# Codex CLI: features, protocols, quickstart

## TL;DR

Codex CLI is OpenAI's Apache-2.0 coding agent that runs locally in the terminal, sharing configuration with the Codex IDE extension and desktop app. It edits code inside an OS-level sandbox, connects to MCP servers and can spawn parallel subagents. It suits developers with a ChatGPT plan or an OpenAI API key.

## Key facts

| Field | Value |
| --- | --- |
| Type | Harness |
| Languages / SDKs | Rust, TypeScript, Python |
| License | Apache-2.0 |
| Pricing model | [Open core](https://learn.chatgpt.com/docs/pricing) |
| Orchestration pattern | Supervisor |
| GitHub stars | 127,360 (as of 2026-09-30) |
| GitHub forks | 19,899 |
| Last push | 2026-09-30 |
| Latest release | rust-v0.159.2 |
| Repository | [openai/codex](https://github.com/openai/codex) |
| Website | [learn.chatgpt.com](https://learn.chatgpt.com/docs/codex/cli) |
| Documentation | [learn.chatgpt.com](https://learn.chatgpt.com/docs) |
| Last verified | 2026-09-30 |

## Key features

- Subagent workflows are on by default in current releases: ask Codex to spawn agents in parallel and it collects their results into one response; /agent switches between agent threads. ([source](https://learn.chatgpt.com/docs/agent-configuration/subagents))
- Custom agents are TOML files in .codex/agents/ or ~/.codex/agents/ with a name, description, developer_instructions and optional model, reasoning effort, sandbox_mode and MCP servers; built-ins are default, worker and explorer. ([source](https://learn.chatgpt.com/docs/agent-configuration/subagents))
- OS-level sandbox with read-only, workspace-write and full-access modes plus approval policies; network access is off by default in workspace-write. ([source](https://learn.chatgpt.com/docs/agent-approvals-security))
- Auto-review can hand eligible sandbox-escalation approvals to a separate reviewer agent instead of the user. ([source](https://learn.chatgpt.com/docs/sandboxing/auto-review))
- MCP client for stdio and Streamable HTTP servers with bearer or OAuth auth, configured in config.toml or with codex mcp add. ([source](https://learn.chatgpt.com/docs/extend/mcp))
- Layered AGENTS.md instructions from the Codex home directory down to the working directory. ([source](https://learn.chatgpt.com/docs/agent-configuration/agents-md))
- A TypeScript SDK (Node 18+) and a Python SDK (3.10+) start, continue and resume local Codex threads from CI or internal tools. ([source](https://learn.chatgpt.com/docs/codex-sdk))

## Architecture and orchestration pattern

Pattern: Supervisor.

Codex CLI is a Rust binary that runs one agent thread per session against your local checkout. Commands the model generates run under an OS-level sandbox, and an approval policy decides when Codex must stop and ask. The same configuration (`~/.codex/config.toml` or a trusted project's `.codex/config.toml`) is shared with the IDE extension and the ChatGPT desktop app, and `codex app-server` exposes the agent over a JSON-RPC protocol for rich clients.

Multi-agent work is supervisor-style. When you ask for parallel work, or when AGENTS.md or a skill asks for it, the main thread spawns subagents (built-in `default`, `worker`, `explorer`, or custom TOML agents), each in its own agent thread with its own model and reasoning settings. The main thread waits for the requested results and returns a consolidated answer; `[agents]` settings cap concurrent threads and set default subagent models. Subagents inherit the parent's sandbox policy and live approval overrides unless a custom agent sets its own `sandbox_mode`.

There is no separate long-term memory store in the CLI docs: persistent guidance comes from AGENTS.md files, concatenated from global to project scope up to 32 KiB by default. For parallel sessions that edit the same repository, the docs point to Git worktrees.

### Human in the loop

Two settings control human oversight: the sandbox mode (`read-only`, `workspace-write`, `danger-full-access`) and the approval policy (`on-request` asks before leaving the sandbox, using the network or other escalations; `never` never asks). `/permissions` switches mode mid-session. Destructive MCP or app tool calls that advertise a destructive annotation always need approval. With subagents, approval requests from inactive agent threads appear in an overlay that names the source thread; press `o` to open it before approving, rejecting or answering. You can ask Codex to steer or stop a running subagent. In non-interactive runs an action needing fresh approval fails and the error returns to the parent. Auto-review can replace the human reviewer with a reviewer agent for eligible requests.

## Protocols

| Protocol | Support | Evidence | Note |
| --- | --- | --- | --- |
| MCP | Yes (checked 2026-09-30) | [link](https://learn.chatgpt.com/docs/extend/mcp) | Client only: STDIO and Streamable HTTP servers (bearer and OAuth auth) via config.toml or codex mcp add; the former codex mcp-server server mode has been removed in favour of the app-server protocol. |
| A2A | Unknown (checked 2026-09-30) | — | No A2A mention in the README or the docs llms.txt index; GitHub code search for a2a in openai/codex only matched unrelated strings (base64 data), and agent2agent returned nothing. |
| AG-UI | Unknown (checked 2026-09-30) | — | No AG-UI mention in the README, docs llms.txt index or code search, and Codex is not in the AG-UI README integration list. |

## Best for

- Terminal coding in a local repository with sandboxed command execution and approval prompts. ([shortlist](https://multiagentguide.top/best/coding-agents.md))
- Parallel review or exploration of a codebase with read-only custom subagents that report back to one thread. ([shortlist](https://multiagentguide.top/best/coding-agents.md))
- Scripting Codex from CI or internal tools through codex exec, the TypeScript SDK or the Python SDK. ([shortlist](https://multiagentguide.top/best/typescript.md))
- Organisations that distribute managed configuration and requirements to local Codex clients. ([shortlist](https://multiagentguide.top/best/enterprise-governance.md))

## Not for

- Integrations that relied on running Codex as an MCP server; that mode was removed.
- Write-heavy parallel edits in one checkout; the docs warn simultaneous agent edits can conflict.
- Cross-framework agent networks that need A2A or AG-UI; neither is documented.

## Quickstart

```sh
npm install -g @openai/codex
```

Install verified 2026-09-30 (temp dir, Node v22.22.3, macOS arm64: local `npm i @openai/codex` (no -g) ok, `npx --no-install codex --version` ok, @openai/codex 0.159.2. The official command uses `-g`; the same package was installed locally. Packages came from the registry.npmmirror.com mirror, so the version is the one that mirror served on this date. Install and import check only; not a functional test.).

```bash
npm install -g @openai/codex
codex                          # first run: choose Sign in with ChatGPT

# a read-only reviewer that subagent workflows can spawn
mkdir -p .codex/agents
cat > .codex/agents/reviewer.toml <<'EOF'
name = "reviewer"
description = "Reviews diffs for correctness, security and missing tests."
sandbox_mode = "read-only"
developer_instructions = """
Report concrete defects with file and line. Do not edit files.
"""
EOF

codex mcp add context7 -- npx -y @upstash/context7-mcp
codex --sandbox workspace-write --ask-for-approval on-request
# in the session: "Fix the failing parser test, then spawn reviewer and wait for it"
```

### Common pitfalls

- The npm package pulls a per-platform binary as an optional dependency; npm registry metadata lists `@openai/codex@0.159.2-darwin-arm64` at about 332 MB unpacked (https://registry.npmjs.org/@openai/codex/0.159.2-darwin-arm64). The standalone installer (`curl -fsSL https://chatgpt.com/codex/install.sh | sh`) is the alternative.
- Using an API key instead of ChatGPT sign-in needs extra setup (see the auth docs).
- `approval_policy = "untrusted"` is no longer supported; use `read-only` with `on-request` instead.
- `codex mcp-server` and the `codex-mcp-server` binary were removed; migrate integrations to `codex app-server`, which the docs call experimental and not supported for production.
- Subagent workflows use more tokens than single-agent runs, and non-interactive runs fail any action that needs a new approval.

Official quickstart: https://learn.chatgpt.com/docs/codex/cli

## Pros

- Apache-2.0 licensed source in a public repository. ([source](https://github.com/openai/codex))
- Sandboxing is enforced by the operating system, with no network access and workspace-only writes by default in the CLI. ([source](https://learn.chatgpt.com/docs/agent-approvals-security))
- Custom agents can pin their own model, reasoning effort, sandbox mode and MCP servers. ([source](https://learn.chatgpt.com/docs/agent-configuration/subagents))
- One config.toml (including MCP servers) is shared by the CLI, IDE extension and desktop app. ([source](https://learn.chatgpt.com/docs/extend/mcp))
- codex exec runs Codex from scripts and CI pipelines without the interactive UI. ([source](https://learn.chatgpt.com/docs/codex/cli))

## Cons

- The MCP server mode (codex mcp-server) was removed, so integrations that called Codex as an MCP tool must move to the app-server protocol. ([source](https://learn.chatgpt.com/docs/mcp-server))
- The app-server protocol that replaces it is documented as experimental and not supported for production workloads. ([source](https://learn.chatgpt.com/docs/mcp-server))
- Subagent workflows consume more tokens, and the docs caution that parallel write-heavy work can create conflicts. ([source](https://learn.chatgpt.com/docs/agent-configuration/subagents))
- The custom agent file format is described as possibly evolving. ([source](https://learn.chatgpt.com/docs/agent-configuration/subagents))
- Config churn: the untrusted approval policy was retired and existing configs must migrate. ([source](https://learn.chatgpt.com/docs/agent-approvals-security))

## Alternatives

- [Claude Code](https://multiagentguide.top/tools/claude-code.md)
- [OpenCode](https://multiagentguide.top/tools/opencode.md)
- [Gemini CLI](https://multiagentguide.top/tools/gemini-cli.md)
- [Cline](https://multiagentguide.top/tools/cline.md)
- [Aider](https://multiagentguide.top/tools/aider.md)

## FAQ

### Does Codex CLI support MCP?

Yes, as a client for STDIO and Streamable HTTP servers. Running Codex itself as an MCP server was removed; use codex app-server instead. A2A and AG-UI support are not documented.

### Is Codex CLI free?

The CLI is Apache-2.0 open source. Using it needs a ChatGPT plan sign-in or an OpenAI API key; usage and plan prices are on the Codex pricing page.

### Can Codex run multiple agents?

Yes. Current releases enable subagent workflows by default: Codex spawns agents in parallel on request, each in its own thread, and merges their results. Custom agents are defined in TOML files.

### What language is Codex written in?

The CLI is built from a Rust Cargo workspace; the SDKs are TypeScript and Python.

## Sources

- [openai/codex repository (README)](https://github.com/openai/codex)
- [Codex documentation](https://learn.chatgpt.com/docs)
- [Codex CLI (install)](https://learn.chatgpt.com/docs/codex/cli)
- [Subagents and custom agents](https://learn.chatgpt.com/docs/agent-configuration/subagents)
- [Agent approvals and security](https://learn.chatgpt.com/docs/agent-approvals-security)
- [Auto-review](https://learn.chatgpt.com/docs/sandboxing/auto-review)
- [Model Context Protocol](https://learn.chatgpt.com/docs/extend/mcp)
- [Codex MCP server removal](https://learn.chatgpt.com/docs/mcp-server)
- [Codex app server](https://learn.chatgpt.com/docs/app-server)
- [Codex SDK](https://learn.chatgpt.com/docs/codex-sdk)
- [AGENTS.md](https://learn.chatgpt.com/docs/agent-configuration/agents-md)
- [Worktrees](https://learn.chatgpt.com/docs/environments/git-worktrees)
- [Pricing](https://learn.chatgpt.com/docs/pricing)
- [npm registry metadata: @openai/codex 0.159.2-darwin-arm64](https://registry.npmjs.org/@openai/codex/0.159.2-darwin-arm64)
- [AG-UI README integration list](https://github.com/ag-ui-protocol/ag-ui)

## Unknown fields

protocols.a2a and protocols.agui: searched the README, the docs llms.txt index (learn.chatgpt.com), GitHub code search in openai/codex (a2a, agent2agent, ag-ui) and the AG-UI README integration list; no support found. The only a2a code hits were unrelated strings.

Corrections or removal requests: support@multiagentguide.top

---

Data as of 2026-09-30. Not affiliated with listed projects. HTML version: https://multiagentguide.top/tools/codex