Architecture Overview

Relevant source files

• codex-rs/app-server-protocol/schema/json/ClientRequest.json
• codex-rs/app-server-protocol/schema/json/codex_app_server_protocol.schemas.json
• codex-rs/app-server-protocol/schema/typescript/ClientRequest.ts
• codex-rs/app-server-protocol/schema/typescript/v2/index.ts
• codex-rs/app-server-protocol/src/protocol/common.rs
• codex-rs/app-server-protocol/src/protocol/v2.rs
• codex-rs/app-server/README.md
• codex-rs/app-server/src/bespoke_event_handling.rs
• codex-rs/app-server/src/codex_message_processor.rs
• codex-rs/app-server/tests/common/mcp_process.rs
• codex-rs/app-server/tests/suite/v2/mod.rs
• codex-rs/codex-api/src/error.rs
• codex-rs/codex-api/src/rate_limits.rs
• codex-rs/core/src/api_bridge.rs
• codex-rs/core/src/client.rs
• codex-rs/core/src/client_common.rs
• codex-rs/core/src/codex.rs
• codex-rs/core/src/error.rs
• codex-rs/core/tests/responses_headers.rs
• codex-rs/core/tests/suite/client.rs
• codex-rs/protocol/src/protocol.rs
• codex-rs/tui/src/app.rs
• codex-rs/tui/src/app_event.rs
• codex-rs/tui/src/bottom_pane/chat_composer.rs
• codex-rs/tui/src/bottom_pane/mod.rs
• codex-rs/tui/src/chatwidget.rs
• codex-rs/tui/src/chatwidget/tests.rs
• codex-rs/tui/src/history_cell.rs
• codex-rs/tui/src/slash_command.rs

Purpose and Scope

This page provides a high-level architectural overview of the Codex system, organized into five major subsystems:

1. User Interfaces – Multiple frontend implementations (TUI, exec mode, app-server) that share a common protocol
2. Core Agent System – Business logic for session management, turn execution, and event processing (codex-core)
3. Model Interaction – Session-scoped ModelClient that communicates with OpenAI and other providers
4. Tool Execution – Tool registry, approval orchestration, sandboxing, and execution runtimes
5. Configuration & State – Hierarchical config loading, feature flags, and JSONL persistence

The architecture follows a queue-based submission/event protocol (Op/EventMsg) where user operations are submitted asynchronously and results stream back as events. This decouples request initiation from execution and enables interruptible workflows.

For installation procedures, see Installation and Setup. For crate-level organization, see Repository Structure. For protocol message details, see Protocol Layer (Submission/Event System).

---

System Architecture Overview

The following diagram shows the major subsystems and their relationships. User interfaces communicate with the core agent via a queue-based protocol, the agent coordinates model calls and tool execution, and all state is persisted to JSONL rollout files.

Diagram: Codex Ecosystem Overview

Sources: codex-rs/cli/src/main.rs1-100 codex-rs/core/src/codex.rs274-520 codex-rs/core/src/client.rs175-285 codex-rs/core/src/tools/spec.rs1-200 codex-rs/core/src/unified_exec.rs1-150

---

Submission/Event Queue Pattern

The Codex struct (codex.rs274) exposes a queue-based interface:

Key Protocol Types:

• Submission (protocol.rs74): Wraps Op with unique ID
• Op (protocol.rs124): Operations enum (UserTurn, Interrupt, Shutdown, etc.)
• Event (protocol.rs664): Wraps EventMsg with submission ID
• EventMsg (protocol.rs683): Events enum (TurnStarted, AgentMessageDelta, ExecCommandBegin, etc.)

The Codex::submit() method (codex.rs470-475) generates a unique ID and sends the submission. The submission_loop (codex.rs2680-2870) runs as a Tokio task and dispatches operations to the appropriate handler (e.g., handle_user_turn, handle_interrupt).

