This page introduces the Codex repository, explaining its purpose as a local AI coding agent, its multi-interface architecture (CLI/TUI, headless exec, IDE integration, MCP server), and the high-level organization of its core subsystems. For detailed information about specific subsystems, see:
Codex is a local AI coding agent from OpenAI that runs natively on user machines. It provides an interactive terminal interface, headless execution mode, IDE integrations, and acts as both an MCP client (consuming external tools) and MCP server (exposing its tools to other clients).
The repository is a Rust workspace (codex-rs) that implements:
| Component | Description | Distribution |
|---|---|---|
| codex CLI | Terminal user interface (TUI) with interactive chat | Native binary via npm, Homebrew, GitHub Releases |
| codex exec | Non-interactive headless execution for scripting/CI | Same binary, different subcommand |
| codex-app-server | JSON-RPC server for IDE extensions (VS Code, Cursor) | Spawned by IDE extensions |
| codex-mcp-server | MCP server exposing Codex tools to other clients | Standalone or embedded mode |
Users authenticate via ChatGPT OAuth or OpenAI API keys. The agent supports Plus, Pro, Team, Edu, and Enterprise plans.
Sources: README.md1-61 codex-rs/README.md1-95 codex-rs/Cargo.toml1-66 codex-rs/core/src/lib.rs1-156
Multi-tool dispatch: The codex binary uses arg0_dispatch_or_else to route execution based on the program name or subcommand. When invoked as codex with no subcommand, it launches the TUI. The exec, mcp, and app subcommands route to their respective entry points.
Interface summary:
| Interface | Entry Point | Primary Use Case |
|---|---|---|
| TUI | codex_tui::run_main() | Interactive terminal sessions with streaming UI |
| Exec | codex_exec::run_exec() | CI/CD pipelines, scripting, one-shot tasks |
| App Server | codex_app_server::run() | IDE integrations (VS Code, Cursor, Windsurf) |
| MCP Server | codex_mcp_server::run() | Exposing Codex tools to external MCP clients |
All interfaces converge on ThreadManager, which spawns Codex instances. Each Codex instance owns a Session that manages conversation state, model client, and tool execution.
Sources: codex-rs/cli/src/main.rs1-856 codex-rs/tui/src/lib.rs1-617 codex-rs/exec/src/lib.rs1-616 codex-rs/Cargo.toml1-374
Workspace organization: The repository is a Cargo workspace with 65+ member crates. The workspace root Cargo.toml declares shared dependencies and lints.
Key directories:
| Directory | Purpose | Primary Crates |
|---|---|---|
cli/ | Main entry point, subcommand routing | codex-cli |
tui/ | Terminal UI implementation | codex-tui |
exec/ | Headless execution mode | codex-exec |
app-server/ | JSON-RPC v2 server for IDEs | codex-app-server, codex-app-server-protocol |
mcp-server/ | MCP server implementation | codex-mcp-server |
core/ | Core agent engine | codex-core |
protocol/ | Op/Event protocol types | codex-protocol |
config/ | Configuration TOML parsing | codex-config |
utils/ | Shared utilities | codex-utils-* (20+ crates) |
The codex-core crate is the heart of the system, containing the Codex struct (codex-rs/core/src/codex.rs274-520), Session (codex-rs/core/src/codex.rs525-539), ThreadManager (codex-rs/core/src/thread_manager.rs), and ModelClient (codex-rs/core/src/client.rs).
Sources: codex-rs/Cargo.toml1-374 codex-rs/README.md1-95 codex-rs/core/src/lib.rs1-156 codex-rs/core/Cargo.toml1-130
Codex: The high-level interface to the agent (codex-rs/core/src/codex.rs272-520). It operates as a queue pair: clients submit Op operations via tx_sub and receive Event responses via rx_event. The Codex::spawn() method initializes a session and starts the submission_loop task (codex-rs/core/src/codex.rs298-467).
Session: Represents an initialized conversation with at most 1 running task at a time (codex-rs/core/src/codex.rs525-539). The session_loop (codex-rs/core/src/codex.rs1265-1426) processes submissions, spawns tasks (RegularTask, ReviewTask, GhostSnapshotTask), and manages conversation history via ContextManager (codex-rs/core/src/context_manager.rs).
SessionState: Mutable state protected by a Mutex, containing:
session_configuration: Frozen config snapshot for the sessioncontext_manager: Conversation history and token trackingrollout: JSONL event log for persistenceactive_turn: Ephemeral turn state during executionSources: codex-rs/core/src/codex.rs272-540 codex-rs/core/src/codex.rs1265-1426 codex-rs/core/src/context_manager.rs1-1000
Protocol types: Defined in codex_protocol::protocol (codex-rs/protocol/src/protocol.rs1-2500). The protocol uses:
id and an Op payload (codex-rs/protocol/src/protocol.rs73-79)UserTurn, Interrupt, ExecApproval) (codex-rs/protocol/src/protocol.rs124-500)id (correlates to submission) and EventMsg (codex-rs/protocol/src/protocol.rs502-530)TurnStarted, AgentMessageDelta, ExecCommandBegin) (codex-rs/protocol/src/protocol.rs532-800)All user interfaces consume this protocol. The TUI calls codex.submit() (codex-rs/core/src/codex.rs470-475) and codex.next_event() (codex-rs/core/src/codex.rs487-494). The app-server translates between JSON-RPC v2 and the internal protocol (codex-rs/app-server/src/main.rs).
Sources: codex-rs/protocol/src/protocol.rs1-2500 codex-rs/core/src/codex.rs470-494
ModelClient: Session-scoped client that manages WebSocket vs HTTP transport (codex-rs/core/src/client.rs). It prefers WebSocket for streaming but falls back to HTTP/SSE when WebSocket is unavailable.
ModelClientSession: Turn-scoped session that sends requests to the OpenAI Responses API (codex-rs/core/src/client.rs). It includes:
x-codex-turn-state header for multi-turn session affinityx-responsesapi-include-timing-metrics header for latency telemetryResponse streaming: The client yields ResponseEvent items (codex-rs/core/src/client_common.rs) which the session task processes via handle_non_tool_response_item() (codex-rs/core/src/stream_events_utils.rs).
Sources: codex-rs/core/src/client.rs1-1500 codex-rs/core/src/client_common.rs1-500 codex-rs/core/src/stream_events_utils.rs1-800
ToolsConfig: Selects which tools are available based on Features and model capabilities (codex-rs/core/src/tools/spec.rs). Tools can be Function (JSON schema) or Freeform (text args).
ToolRouter: Dispatches tool calls by name to the appropriate handler (codex-rs/core/src/tools/mod.rs). Handlers include:
apply_patch tool (codex-rs/apply-patch/src/lib.rs)ToolOrchestrator: Unified approval flow that evaluates AskForApproval policy and prompts the user when needed (codex-rs/core/src/tools/orchestrator.rs). After approval, it applies sandbox policies (Bubblewrap on Linux, Seatbelt on macOS, AppContainer on Windows).
Sources: codex-rs/core/src/tools/spec.rs1-500 codex-rs/core/src/tools/mod.rs1-800 codex-rs/core/src/unified_exec.rs1-1500 codex-rs/core/src/tools/orchestrator.rs1-1000
Configuration flow: Settings merge through multiple layers with increasing priority (codex-rs/core/src/config/mod.rs):
~/.codex/config.toml (global settings).codex/config.toml (per-project overrides)fast, slow, custom--set key=value flagsConfigLayerStack: Manages layer ordering and constraint validation (codex-rs/core/src/config_loader/mod.rs). Cloud requirements can restrict values (e.g., enforce specific sandbox policies for managed environments).
SessionConfiguration: Frozen snapshot created at session start (codex-rs/core/src/codex.rs708-800). This ensures consistent behavior across the session even if config files change on disk.
Sources: codex-rs/core/src/config/mod.rs1-2000 codex-rs/core/src/config_loader/mod.rs1-1500 codex-rs/core/src/codex.rs708-800
Target platforms:
| Platform | Architectures | Formats |
|---|---|---|
| macOS | x86_64, ARM64 | .tar.gz, .dmg (signed + notarized) |
| Linux | x86_64, ARM64 | .tar.gz (musl static, gnu dynamic) |
| Windows | x86_64 | .zip (Azure Trusted Signing) |
Distribution channels:
npm install -g @openai/codex (downloads platform-specific binary via postinstall)brew install --cask codex (macOS only)The release pipeline (.github/workflows/rust-release.yml) builds for all platforms, signs binaries, and uploads to GitHub Releases. The npm package wrapper (npm/README.md) downloads the appropriate binary for the user's platform at install time.
Sources: README.md1-61 codex-rs/README.md1-95 .github/workflows/rust-release.yml1-1000