Codex CLI is an AI coding agent from OpenAI that runs locally on your computer. It provides an interactive terminal interface, non-interactive automation modes, and IDE integration capabilities for executing coding tasks with AI assistance. The system is implemented in Rust as a Cargo workspace and supports multiple execution modes, configurable sandboxing, tool extensibility via the Model Context Protocol (MCP), and multi-agent workflows.
For detailed information about installation procedures, see Installation and Setup. For repository organization, see Repository Structure. For detailed system flow, see Architecture Overview.
Codex is designed as a native executable that coordinates AI model interactions, executes tools in sandboxed environments, and manages conversation state across multiple sessions. The codebase is organized as a Rust workspace with clear separation between core business logic, user interfaces, and integration points.
The diagram below maps high-level system components to their specific implementation crates and modules within the codex-rs workspace.
Sources: codex-rs/cli/src/main.rs106-212 codex-rs/core/src/lib.rs1-205 README.md1-10
Codex supports several primary execution modes, each serving different use cases. All modes converge on the same core ThreadManager codex-rs/core/src/lib.rs116 infrastructure but differ in how they present events and handle user interaction.
| Mode | Entry Point | Use Case | Session Persistence | User Interaction |
|---|---|---|---|---|
| TUI | codex (default) | Interactive development | Yes (rollout files) | Full interactive UI codex-rs/cli/src/main.rs117 |
| Exec | codex exec | Automation/CI | Yes (unless ephemeral) | Non-interactive codex-rs/cli/src/main.rs127 |
| App Server | codex app-server | IDE integration | Yes | JSON-RPC protocol codex-rs/cli/src/main.rs148 |
| MCP Server | codex mcp-server | Tool delegation | Yes | MCP protocol (stdio) codex-rs/cli/src/main.rs144 |
| Cloud | codex cloud | Remote task management | Remote | TUI/CLI for Cloud codex-rs/cli/src/main.rs196 |
The MultitoolCli codex-rs/cli/src/main.rs106 struct handles the routing of subcommands to their respective crates and logic.
Sources: codex-rs/cli/src/main.rs123-212 README.md14-40 codex-rs/core/src/lib.rs116
The Codex workspace is organized into focused crates. The codex-rs/Cargo.toml codex-rs/Cargo.toml1-127 file defines the workspace members.
| Crate | Path | Purpose |
|---|---|---|
codex-core | core/ | Core agent logic, session management, model client, tool orchestration codex-rs/Cargo.toml39 |
codex-tui | tui/ | Interactive terminal UI built with Ratatui codex-rs/Cargo.toml88 |
codex-exec | exec/ | Non-interactive headless CLI codex-rs/Cargo.toml46 |
codex-cli | cli/ | Multitool dispatcher, subcommand routing, feature toggles codex-rs/Cargo.toml31 |
codex-app-server | app-server/ | JSON-RPC server for VS Code and other IDE clients codex-rs/Cargo.toml11 |
codex-mcp-server | mcp-server/ | MCP server implementation exposing Codex as tools codex-rs/Cargo.toml70 |
codex-config | config/ | Configuration parsing, validation, layer merging codex-rs/Cargo.toml34 |
codex-cloud-tasks | cloud-tasks/ | Interface for interacting with Codex Cloud environments codex-rs/Cargo.toml28 |
Sources: codex-rs/Cargo.toml1-127
The core engine implements a layered architecture where the ThreadManager manages thread lifecycles, CodexThread coordinates session execution, and internal Session modules handle turn-by-turn model interactions.
The interaction between frontends and the core is governed by the submission of UserInput codex-rs/cli/src/main.rs88 and the streaming of ResponseEvent codex-rs/core/src/lib.rs189 objects.
Sources: codex-rs/core/src/lib.rs17-116 codex-rs/core/src/session.rs17
| Component | File | Primary Responsibilities |
|---|---|---|
ThreadManager | core/src/thread_manager.rs | Thread spawning/resuming, state database interaction codex-rs/core/src/lib.rs116 |
CodexThread | core/src/codex_thread.rs | Submission queue, event emission, task management codex-rs/core/src/lib.rs28 |
Session (internal) | core/src/session.rs | Turn orchestration, prompt building, model streaming codex-rs/core/src/session.rs17 |
ContextManager | core/src/context_manager.rs | Message history, token tracking, compaction triggers codex-rs/core/src/lib.rs42 |
ModelClient | core/src/client.rs | HTTP/WebSocket transport, SSE parsing, retry logic codex-rs/core/src/lib.rs184 |
RolloutRecorder | core/src/rollout.rs | Session persistence, event filtering codex-rs/core/src/lib.rs155 |
Sources: codex-rs/core/src/lib.rs1-205
Configuration is assembled from multiple layers with CLI arguments taking highest priority. The ConfigEditsBuilder codex-rs/cli/src/main.rs74 is used to modify settings programmatically. Codex supports a layered configuration system starting from defaults up to CLI overrides.
Sources: codex-rs/cli/src/main.rs107-111 codex-rs/core/src/lib.rs39 codex-rs/core/src/lib.rs107
Sessions are persisted as rollout files containing event streams. The RolloutRecorder codex-rs/core/src/lib.rs155 manages this process. Files are stored in directories defined by SESSIONS_SUBDIR codex-rs/core/src/lib.rs157 and ARCHIVED_SESSIONS_SUBDIR codex-rs/core/src/lib.rs152
Sources: codex-rs/core/src/lib.rs152-174
Refresh this wiki