Sources: codex-rs/core/src/codex.rs274-520 codex-rs/core/src/codex.rs470-475 codex-rs/core/src/codex.rs2680-2870 codex-rs/protocol/src/protocol.rs74-750

---

Three-Tier Architecture

User Interface → Core → Model Flow

The following diagram shows how user input flows from UI layers through the core agent to model APIs, and how events stream back.

Diagram: Core Agent Event Loop

Sources: codex-rs/tui/src/chatwidget.rs1-300 codex-rs/core/src/codex.rs274-520 codex-rs/core/src/codex.rs1500-1800 codex-rs/core/src/client.rs175-600 codex-rs/core/src/tools/mod.rs1-200

---

UI Layer: Multiple Frontends

The UI layer provides three distinct user-facing modes, each optimized for different use cases. All modes communicate with codex-core using the same Codex queue interface.

Mode	Entry Point	Primary Use Case	Event Processing
TUI	codex-tui binary, App struct	Interactive terminal sessions	ChatWidget maintains UI state, renders cells
Exec	codex exec subcommand	CI/CD pipelines, scripts	EventProcessorWithHumanOutput or EventProcessorWithJsonOutput
App Server	codex-app-server binary	IDE extensions (VS Code, Cursor)	CodexMessageProcessor translates to JSON-RPC notifications

TUI Architecture

The TUI mode uses App (app.rs518) as the top-level coordinator. It manages multiple ChatWidget instances (one per thread) and handles thread switching, config persistence, and external editor integration.

Diagram: TUI Component Hierarchy

Key TUI Components:

• App (app.rs518-633): Multiplexes TuiEvent (key presses, ticks) and AppEvent (file search, rate limits); manages ThreadEventChannel buffering for inactive threads
• ChatWidget (chatwidget.rs515-665): Handles EventMsg variants, builds HistoryCell instances, manages streaming state (active_cell, stream_controller)
• BottomPane (bottom_pane/mod.rs145-360): Routes keys to active view (popup) or composer; manages view stack (approval overlays, selection lists)
• ChatComposer (chat_composer.rs200-500): TextArea editing, paste burst detection, slash command popup, file search popup, skill/app mention popup

Sources: codex-rs/tui/src/app.rs518-633 codex-rs/tui/src/chatwidget.rs515-665 codex-rs/tui/src/bottom_pane/mod.rs145-360 codex-rs/tui/src/bottom_pane/chat_composer.rs200-500

Exec Mode Architecture

Exec mode is headless and synchronous: it submits a turn, processes events linearly, and exits with a status code. Output format is controlled by the --json flag.

Diagram: Exec Mode Event Processing

Key Exec Components:

• EventProcessor trait (event_processor.rs20-60): Defines handle_event(), take_status(), final_output_schema() interface
• EventProcessorWithHumanOutput (event_processor_with_human_output.rs50-800): Renders ANSI-colored text, displays streaming agent messages, exec command summaries, errors
• EventProcessorWithJsonOutput (event_processor_with_jsonl_output.rs30-200): Emits one JSON object per line for machine consumption

Exec mode auto-cancels elicitations (approval requests) when not running interactively (event_processor_with_human_output.rs400-450).

Sources: codex-rs/exec/src/lib.rs100-300 codex-rs/exec/src/event_processor.rs20-60 codex-rs/exec/src/event_processor_with_human_output.rs50-800 codex-rs/exec/src/event_processor_with_jsonl_output.rs30-200

App Server Architecture

The app-server exposes a JSON-RPC 2.0 API over stdio (default) or WebSocket. IDE extensions send ClientRequest messages and receive ServerNotification messages. The CodexMessageProcessor translates between protocol v2 and core events via bespoke_event_handling.

Diagram: App Server Protocol Translation

Key App Server Components:

