Codex Overview, generated by Codex

codex_overview.md

Codex Rust CLI (codex-rs) codebase overview

codex-rs is a Cargo workspace that builds the Rust implementation of the Codex CLI plus “server mode” frontends. The split is: types/protocol (codex-protocol), engine (codex-core), and adapters/UI (codex-cli, codex-tui, codex-exec, app-server, mcp-server).

Workspace layout (what matters)

• core/ (codex-core): the engine. Owns session state, model streaming, tool dispatch, sandboxing, approvals, rollouts, and config loading.
• protocol/ (codex-protocol): the SQ/EQ message protocol between a UI/client and the engine. This is where Op (inputs) and Event/EventMsg (outputs) live (protocol/src/protocol.rs).
• cli/ (codex-cli): the codex multitool binary. It routes to subcommands like codex exec, codex mcp-server, codex app-server, etc (cli/src/main.rs).
• tui/ (codex-tui): the fullscreen interactive UI (tui/src/lib.rs, tui/src/main.rs).
• exec/ (codex-exec): the headless “run to completion” CLI, with human or JSONL output modes (exec/src/lib.rs, exec/src/main.rs).
• app-server/ (codex-app-server + codex-app-server-protocol): JSON-RPC-ish stdio server for rich clients (e.g. VS Code). It models thread/turn/item explicitly (app-server/README.md).
• mcp-server/ (codex-mcp-server): MCP stdio server wrapper around the same engine (mcp-server/src/lib.rs).
• linux-sandbox/, windows-sandbox-rs/, core/src/seatbelt.rs, core/src/landlock.rs: OS sandboxes. The engine chooses at runtime (core/src/safety.rs).
• apply-patch/: patch application mechanics.
• Many support crates (login/, keyring-store/, file-search/, otel/, responses-api-proxy/, etc.) that plug into core/CLI.

The engine contract (SQ/EQ)

• The “real API” between UI and engine is codex_protocol::protocol::{Op, Event, EventMsg}.
• A conversation is driven by sending Op values and reading Event values.
• codex-rs/docs/protocol_v1.md references core/src/protocol.rs which no longer exists; the authoritative types are in protocol/src/protocol.rs and re-exported by codex-core (core/src/lib.rs).

Runtime architecture (what happens on a turn)

• ConversationManager constructs and tracks live conversations (core/src/conversation_manager.rs).
• Each conversation wraps a spawned engine instance (Codex) plus rollout persistence (core/src/codex_conversation.rs, core/src/codex.rs).
• Codex::spawn creates an async channel pair: a submission queue (UI → engine) and an event queue (engine → UI) (core/src/codex.rs). This is the SQ/EQ pattern described in the protocol doc.
• The model stream produces ResponseItems; the engine maps them to protocol events and/or tool calls (core/src/event_mapping.rs).
• Tool calls are routed by ToolRouter (core/src/tools/router.rs) using a registry built from model-family + feature flags (core/src/tools/spec.rs).
• Approvals and sandboxing are enforced before executing shell or applying patches (core/src/safety.rs plus sandbox-specific code).

Mental model

sequenceDiagram
  participant UI
  participant Core as codex-core (Codex)
  participant Model
  participant Tools as ToolRouter/Sandbox

  UI->>Core: Op::UserInput / Op::UserTurn
  Core->>Model: stream request
  Model-->>Core: ResponseItem stream
  Core->>Tools: (optional) exec/apply_patch/MCP tool call
  Tools-->>Core: tool output (+ approvals gating)
  Core-->>UI: EventMsg::* (deltas, approvals, exec start/stop, turn complete)

Loading

Where to extend it (the “seams”)

• Add/modify protocol surface: protocol/src/protocol.rs (then core + UIs must handle new Op/EventMsg).
• Add a tool: implement a handler under core/src/tools/handlers/… and register it via core/src/tools/spec.rs (and decide its sandbox/approval behavior).
• Add a new frontend: write an adapter that speaks the protocol (send Op, render EventMsg). tui/ and exec/ are the smallest concrete examples.
• Add a server interface: follow mcp-server/src/lib.rs or app-server/README.md and translate remote RPC messages into Ops/events.

Open questions

• Do you want the “engine-first” view (how core/src/codex.rs schedules turns, compaction, tool parallelism), or the “UI-first” view (how the TUI renders events and approvals)?
• Are you assuming MCP and app-server are interchangeable? They are not: both wrap the same core, but they expose different schemas and lifecycle (MCP is tool-centric; app-server is thread/turn/item-centric).

---

╭──────────────────────────────────────────────╮
│ >_ OpenAI Codex (v0.72.0)                    │
│                                              │
│ model:     gpt-5.2 medium   /model to change │
│ directory: ~/workspace/codex/codex-rs        │
╰──────────────────────────────────────────────╯