OpenAI product dossier 062
Codex: Agent Architecture, Tools and Product System
How models, the agent loop, local and cloud environments, repository context, tools, permissions, skills, plugins, MCP, subagents, worktrees, automation and developer interfaces fit together.· verified
Part I — System analysis. Sections 01–14 explain what Codex is, where it runs, how the agent loop produces and verifies changes, and where authority and trust boundaries sit. The exhaustive command inventory is deliberately separated into Part II.
01
Codex in one minute
Codex is OpenAI's software-engineering agent system: a model-directed runtime that can inspect a workspace, plan work, call tools, edit files, run commands, verify results and return reviewable evidence. It is delivered through the ChatGPT desktop app, command-line interface, IDE extension, web and cloud execution, Remote and automation interfaces.
Codex is not one model, one application or a synonym for the OpenAI API. The selected model supplies reasoning; the agent harness manages the conversation and tool loop; the environment holds code and processes; the sandbox constrains execution; approvals govern boundary crossings; skills, plugins and MCP extend behaviour and reach.
Original Codex modelAug 2021API model trained for code
Cloud coding agentMay 2025Delegated repository tasks
Current product surfaces6Desktop, Remote, web, CLI, IDE, cloud
Execution choicesLocal + cloudPolicy and environment differ
Canonical formula. Codex = selected OpenAI model + agent runtime + context + tools + execution environment + controls + integrations + product interface. Codex product capability ≠ underlying model capability. A model upgrade changes reasoning capability; it does not by itself change the permissions, repository, network or verification boundary.
Essential questions
| Question | Concise answer |
|---|---|
| Is Codex a model, an application or an agent system? | Today it is an agent system delivered through several applications and developer interfaces. It uses models from the Codex catalogue, but the harness, tools, policies and environments are separate system layers. |
| Which model does Codex use? | The active catalogue and account determine the choices. The user can select a model and, where supported, reasoning effort and service tier. Product behaviour must therefore not be inferred from a model name alone. |
| Where does code execute? | Local sessions run tools on the user's machine inside the configured sandbox. Cloud tasks run in an isolated hosted environment. Remote steers a Codex session from another interface; it does not make every local process a cloud process. |
| What can Codex access? | Only what the current surface, workspace, filesystem roots, network policy, credentials and connected tools expose. Model intent is not execution authority. |
| What is the difference between sandboxing and approvals? | The sandbox is the technical boundary around commands and filesystem or network access. The approval policy decides when Codex must stop and request permission to cross that boundary. |
| What is AGENTS.md? | A repository instruction file whose scoped content is supplied to Codex. It can define project conventions and commands, but it cannot grant operating-system access or override higher-priority policy. |
| How do skills, plugins and MCP differ? | A skill packages task-specific instructions and resources. A plugin packages one or more extension assets for installation and distribution. MCP is a protocol for exposing tools and data. They may be combined, but they are not interchangeable. |
| What are subagents and worktrees? | A subagent is a delegated reasoning context; a worktree is an isolated Git checkout. Subagents divide cognitive work, while worktrees reduce file and branch collisions. |
| What is Codex cloud? | A hosted execution path that checks out a repository into an isolated environment, runs the agent and returns logs, changes and results for review. Its credentials and network policy are configured separately from a local machine. |
| What is the Codex SDK? | A programmatic interface for embedding Codex workflows. App Server exposes the harness to rich clients; MCP Server lets another MCP client call Codex; non-interactive mode supports scripts and CI. |
| Does Codex have Claude Code-style slash commands? | Yes. The CLI and desktop app expose native / commands, but their sets differ. CLI subcommands and keyboard controls are separate control surfaces; Appendix 16 records all three without treating them as synonyms. |
| Can Codex work in parallel? | Yes, through separate tasks, subagents, cloud attempts and worktrees. Parallelism increases throughput only when responsibilities, dependencies and file ownership are divided clearly. |
| Can Codex operate autonomously? | It can complete long multi-step work, but autonomy remains bounded by instructions, tool availability, sandboxing, approvals, credentials, time, context and verification. Human review remains important for consequential changes. |
| What are the principal enterprise risks? | Untrusted instructions, excessive credentials, unsafe commands, data leakage, compromised extensions, weak review and mistaken confidence in incomplete tests. Sections 11 and 14 map the controls and residual risks. |
02
The Codex system
| Canonical layer | Responsibility | Examples | Boundary | Detail |
|---|---|---|---|---|
| 1. Product surfaces | Present, steer and review work. | Desktop, Remote, web, CLI, IDE and cloud. | The interface does not by itself locate execution. | 04 |
| 2. Agent runtime | Assemble context, preserve task state, plan and iterate. | Chats, goals, compaction, subagents and attempts. | Runtime coordination does not grant tool authority. | 05, 06, 09 |
| 3. Model layer | Reason over evidence and propose outputs or actions. | Selected model, reasoning effort and service tier. | Model capability is not product capability or execution authority. | 01, 05 |
| 4. Action / control | Select and govern attempted actions. | Tool routing, sandbox, approvals, rules and credentials. | Proposal, authorisation and execution are separate events. | 07, 11 |
| 5. Execution layer | Read or change files and run processes. | Patch, shell, tests, Git, browser and computer use. | The executing host owns actual side effects. | 05, 07 |
| 6. Extensions / integrations | Add behaviour, context, lifecycle actions and connected systems. | AGENTS.md, skills, plugins, hooks, MCP and apps. | Each extension adds its own trust and permission boundary. | 06, 08, 10 |
| 7. Environment | Hold code, data, processes, network and external connections. | Local workspace, cloud container, repository and services. | Local and cloud have separate identity, persistence and rollback boundaries. | 04, 11 |
03
From code model to agent platform
| Date | Release type | Milestone | What changed | Meaning |
|---|---|---|---|---|
| 10 Aug 2021 | Model / API | Original OpenAI Codex | A GPT-derived model translated natural language into code and powered the first GitHub Copilot preview. | Codex began as a model capability, not the present agent product. |
| 7 May 2025 | Product | Codex CLI announced | An open-source terminal coding agent brought repository inspection, editing and command execution into a local loop. | Established the local harness and user-controlled workspace boundary. |
| 16 May 2025 | Cloud product | Codex cloud research preview | Parallel delegated tasks ran in isolated cloud environments connected to repositories. | Separated supervision from execution and enabled background work. |
| Aug–Oct 2025 | Model + surfaces | GPT-5-Codex, IDE extension and GA | Codex-specific model optimisation and broader local/cloud workflow integration arrived. | Joined model, CLI, IDE and cloud into one product family. |
| Nov 2025 | Platform | Codex SDK and App Server | Developers gained programmatic and client-facing access to the agent harness. | Moved Codex from finished product towards reusable agent infrastructure. |
| 2 Feb 2026 | Product surface | Codex desktop app | A graphical multi-task workspace added projects, chats, worktrees, review and local/cloud handoff. | Made parallel agent work visible and operable beyond the terminal. |
| 2026 | Extension / orchestration | Skills, plugins, hooks, Remote and subagents | Reusable capabilities, connected systems, lifecycle automation and delegated contexts broadened the harness. | Codex became a general workspace-agent platform centred on software work. |
| 24 Aug 2026 | Research cut | Current documented system | Desktop, Remote, web, CLI, IDE and cloud share a growing set of agent, security and extension concepts. | Surface capability remains uneven; the live documentation is authoritative. |
Lineage boundary. The 2021 Codex model and the current Codex product share a name, but the modern system is a multi-surface agent harness using a changing model catalogue. Product, model and platform milestones are labelled separately.
04
Product surfaces and execution locations
Current as of 24 August 2026. Surface, runtime and tool location are independent dimensions. The same interface may supervise local work in one task and a hosted environment in another.
| Surface | Primary role | Execution | Best fit | Boundary |
|---|---|---|---|---|
| ChatGPT desktop app | Graphical workspace for projects, chats, tasks, worktrees, diffs and integrated terminals. | Local or cloud, selected per task. | Parallel supervised engineering and visual review. | App access does not erase workspace or cloud policy. |
| Remote | Start, steer and inspect engineering work from another device. | Connected Codex environment. | Continuing work away from the main workstation. | Remote control is an interface link, not unrestricted machine access. |
| ChatGPT web | Browser access to projects and compatible Codex workflows. | Primarily hosted services. | Repository-connected tasks without a local terminal. | Its composer commands differ from CLI slash commands. |
| Codex CLI | Keyboard-first interactive and non-interactive agent. | Local workspace; optional remote/cloud commands. | Repository work, automation and terminal-native control. | Shell commands inherit the active sandbox and approval policy. |
| IDE extension | Editor-aware chat, code selection and file context. | Local or connected Codex path. | Focused iteration while editing. | Open editor context is not automatically the entire repository. |
| Codex cloud | Hosted background tasks and parallel attempts. | Isolated cloud environment. | Delegated work, reproducible setup and asynchronous review. | Secrets, setup and network rules are environment-specific. |
Local versus cloud execution
| Dimension | Local execution | Remote / cloud execution |
|---|---|---|
| Workspace | The user's accessible local repository and working tree. | A provisioned container checks out the selected repository branch or commit. |
| Compute | User machine, local operating system and installed tools. | Managed container image plus configured setup and maintenance scripts. |
| Network | Local sandbox, policy and machine configuration govern access. | Setup runs with internet access; agent access is off by default unless configured as limited or unrestricted. |
| Credentials | User-controlled credentials exposed to the active local process and integrations. | Environment values are configured explicitly; cloud secrets are removed before the agent phase after setup. |
| Persistence | Files remain in the local working tree; process lifetime depends on the session and host. | Task and cached-container lifetime are environment-dependent; cache is not the system of record. |
| Result | Local file changes, command output, tests and Git diff. | Answer and reviewable diff, with an optional pull request or application of the cloud diff locally. |
Location rule. Ask three separate questions: where the interface runs, where the agent runtime runs and where each tool executes. These locations can differ in one workflow.
05
How a task moves through Codex
| Authority | Owned by | Decision | What it cannot prove |
|---|---|---|---|
| Instruction authority | User, project and policy layers | What outcome and constraints should guide the task. | That the requested action is safe or technically possible. |
| Reasoning authority | Selected model within the harness | What to inspect, infer and attempt next. | That a requested tool action has permission to execute. |
| Execution authority | Host, sandbox, approval policy and external service | Whether and where a side effect occurs. | That the change is correct or complete. |
| Verification authority | Tests, builds, diffs, logs and human reviewers | Whether specified observable properties hold. | Correctness outside the evidence and scenarios examined. |
Verification is a subsystem, not an afterthought
| Stage | Question | Typical evidence | Failure if omitted |
|---|---|---|---|
| Generation | What code or configuration should change? | Proposed patch, created files or migration plan. | Plausible output without proof that it can run. |
| Execution | Can the environment perform the requested operation? | Command exit codes, process output and resulting files. | Textual code that was never exercised. |
| Verification | Do observable technical properties hold? | Diff inspection, tests, lint, type checks, builds, browser checks and logs. | Undetected regressions, omissions or unintended changes. |
| Evaluation | Does the verified result satisfy the actual request? | Acceptance criteria, scenario coverage and accountable human review. | Passing checks for the wrong or incomplete outcome. |
Central rules. Proposal ≠ authorisation ≠ execution. Model intent is not execution authority. Generating code ≠ verifying that the task is complete. A dependable loop is edit → inspect diff → validate → observe failure → revise → revalidate.
06
Context, instructions and working state
| Context source | Purpose | Scope / lifetime | Limit |
|---|---|---|---|
| User and system instructions | Define the current request, safety and operating constraints. | Conversation or managed runtime. | Conflicts are resolved by instruction priority, not by recency alone. |
| AGENTS.md | Record repository conventions, commands and local guidance. | Directory tree and applicable descendants. | Text guidance cannot grant permissions or make stale instructions true. |
| Workspace evidence | Files, Git state, tests, logs and configuration inspected by tools. | Current accessible environment. | Uninspected or inaccessible material is absent from the model's evidence. |
| Skills | Load task-specific procedures, references, scripts and assets. | Selected turn or workflow. | A skill influences behaviour; it does not automatically execute actions. |
| Conversation state | Preserve requests, tool observations, decisions and partial results. | Chat or task. | Long sessions require compaction; detail may be summarised. |
| Memories and history | Reuse durable preferences or locate previous work where enabled. | User, project or product feature. | Availability and retention depend on surface and policy. |
| Connected sources | Add external files, data and application context. | Connection, account and permission scope. | Freshness and completeness remain source-specific. |
Context is selected evidence. A large context window does not mean Codex has read every file, retained every earlier token or discovered every relevant dependency. Retrieval, inspection, compaction and source quality still determine what the model can reason over.
07
Tools and side-effect ownership
| Tool class | Typical operations | Executor | Control boundary | Preferred evidence |
|---|---|---|---|---|
| Workspace read/search | List files, search text, inspect configuration and Git state. | Local or cloud runtime. | Readable roots and ignore rules. | Exact paths, lines and repository state. |
| Patch / file write | Create or modify source and configuration. | Runtime filesystem tools. | Writable roots, policy and review. | Diff plus focused tests. |
| Shell / terminal | Build, test, format, run scripts and inspect processes. | Sandboxed host process. | Sandbox, approvals, network and credentials. | Exit code, logs and reproducible command. |
| Browser / computer use | Navigate applications, observe screens and interact with UI. | Browser or desktop automation environment. | Session, domains, login and approval policy. | Rendered state, screenshots and console/network checks. |
| Web search | Find and retrieve current public information. | Search and retrieval service. | Internet policy, source restrictions and citation rules. | Opened primary source and retrieval date. |
| MCP and apps | Call typed external tools and read connected resources. | External server or connector. | Connection auth, exposed schema and server policy. | Tool result plus target-system confirmation. |
| Media generation | Create or edit images and other supported media. | Specialised model or service. | Tool availability and content policy. | Rendered asset and acceptance criteria. |
| Git / hosting integration | Review diffs, inspect pull requests and publish approved changes. | Local Git or connected provider. | Repository permissions, branch rules and user authority. | Commit, check result or provider record. |
Safer interface principle. Prefer typed APIs, repository-native commands and narrow file operations over free-form GUI control when they provide the same outcome. Computer use is valuable when no reliable structured interface exists, but it expands ambiguity and attack surface.
08
Extensions: what each mechanism actually does
| Mechanism | Primary object | Best use | Not equivalent to | Key risk |
|---|---|---|---|---|
| AGENTS.md | Scoped repository instructions | Stable project conventions and commands. | A tool, plugin or permission grant. | Stale or malicious repository guidance. |
| Skill | Instruction package with optional references, scripts and assets | Repeatable specialist workflows. | An MCP connection or automatic hook. | Over-broad instructions or unreviewed scripts. |
| Plugin | Installable bundle | Distributing skills, MCP servers and optional UI or metadata together. | A single skill or the agent runtime. | Supply-chain and permission expansion. |
| MCP | Protocol connection to tools and resources | Typed access to external systems. | Procedural knowledge or policy. | Server trust, credentials and prompt injection. |
| App / connector | Managed external integration | Using a supported service or account from the product. | General internet access. | Account scope and unintended writes. |
| Hook | Lifecycle-triggered deterministic action | Validation, logging or policy around defined events. | Model-selected reasoning. | Hidden side effects or untrusted hook changes. |
| Rule / managed policy | Enforced decision constraint | Allowing, prompting or blocking actions. | An instruction that the model may interpret. | Misconfiguration that is too permissive or obstructive. |
Separation rule. Skills change what Codex knows how to do; MCP and apps change what systems it can reach; plugins package extensions; hooks react to lifecycle events; rules constrain actions. Combining them does not collapse their security boundaries.
09
Orchestration, parallelism and isolation
| Object | What it isolates | What it shares | Use | Failure mode |
|---|---|---|---|---|
| Chat / thread | Conversation and working context. | Workspace and configured tools may remain shared. | One coherent line of work. | Long context, drift or hidden dependency. |
| Side chat | Temporary question from the main transcript. | Current environment and selected context. | Clarification without derailing the task. | Important decisions fail to return to the main work. |
| Subagent | Delegated reasoning context and task responsibility. | Tools or workspace according to runtime configuration. | Independent investigation or implementation unit. | Duplicate work, conflicting edits or missing synthesis. |
| Worktree | Git checkout, branch and files. | Repository history and external services. | Parallel implementation without local file collisions. | Integration conflicts or stale base. |
| Cloud attempt | Hosted environment and execution run. | Repository snapshot and configured setup. | Alternative approaches or background delegation. | Divergent environment, credentials or dependency state. |
| Goal | Persistent objective and progress state. | Active task context and tools. | Long-running work that spans turns. | Vague objectives or unchecked completion claims. |
| Handoff / Remote | Supervision surface. | Underlying task or environment. | Continue or review from another device or surface. | Mistaking interface movement for environment migration. |
Coordination rule. A subagent divides reasoning; a worktree divides files; a cloud attempt divides execution; a handoff changes supervision. Reliable parallel work requires explicit ownership, dependency ordering and final integration checks.
10
Codex as a developer platform
Current as of 24 August 2026. OpenAI's controlled maturity vocabulary is Under development, Experimental, Beta and Stable. Where a feature lacks a published maturity label, this article says Documented rather than silently promoting it to Stable.[20]
| Interface | Status | Consumer | Control level | Typical use | Boundary |
|---|---|---|---|---|---|
| Codex SDK | Documented | Application developer | Programmatic task and event interface. | Embed Codex workflows in services and internal tools. | The application still owns identity, product UX and policy. |
| App Server | Experimental | Rich local client | Structured protocol over the Codex harness. | Build custom interfaces with thread, turn and event control. | Experimental interfaces can change; client must handle lifecycle state. |
| MCP Server mode | Documented; CLI command Stable | Another MCP-capable agent or client | Codex exposed as an MCP tool. | Delegate coding work from a wider agent system. | The caller and Codex retain separate permissions and context. |
| Non-interactive CLI | Stable command | Script or CI system | Command, JSONL and exit-code interface. | Repeatable automation, review and batch tasks. | Unattended runs require narrow sandbox and credential design. |
| GitHub Action | Documented | Repository workflow | Event-triggered hosted automation. | Review, issue handling and approved repository changes. | Workflow permissions and untrusted event content are critical. |
| Cloud task API / integrations | Surface-dependent | Product or external workflow | Hosted task creation and result retrieval. | Asynchronous background work from GitHub, Slack or Linear. | Availability, repository access and organisation policy vary. |
Platform boundary. The Responses API and Agents SDK are OpenAI's general agent-building primitives. Codex SDK, App Server and Codex automation expose the specialised coding harness. They can interoperate, but they are not the same product layer.
11
Security and permission model
Trust model. Codex interprets instructions and evidence from sources with different authority and reliability. Authoritative instructions can still be mistaken; untrusted content can contain plausible commands or prompt injection. Trust classification therefore works with enforcement, not instead of it.
| Trust class | Examples | How Codex should treat it | Enforcement boundary |
|---|---|---|---|
| Instruction authority | User request, system constraints and managed organisational policy. | Resolve by documented priority and scope; do not infer broader authorisation. | Policy still cannot bypass operating-system or service enforcement. |
| Conditionally trusted host context | Known local environment, reviewed configuration, approved tools and credentials. | Use only within their configured scope and current state. | Sandbox, filesystem roots, network rules and credential permissions. |
| Potentially untrusted inputs | Repository text, dependencies, issues, terminal output, web pages, retrieved files, MCP results and generated commands. | Treat as evidence, not higher-priority instructions; inspect before execution. | Approval, containment, source checking and least-privilege access. |
| Produced artefacts | Generated code, patches, commands, test output and completion claims. | Verify independently against task requirements and observable results. | Diffs, tests, builds, logs, review and audit records. |
| Control | Protects | How it works | Residual risk |
|---|---|---|---|
| Filesystem sandbox | Host files outside allowed roots. | Constrains reads and writes for spawned commands and built-in operations. | Allowed workspace files may still contain secrets or destructive scripts. |
| Network policy | External data flow and dependency retrieval. | Disables, restricts or approves network use according to environment. | An allowed destination can still return malicious content. |
| Approval policy | Boundary crossings and consequential actions. | Pauses for human authorisation under configured conditions. | Approval fatigue and misleading command descriptions. |
| Automatic review | Suspicious commands that policy might otherwise allow. | Reviews an action and can deny it before execution. | False positives and false negatives; not a proof of safety. |
| Rules and managed configuration | Organisation-wide consistency. | Require, deny or constrain settings and command patterns. | Policy gaps or overly broad exceptions. |
| Credential scoping | Repositories and external services. | Supplies only required identities to the selected environment. | Agent can misuse credentials within their granted scope. |
| Environment isolation | Local machine and parallel tasks. | Uses cloud containers or Git worktrees to limit interference. | Shared upstream services, secrets and merge paths remain connected. |
| Diff, tests and human review | Correctness and unintended changes. | Examines produced artefacts before publication. | Incomplete tests and reviewers can miss semantic or supply-chain risk. |
Defence in depth. Sandboxing limits technical capability; approvals add human control; rules add policy; credentials define external reach; verification checks the result. No single layer substitutes for the others.
12
Users, buyers and workflow fit
| User / buyer | Primary job | Best-fit surface | Value mechanism | Adoption constraint |
|---|---|---|---|---|
| Individual developer | Implement, debug, refactor and learn a codebase. | CLI, IDE or desktop. | More work completed per engineering hour. | Trust, review discipline and usage limits. |
| Software team | Parallelise backlog, reviews and maintenance. | Desktop projects, cloud tasks and Git integrations. | Throughput across many independent work units. | Coordination, conventions and merge quality. |
| Platform / SRE team | Operate repositories, infrastructure and incident workflows. | CLI, cloud and controlled integrations. | Faster diagnosis and repeatable automation. | Credential scope and production risk. |
| Enterprise engineering organisation | Standardise governed agent-assisted development. | Managed desktop, IDE, cloud and policy controls. | Scaled productivity with audit and administration. | Compliance, data residency and measurable quality. |
| Open-source maintainer | Triage issues, update dependencies and review contributions. | GitHub integration and cloud tasks. | Automates high-volume maintenance work. | Untrusted contribution content and limited maintainer time. |
| Developer-tool vendor | Embed an agentic coding loop in another product. | SDK, App Server or MCP Server. | Uses the Codex harness without recreating the full runtime. | Interface maturity, product differentiation and policy ownership. |
| Non-engineering technical professional | Analyse data, automate files or build internal tools. | Desktop app and plugins. | Turns natural-language objectives into executable workflows. | Domain validation and accidental side effects. |
Commercial boundary. Codex is packaged through ChatGPT plans, usage entitlements and enterprise arrangements rather than as one standalone unit with one disclosed price. Pricing and limits change faster than the architecture and are deliberately excluded from this dossier.
13
Direction: from coding assistant to workspace agent
| Direction | Evidence in the product | Potential | Dependency | Status |
|---|---|---|---|---|
| Longer autonomous work | Goals, long-running tasks, background terminals, compaction and cloud execution. | Complete larger engineering units with less continuous steering. | Reliable planning, verification and recovery. | Operational and expanding |
| Parallel agent operations | Subagents, worktrees, cloud attempts and multi-task desktop UI. | Scale one developer across independent workstreams. | Task decomposition and integration discipline. | Operational and expanding |
| Local / cloud continuity | Desktop, CLI, Remote, cloud and handoff paths. | Move supervision without restarting the work. | Consistent context, environment and credential handling. | Operational with surface differences |
| Composable capability system | Skills, plugins, MCP, apps, hooks and rules. | Turn Codex into a domain-specific workspace agent. | Extension quality, trust and discovery. | Operational; ecosystem developing |
| Codex as infrastructure | SDK, App Server, MCP Server and non-interactive mode. | Power third-party and internal agent products. | Stable protocols and clear policy ownership. | Mixed stable and experimental |
| Beyond code | Browser, computer use, files, data, media and connected apps. | Execute end-to-end knowledge and operational workflows. | Domain-specific controls and validation. | Emerging from coding core |
Strategic synthesis. Codex is evolving towards a software-engineering agent platform in which the model is only one layer. Differentiated value increasingly comes from orchestration, environment integration, controlled execution, verification and review. The competitive unit is therefore shifting from model quality alone towards verified end-to-end task completion under real software-development constraints.
14
Limits and unresolved questions
- Fast-moving surface. Commands, models, plan entitlements and experimental features change frequently; live product discovery remains authoritative.
- Uneven capability. Desktop, web, CLI, IDE and cloud do not expose identical commands or environment controls.
- Verification gap. Passing tests can coexist with incorrect requirements, missing scenarios or unsafe external effects.
- Prompt injection. Repositories, web pages, issues and connected systems may contain untrusted instructions aimed at the agent.
- Credential concentration. A capable agent with broad credentials can produce large side effects quickly.
- Parallelism cost. More agents can increase duplicated work, merge conflicts and review load when ownership is unclear.
- Context loss. Retrieval and compaction trade completeness for tractability; important details can be omitted or summarised incorrectly.
- Extension supply chain. Skills, plugins, MCP servers and hooks add code, instructions and third-party trust.
- Cloud reproducibility. Hosted and local environments may diverge in dependencies, secrets, operating system and network access.
- Economic opacity. Productivity and quality benefits vary by task; usage, review and integration costs must be measured in the user's environment.
15
Primary sources
- Codex developer commandsComplete documented CLI command, flag, interactive shortcut and slash-command reference.
- Codex desktop slash commandsComposer commands available in the ChatGPT desktop app.
- SandboxRelationship between technical sandbox boundaries and approval policies.
- Agent approvals and securityLocal execution risk, approval modes and safe operating patterns.
- AGENTS.mdRepository instruction discovery and directory scope.
- SubagentsDelegated contexts, agent definitions and orchestration.
- Git worktreesFile and branch isolation for parallel tasks.
- Build skillsSkill structure, progressive disclosure, scripts and assets.
- Build pluginsPlugin packaging and installable extension boundaries.
- Model Context ProtocolMCP server configuration, tools, resources and authentication.
- HooksLifecycle automation and trust model.
- Codex CLIInteractive local agent and terminal workflow.
- Codex cloud environmentsHosted repository checkout, setup, internet policy, secrets, container caching, execution loop and returned diff.
- RemoteRemote supervision and continuation of Codex work.
- Codex SDKProgrammatic embedding of Codex workflows.
- App ServerStructured client protocol for the Codex harness.
- Codex MCP ServerExposing Codex to another MCP client.
- Non-interactive modeScripted and CI execution through codex exec.
- Codex GitHub ActionRepository automation and workflow permissions.
- Feature maturityStable, beta and experimental labels used by the product.
- Codex changelogProduct and CLI release chronology.
- Introducing Codex, 16 May 2025Cloud coding-agent launch and isolated task model.
- Codex configuration referenceConfiguration layers, project trust, approval policy, sandbox and agent settings.
Research cut. Facts and command availability were re-checked against official OpenAI documentation on 24 August 2026 at 19:21 ICT. Surface-dependent and experimental capabilities are labelled; pricing is excluded.
Part II — Technical reference. The system analysis ends above. This appendix preserves exact operator controls for practical use, but it is subordinate to the architecture: commands are grouped first by why they exist, then listed by surface.
16
Appendix: Codex command reference
Yes—these are the Codex equivalents of Claude Code's / commands. They are controls for the Codex product, not prompts sent to the model as ordinary text. The CLI, desktop app, CLI executable and IDE command palette expose different sets, so this appendix keeps them separate.
Operator taxonomy
| Priority class | Why it exists | Representative controls | Read first when |
|---|---|---|---|
| Core | Choose the model and operating mode; inspect state; attach context; review changes. | /model, /permissions, /status, /mention, /diff, /review | Starting ordinary interactive work. |
| Advanced | Manage long, parallel or isolated work. | /goal, /agent, /subagents, /worktree, /compact, /fork | Tasks span contexts, agents or branches. |
| Automation | Run Codex from scripts, CI or another application. | codex exec, SDK, App Server, MCP Server and GitHub Action | No interactive operator is guaranteed to be present. |
| Security | Constrain execution, network, credentials and boundary crossings. | /permissions, sandbox controls, codex execpolicy, rules and managed configuration | Actions can change files, call services or use credentials. |
| Integration | Add external tools, data, behaviour and lifecycle actions. | /mcp, /apps, /plugins, /skills and /hooks | The built-in runtime lacks required context or reach. |
| Diagnostic | Explain configuration, processes, usage and failures. | /debug-config, /ps, /usage, codex doctor and codex debug | Observed behaviour differs from expectation. |
Status and version boundary · current as of 24 August 2026. Stable, Beta, Experimental and Under development follow OpenAI's published maturity vocabulary. Command availability additionally depends on product surface, installed version, operating system, account, policy and feature flags. Unlabelled availability is not evidence of Stable status.
Codex CLI built-in slash commands
| Command | Purpose | Surface / boundary |
|---|---|---|
| /permissions | Set what Codex can do without asking first. | CLI; policy can restrict choices. |
| /ide | Include open files, selection and IDE context. | CLI with IDE integration. |
| /keymap | Inspect and remap terminal UI shortcuts. | CLI; persists to configuration. |
| /vim | Toggle Vim behaviour in the composer. | CLI. |
| /setup-default-sandbox | Configure the elevated default sandbox. | Windows only. |
| /sandbox-add-read-dir | Add read access for an external directory. | Windows only; read access, not write. |
| /agent / /subagents | Switch the active agent thread. | When subagents exist. |
| /apps | Browse apps and insert one into the prompt. | Availability depends on installed connections. |
| /plugins | Browse and manage installed or discoverable plugins. | Plugin support and policy required. |
| /hooks | Inspect, trust or disable lifecycle hooks. | Hook-enabled releases. |
| /clear | Clear the terminal and start a fresh chat. | Resets visible UI and chat context. |
| /rename | Rename the current saved chat. | CLI session metadata. |
| /archive | Archive the current session and exit. | Preserves transcript. |
| /delete | Permanently delete the current session and descendants. | Destructive; exits the CLI. |
| /compact | Summarise the visible chat to release context capacity. | Detail is compressed. |
| /copy | Copy the latest completed Codex output. | Same function as Ctrl+O. |
| /diff | Show tracked and untracked Git changes. | Git workspace. |
| /exit / /quit | Exit the CLI. | Save important work first. |
| /experimental | Toggle experimental features. | Options can change without stable guarantees. |
| /approve | Approve one retry of an automatic-review denial. | Only after a denied action. |
| /memories | Configure memory use and generation. | Feature and policy dependent. |
| /skills | Browse and invoke available skills. | Local, project and plugin skills can vary. |
| /import | Import supported Claude Code or Cursor setup and chats. | Supported external artefacts only. |
| /feedback | Submit feedback and optional diagnostics. | May include selected logs. |
| /init | Generate an AGENTS.md scaffold. | Current project directory. |
| /logout | Clear local authentication credentials. | Shared-machine safety. |
| /mcp | List configured MCP tools and server details. | Use verbose view for connection details. |
| /mention | Attach a file or folder to the chat. | Accessible workspace paths. |
| /model | Select the active model and supported reasoning effort. | Catalogue and account dependent. |
| /fast | Toggle the model catalogue's Fast service tier. | Shown only when supported. |
| /plan | Enter plan mode and optionally send a task. | Separates planning from implementation. |
| /goal | Set, edit, pause, resume, inspect or clear a persistent goal. | Goal-enabled surfaces. |
| /personality | Select a response communication style. | Does not override explicit instructions. |
| /ps | Show background terminals and recent output. | Current session processes. |
| /stop | Stop all background terminals. | Cancels session-started terminal work. |
| /fork | Branch the current chat into a new chat. | Original transcript remains. |
| /app | Continue the session in the desktop app. | macOS or Windows desktop support. |
| /side / /btw | Start a temporary side chat. | Does not interrupt the main transcript. |
| /raw | Toggle raw scrollback mode. | Terminal display only. |
| /resume | Resume a saved chat. | Session inventory. |
| /new | Start a new chat in the same CLI process. | Fresh conversation context. |
| /review | Review the working tree or compare with a base. | Review target and Git state required. |
| /status | Show model, policy, writable roots, context and session details. | Primary configuration check. |
| /usage | Inspect token activity and available rate-limit controls. | Account dependent. |
| /debug-config | Show configuration layers and policy requirements. | Diagnostic output may expose paths. |
| /statusline | Configure footer fields. | Persists TUI configuration. |
| /title | Configure terminal title fields. | Terminal support dependent. |
| /theme | Select syntax-highlighting theme. | Display only. |
| /pets / /pet | Choose or hide a terminal pet. | Cosmetic; TUI availability. |
ChatGPT desktop app slash commands
| Command | Purpose | Boundary |
|---|---|---|
| /approve | Approve one retry after automatic review denies an action. | Only when auto-review is active. |
| /cloud | Run the chat in cloud mode. | Cloud execution must be available. |
| /cloud-environment | Select the cloud environment. | Configured environments only. |
| /compact | Compact the current chat context. | Summarises prior detail. |
| /fast | Toggle a supported Fast service tier. | Catalogue dependent. |
| /feedback | Open feedback and optional log submission. | User confirmation required. |
| /fork | Copy the local chat into a new local chat. | Local chat only. |
| /goal | Set a persistent task goal. | Goal-enabled app versions. |
| /ide-context | Toggle automatic IDE context. | IDE connection required. |
| /init | Generate AGENTS.md for the project. | Project workspace required. |
| /local | Run the chat in the local workspace. | Local environment available. |
| /mcp | Open MCP server status. | Configured servers only. |
| /memories | Configure chat memory use and generation. | Feature availability varies. |
| /model | Select the active model. | Catalogue and account dependent. |
| /personality | Select response style. | Supported models only. |
| /plan | Toggle plan mode. | Multi-step planning surface. |
| /project | Select the project used for new chats. | Configured projects only. |
| /reasoning | Select model reasoning effort. | Model dependent. |
| /review | Start code-review mode. | Working tree or base comparison. |
| /side | Open a temporary side chat. | Main chat remains active. |
| /status | Show chat ID, context usage and rate limits. | Read-only status. |
| /worktree | Run the chat in a new Git worktree. | Git project required. |
CLI executable commands
| Command | Maturity | Purpose |
|---|---|---|
| codex | Stable | Launch the terminal UI with optional prompt, images and global flags. |
| codex app | Stable | Launch or direct the user to the desktop app. |
| codex app-server | Experimental | Run the app-server protocol for client development and debugging. |
| codex apply | Stable | Apply the latest cloud-task diff to the local working tree. |
| codex archive | Stable | Archive a saved session by ID or name. |
| codex cloud | Experimental | Browse or execute cloud chats from the terminal. |
| codex completion | Stable | Generate shell completion scripts. |
| codex debug | Experimental | Inspect models, prompt input or app-server behaviour. |
| codex delete | Stable | Permanently delete a saved session. |
| codex doctor | Stable | Create a diagnostic report for installation, config, authentication and runtime. |
| codex exec | Stable | Run Codex non-interactively for scripts and CI; supports JSONL and resume. |
| codex execpolicy | Experimental | Evaluate whether a rule would allow, prompt or block a command. |
| codex features | Stable | List and persist feature-flag settings. |
| codex fork | Stable | Fork a previous interactive session. |
| codex login | Stable | Authenticate using supported ChatGPT or API routes. |
| codex logout | Stable | Remove stored authentication credentials. |
| codex mcp | Stable | List, add, remove and authenticate MCP servers. |
| codex mcp-server | Stable | Expose Codex as an MCP server over standard input/output. |
| codex plugin | Stable | Install, list and remove plugins from configured marketplaces. |
Interactive keyboard and composer controls
| Control | Action | Boundary |
|---|---|---|
| @ | Search workspace files and add a path to the prompt. | Accessible workspace files. |
| ! prefix | Run a local shell command. | Current sandbox and approval settings apply. |
| Up / Down | Restore draft history. | Composer history. |
| Ctrl+R | Search prompt history. | Press Enter to accept or Esc to cancel. |
| Ctrl+O | Copy the latest completed output. | Equivalent to /copy. |
| Tab while working | Queue a prompt, slash command or shell command for the next turn. | Runs after the current turn completes. |
| Enter while working | Inject new instructions into the current turn. | May redirect active reasoning. |
| Esc twice | Edit the previous user message and fork from that point. | Empty composer required. |
| Ctrl+C | Close the session. | Equivalent exit path. |
Dynamic boundary · checked 24 August 2026. Surface, version, operating system, account, managed policy and experimental flags can change which commands appear. Skills, plugins and connected systems can also add invocable capabilities. Type / in the active surface and use /status or the official developer-command reference as the live authority.