• CodexMessageProcessor (codex_message_processor.rs200-3500): Dispatches ClientRequest to handlers (thread/start, turn/start, config/read, etc.)
• bespoke_event_handling (bespoke_event_handling.rs50-2000): Translates core EventMsg to protocol v2 notifications (item/started, item/delta, turn/completed)
• ThreadWatchManager (thread_status.rs100-300): Tracks per-thread status (idle, busy, waiting_for_input)
• OutgoingMessageSender (outgoing_message.rs100-400): Multiplexes responses and notifications over transport

The app-server supports two protocol versions (v1 and v2); v2 is the current default and uses camelCase naming conventions (app-server-protocol/src/protocol/v2.rs1-2000).

Sources: codex-rs/app-server/src/codex_message_processor.rs200-3500 codex-rs/app-server/src/bespoke_event_handling.rs50-2000 codex-rs/app-server/src/thread_status.rs100-300 codex-rs/app-server/src/outgoing_message.rs100-400 codex-rs/app-server-protocol/src/protocol/v2.rs1-2000

---

Core Layer: Business Logic

The core layer is implemented in codex-core and provides the shared business logic for all frontends. The entry point is the Codex struct, which owns a Session and exposes the submission/event interface.

Codex Interface

The Codex struct (codex.rs274) provides the submission/event queue interface:

pub struct Codex {
    pub(crate) tx_sub: Sender<Submission>,
    pub(crate) rx_event: Receiver<Event>,
    pub(crate) agent_status: watch::Receiver<AgentStatus>,
    pub(crate) session: Arc<Session>,
}

Public Methods:

• Codex::spawn() (codex.rs300-467): Creates new session, spawns submission_loop Tokio task, returns CodexSpawnOk with thread ID
• submit(op: Op) (codex.rs470-475): Generates UUID, wraps in Submission, sends to tx_sub
• next_event() (codex.rs487-493): Blocks on rx_event.recv() until next event
• steer_input(items, expected_turn_id) (codex.rs496-502): Injects user input during an active turn (used for agent steering)

The submission_loop (codex.rs2680-2870) runs as a Tokio task and dispatches operations:

• Op::UserTurn → handle_user_turn() → spawns RegularTask
• Op::Interrupt → cancels active task
• Op::Shutdown → cleans up and exits loop

Sources: codex-rs/core/src/codex.rs274-285 codex-rs/core/src/codex.rs300-467 codex-rs/core/src/codex.rs470-502 codex-rs/core/src/codex.rs2680-2870

Session Lifecycle

The Session struct (codex.rs525-539) manages conversation state and coordinates subsystems. It is created once per thread and is immutable for the thread's lifetime.

Diagram: Session Initialization and State

SessionState (state.rs50-200) contains mutable per-turn state:

• context_manager: ContextManager: Conversation history, token usage tracking (context_manager.rs1-500)
• session_configuration: SessionConfiguration: CWD, approval/sandbox policies, model (codex.rs708-800)
• rollout_recorder: RolloutRecorder: JSONL persistence (rollout/mod.rs1-300)
• pending_elicitations: HashMap<...>: Tracks approval requests awaiting user response

SessionServices (state.rs100-250) holds shared services:

• auth_manager: Arc<AuthManager>: Handles authentication (ChatGPT, API key)
• models_manager: Arc<ModelsManager>: Model metadata, version resolution
• exec_policy: Arc<ExecPolicyManager>: Per-directory execution rules
• skills_manager: Arc<SkillsManager>: Loads and tracks project skills
• file_watcher: Arc<FileWatcher>: Watches for SKILL.md changes

Sources: codex-rs/core/src/codex.rs300-467 codex-rs/core/src/codex.rs525-539 codex-rs/core/src/codex.rs967-1200 codex-rs/core/src/state.rs50-250 codex-rs/core/src/context_manager.rs1-500

Turn Execution Pipeline

When a UserTurn operation is submitted, the session creates a RegularTask and executes it via SessionTask::execute().

Diagram: Turn Execution Flow

Key Turn Structures:

