Codex CLI: OpenAI's Production Coding Agent

What is Codex CLI?

Codex CLI (@openai/codex) is a coding agent from OpenAI that runs locally on your computer. It is distributed as a standalone native binary — no Node.js, no Python, no JVM — built from a Rust workspace of 70+ crates totaling approximately 3,805 files (roughly 1,418 Rust source files in the core workspace alone). The project is licensed under the Apache-2.0 License.

The Rust implementation is the maintained Codex CLI — a successor to an earlier TypeScript CLI that OpenAI no longer actively develops. The Rust version ships with features the TypeScript version never supported: rich config.toml parsing, MCP client and server modes, an exec headless automation CLI, collaboration mode, and platform-specific sandbox hardening.

Code organization: a workspace of workspace crates

Codex's codex-rs/ directory is a Cargo workspace with over 70 member crates. This is not a monolith — it is a modular architecture where each crate has a narrow responsibility. The key crates are:

The workspace uses Rust 2024 edition with resolver = "2", fat LTO in release mode, and symbol stripping for minimal binary size. The Cargo.toml enforces a strict clippy lint policy: unwrap_used, expect_used, needless_borrow, and dozens of other pedantic checks are all set to deny. This is a codebase that takes correctness seriously.

The tool layer: schemas, handlers, and runtimes

Codex's tool architecture is one of the most systematic in this entire study. Tools flow through three layers:

Shell execution: zsh-fork backend and escalation

Codex does not just pass commands to /bin/sh. The shell handler has two backends:

• Zsh Fork Backend — On macOS, Codex uses a dedicated zsh-fork backend (tools/runtimes/shell/zsh_fork_backend.rs) that avoids fork-related vulnerabilities in the standard shell escalation path. This is a response to macOS-specific security considerations around process spawning.
• Classic Unix Escalation — On other platforms, the classic escalation path (tools/runtimes/shell/unix_escalation.rs) handles permission elevation and command validation.

The shell handler also integrates with the execpolicy engine, which parses policy rules with a domain-specific language supporting prefix patterns, network rules (with protocol granularity), and command whitelists/blacklists. Safety checking also uses is_known_safe_command() from codex-shell-command for a fast-path allowlist before deeper policy evaluation.

Sandboxing: three platform-specific enforcement layers

Codex's sandbox story is one of the most sophisticated in this study. Rather than a one-size-fits-all approach, Codex implements platform-native enforcement:

Model handling: OpenAI-first but provider-extensible

Codex is built by OpenAI, and its default model family is the Responses API (wire_api = "responses"). The legacy Chat Completions API (wire_api = "chat") is explicitly no longer supported and produces a migration error at config parse time. However, Codex is not hard-coded to OpenAI's cloud:

Retry logic is configurable: defaults include a 300,000 ms stream idle timeout, 5 stream max retries, and 4 request max retries, with hard caps of 100 for user-configured values. OpenTelemetry tracing is available via the codex-otel crate.

MCP: client and server in one binary

Codex does not just consume MCP — it also provides it. Two separate crates handle this:

Subagent architecture: spawn, wait, send, close

Codex supports multi-agent workflows through a structured subagent API. The handler code lives in two parallel module trees: multi_agents (v1) and multi_agents_v2 (v2), reflecting an evolving API design:

Codex also supports agent jobs — a higher-level workflow abstraction via spawn_agents_on_csv_tool and create_report_agent_job_result_tool, which allows spawning multiple agents from CSV input and collecting structured results. This is distinct from the lower-level spawn/wait API and is designed for batch processing scenarios.

Configuration: TOML, not JSON

Unlike many agents in this study that use JSON config, Codex uses config.toml (the legacy TypeScript CLI used config.json, but the Rust version deliberately switched). Key configuration areas:

• Sandbox mode — sandbox_mode = "read-only" | "workspace-write" | "danger-full-access"
• Model providers — [model_providers] table for user-defined providers
• MCP servers — [[mcp_servers]] array with command, transport, and per-tool approval overrides
• Notification hooks — script run on turn completion; auto-detects WSL2 + Windows Terminal for native toast notifications
• SQLite state — sqlite_home config key or CODEX_SQLITE_HOME env var for state DB location
• Custom CA certificates — CODEX_CA_CERTIFICATE env var for enterprise proxy scenarios
• Plan mode reasoning — plan_mode_reasoning_effort for model-specific reasoning presets
• Notices — [notice] table for "do not show again" UI prompt flags
• Custom CA bundles — supports multiple PEM certs, OpenSSL TRUSTED CERTIFICATE labels, and X509 CRL sections

A generated JSON Schema for config.toml lives at codex-rs/core/config.schema.json, enabling IDE autocomplete and validation.

TUI: Ratatui with frames, styles, and tooltips

Codex's terminal UI is built with Ratatui (forked patches for color query support) and organized into a frames/ directory holding distinct UI panels. A dedicated styles.md file and tooltips.txt file in the TUI crate suggest a design-conscious approach — someone cared about how the terminal looks, not just what it does.

The TUI also features a prompt_for_init_command.md template, suggesting an onboarding flow that guides new users through their first interaction. Notifications surface as native toast on Windows (when WSL2 inside Windows Terminal is detected) and via configurable scripts on macOS (terminal-notifier).

Skills system

Codex includes a codex-skills crate that manages embedded system skills — procedural Markdown instructions bundled at compile time via include_dir! and installed into CODEX_HOME/skills/.system on first run. A marker file with a fingerprint avoids redundant re-installation. This is a lightweight but deliberate skills mechanism, similar in spirit to Claude Code's built-in instructions and Hermes's SKILL.md files, but focused on system-level guidance rather than learned procedures.

IDE integration: app server protocol

Codex is not just a CLI. The app-server, app-server-client, app-server-protocol, and app-server-test-client crates form an integration layer for IDE extensions. Codex supports running as an extension in VS Code, Cursor, and Windsurf, with a dedicated codex app command for the desktop app experience. The app server protocol handles initialization, client info reporting (the TUI reports codex-tui), and turn lifecycle events.

Collaboration mode

Codex includes a collaboration-mode-templates crate, suggesting support for multi-user or multi-instance collaboration scenarios. While the exact user-facing flow is not fully documented in the local repo, the presence of dedicated templates and collaboration tool specs (create_close_agent_tool, agent job tools for CSV fanout and reporting) indicates a deliberate investment in multi-agent orchestration beyond simple parent-child spawning.

Authentication: ChatGPT plans and API keys

Codex's recommended setup is to sign in with a ChatGPT account (Plus, Pro, Business, Edu, or Enterprise plans). The codex-login crate handles the sign-in flow, while codex-keyring-store persists credentials using the platform's native keyring. API key authentication is also supported but requires additional setup via the OpenAI developer docs.

Strengths

Weaknesses

Where Codex fits in the landscape

Codex occupies a space between Claude Code and Crush: like Claude Code, it is a deeply integrated product with its own runtime, tool catalog, permission system, and TUI; like Crush, it is a native binary (Rust, not Go) with a strong emphasis on correctness, sandboxing, and cross-platform distribution. But Codex stands apart in its bidirectional MCP support, its multi-agent job execution framework, and its IDE extension ecosystem.

If Claude Code is the most Anthropic-native agent, Codex is the most OpenAI-native one. But unlike Claude Code's tight coupling to Anthropic's ecosystem, Codex at least attempts provider extensibility — even if the wire protocol remains Responses API-shaped.