• TurnContext (codex.rs543-705): Immutable turn config (model info, CWD, approval/sandbox policies, ToolsConfig, features, JsReplHandle)
• SessionTask trait (tasks/mod.rs20-50): Defines execute() for different task types
• RegularTask (tasks/regular.rs50-800): Standard user turn execution (prompt → stream → tools → completion)
• ReviewTask (tasks/review.rs1-500): Specialized task for code review with review-specific prompts

Sources: codex-rs/core/src/codex.rs1500-1800 codex-rs/core/src/codex.rs543-705 codex-rs/core/src/tasks/mod.rs20-50 codex-rs/core/src/tasks/regular.rs50-800

---

Model Client Layer

The model client uses a two-level abstraction: session-scoped ModelClient and turn-scoped ModelClientSession. This design enables WebSocket connection reuse across requests within a turn while keeping session configuration isolated.

Diagram: Model Client Architecture

ModelClient (client.rs175-284):

• Created once per session via ModelClient::new() (client.rs228-254)
• Holds provider info (ModelProviderInfo), auth manager, conversation ID, WebSocket version preference
• Builds per-turn ModelClientSession via new_session() (client.rs260-268)

ModelClientSession (client.rs192-210):

• Created per turn; holds optional WebSocket connection for reuse within the turn
• Caches websocket_last_request for incremental response.append optimization
• Stores x-codex-turn-state token from server (used for sticky routing across retries)

Transport Selection (client.rs674-850):

• Prefer WebSocket if responses_websocket_version is set (v1 or v2)
• Fallback to HTTP/SSE if WebSocket fails or is disabled via disable_websockets flag
• Session-level fallback: once HTTP is activated, subsequent turns use HTTP for the session

Streaming Flow (client.rs400-600):

1. Call stream(prompt, model_info, effort, otel) on ModelClientSession
2. Select transport (WebSocket or HTTP/SSE)
3. Send Prompt (messages, tools, output schema, reasoning config)
4. Stream ResponseEvent items (messages, tool calls, reasoning deltas, completion)
5. Handle retries/rate limits (up to 3 attempts)

Sources: codex-rs/core/src/client.rs138-850 codex-rs/core/src/client_common.rs1-200 codex-rs/core/src/model_provider_info.rs1-150

---

Tool Execution and Security

Tools are registered per turn based on model capabilities and enabled features. The ToolOrchestrator enforces approval and sandbox policies before routing tool calls to runtime-specific handlers.

Diagram: Tool Execution Pipeline

Tool Registration (tools/spec.rs200-500):

• ToolsConfig::new() filters tool registry based on Features and ModelInfo
• Creates ToolSpec for each enabled tool (function-call or freeform format)
• Sends specs to model as part of Prompt

Tool Approval (tools/orchestrator.rs50-400):

• ToolOrchestrator evaluates ExecApprovalRequirement per tool call
• Checks approval_policy (Never, OnRequest, UnlessTrusted, OnFailure)
• Emits ExecApprovalRequestEvent if approval needed; waits for Op::ExecApproval

Sandboxing (tools/sandboxing/mod.rs1-300):

• Platform-specific backends: Bubblewrap+Landlock (Linux), Seatbelt (macOS), AppContainer (Windows)
• SandboxPolicy controls read/write/network access
• Retry-without-sandbox on failure (if policy allows)

Unified Exec (unified_exec.rs50-800):

• Process pool for long-lived commands (max 64, LRU eviction)
• PTY allocation for interactive shells
• exec_command spawns new process, write_stdin sends input, read_output streams stdout/stderr

Sources: codex-rs/core/src/tools/spec.rs200-500 codex-rs/core/src/tools/orchestrator.rs50-400 codex-rs/core/src/tools/sandboxing/mod.rs1-300 codex-rs/core/src/unified_exec.rs50-800

---

Configuration and State Management

Configuration flows through multiple layers (defaults, user config, project config, CLI overrides) and is resolved once per session. Session state is persisted to JSONL rollout files.

Diagram: Configuration Flow

Configuration Resolution (config/mod.rs50-500):

1. Load defaults (config/default.rs1-200)
2. Load user config from ~/.codex/config.toml (if exists)
3. Walk directory tree, load .codex/config.toml files (project config)
4. Apply profile (if specified via --profile)
5. Apply CLI overrides (--set, --feature)
6. Apply cloud requirements (if enabled)
7. Merge layers by priority (CLI > cloud > profile > project > user > defaults)

Config Structure (config/mod.rs50-300):

• model: Option<String>: Model slug (e.g., "gpt-4o")
• model_reasoning_effort: Option<ReasoningEffortConfig>: Reasoning effort (low/medium/high)
• permissions: Permissions: Approval/sandbox policies
• features: Features: Immutable feature toggles
• mcp_servers: HashMap<String, McpServerConfig>: MCP server configurations

SessionConfiguration (codex.rs708-800):

• Frozen snapshot of config at session start
• Contains base instructions, CWD, approval/sandbox policies
• Immutable for session lifetime (per-turn config derived from this)

Rollout Persistence (rollout/mod.rs1-300):

• JSONL format: one RolloutLine per line
• RolloutLine::Turn: Complete turn with all events
• RolloutLine::SessionMeta: Thread name, updated timestamp
• Resume: read JSONL, reconstruct InitialHistory::Resumed
• Fork: copy JSONL with new thread ID, update session_meta

Sources: codex-rs/core/src/config/mod.rs50-500 codex-rs/core/src/config/default.rs1-200 codex-rs/core/src/config_loader.rs100-800 codex-rs/core/src/codex.rs708-800 codex-rs/core/src/state.rs50-250 codex-rs/core/src/rollout/mod.rs1-300

---

---

---

Thread and Session Management

The ThreadManager (thread_manager.rs1-500) coordinates multiple conversations. Each thread is a CodexThread (codex_thread.rs1-300) that owns a Codex instance and tracks metadata.

Diagram: ThreadManager Architecture

ThreadManager Key Methods:

• create_thread() (thread_manager.rs200-300): Spawns new Codex with InitialHistory::New
• resume_thread(thread_id) (thread_manager.rs350-450): Loads JSONL rollout, creates Codex with InitialHistory::Resumed
• fork_thread(source_id, fork_from_turn_id) (thread_manager.rs500-600): Copies rollout to new file, creates Codex with InitialHistory::Forked
• list_threads(cursor, page_size, sort_key) (thread_manager.rs700-850): Reads session index, returns paginated list

ThreadEventStore (in TUI App): When a thread is inactive, events are buffered in a bounded queue so switching threads can replay recent events without re-reading the rollout file.

Sources: codex-rs/core/src/thread_manager.rs50-850 codex-rs/core/src/codex_thread.rs50-300 codex-rs/tui/src/app.rs245-320

---

---

Summary: Data Flow Example

The following sequence shows a typical user turn with tool execution and approval.

Diagram: Typical Turn Data Flow

Sources: codex-rs/tui/src/chatwidget.rs1-300 codex-rs/core/src/codex.rs274-520 codex-rs/core/src/codex.rs2680-2870 codex-rs/core/src/client.rs400-600 codex-rs/core/src/tools/mod.rs150-350 codex-rs/core/src/unified_exec.rs200-500

---

Key Architectural Benefits

1. Multiple UIs, One Core: TUI, Exec, and App Server share identical business logic, reducing bug surface area
2. Queue-Based Async: Submission/event protocol enables interruptible, cancellable operations
3. JSONL Persistence: Human-readable, diffable session logs; no database required
4. Model Provider Agnostic: Uniform abstraction over OpenAI, OSS, local models
5. Tool Extensibility: MCP servers and dynamic tools enable third-party integrations

Sources: All files in codex-rs/core/src/ codex-rs/tui/src/ codex-rs/exec/src/ codex-rs/app-server/src/