openai/codex

Codex CLI uses a single-loop architecture without a separate planner; the model itself plans and acts within each turn. The core loop lives in run_turn() in core/src/session/turn.rs:164 which accepts TurnInput (user messages, function-call outputs, inter-agent communications) and runs a loop { ... } (line 427) that repeats until the model produces a final assistant message with no pending input. Inside the loop, the session builds a prompt from its cloned history (line 527), invokes the OpenAI Responses API via run_sampling_request() (line 535), streams the response, and executes any tool calls the model makes through the ToolCallRuntime (line 1633). After each sampling round the loop checks for pending user input (line 431), token-limit thresholds for auto-compaction (line 612), and hook stop/block requests (line 663–719). Tool calls are dispatched through try_run_sampling_request() (line 1679) which invokes the ToolRouter — a registry that maps tool names to CoreToolRuntime implementations in core/src/tools/registry.rs. Sub-agents are supported via a multi-agent V2 system in core/src/tools/handlers/multi_agents_v2.rs:1 where tools like spawn_agent, send_message, and wait let the model create and communicate with child threads, coordinated by the AgentControl trait in core/src/agent/api.rs:41. The turn's tool-call schema is defined by the Responses API's native function-calling format, with tool definitions served by the ToolRouter and filtered per-step based on permissions and feature flags.

Repository context is built through a layered World State system in core/src/context/world_state/mod.rs:64. Each turn constructs a WorldState by merging context fragments from many sources: base instructions, model instructions, AGENTS.md instructions (loaded in core/src/agents_md.rs:58 by walking up from the project root to find files named AGENTS.md), environment configurations, plugin/skill instructions, and permission profiles. These fragments are placed as Prefix, Standalone, or Mergeable items (line 70–75) into the model's input. File search uses a fuzzy-file-search tool and a ripgrep-based content search tool (exposed through the unified exec tool surface). For context-window management, Codex CLI implements auto-compaction in core/src/compact.rs:1. When the token count exceeds the model's limit — tracked via ContextWindowTokenStatus in core/src/session/context_window.rs:8 — run_auto_compact() (called from turn.rs at lines 625, 734, 785) sends the conversation history to the model with a summarization prompt (SUMMARIZATION_PROMPT from prompts). The two main compaction strategies are inline auto-compact (line 625) and remote auto-compact v2 (imported from compact_remote_v2). Session history is stored via the thread store and cloned for each model request, with compaction producing CompactedHistoryMetadata that replaces verbose history. The WorldState also tracks per-section context diffs and token budgets, emitting context-window guidance fragments when approaching limits.

Codex CLI applies code edits through a dedicated apply-patch crate at codex-rs/apply-patch/src/lib.rs:1. The model sends edits as structured function calls containing patch chunks, which are parsed by the parser module into UpdateFileChunk objects (exported from line 27). The core logic in file_update.rs:25 reads the target file, computes replacements against the original content using compute_replacements() (line 60), and produces the new file contents. The patch format supports change-context matching via seek_sequence::seek_sequence() (line 72) which locates context lines before applying edits, allowing robust search/replace operations. The ApplyPatchFileUpdate struct (exported from line 33) tracks what changed. Edits go through the approval pipeline defined in core/src/tools/approvals.rs:67 where tool calls like ExecCommand and ApplyPatchFileUpdate require user approval based on the configured AskForApproval policy. Validation is handled through the Guardian review system: the tool orchestrator in core/src/tools/orchestrator.rs:1 runs approval → sandbox-selection → execution with retry escalation. There is no built-in linter integration; however, edits are recorded as file diffs and tracked via TurnDiffTracker for display. Undo is supported through Git — Codex discovers the project's Git repository and can diff against HEAD or the remote (the GitDiffToRemoteParams schema suggests git-aware diffing). The approval system also caches decisions per session via ApprovalStore (line 42 in sandboxing.rs) so repeated identical edits don't reprompt.

Execution safety is enforced through multi-layer sandboxing with approval gates. On Linux, commands run inside bubblewrap (bwrap) containers for filesystem isolation, combined with seccomp filters for network restriction (implemented in codex-rs/linux-sandbox/src/landlock.rs:1). The bwrap launcher in codex-rs/linux-sandbox/src/linux_run_main.rs:1 creates a sandboxed process with controlled filesystem mounts, network namespaces, and process isolation. On macOS, the seatbelt sandbox is used (codex-rs/sandboxing/src/lib.rs:9). On Windows, restricted-token sandboxes apply. There are three sandboxable preferences: Auto, Require, and Forbid (codex-rs/sandboxing/src/manager.rs:42). The exec policy system in core/src/exec_policy.rs:1 evaluates commands against allow/deny rule files (*.rules files, line 55) loaded from the project, with a default.rules file installed by default. Dangerous command detection in codex-shell-command identifies known dangerous patterns (e.g., rm -rf /, > /dev/sda). The approval system in core/src/tools/approvals.rs:54 uses AskForApproval policies — Always, Auto, Never, or Granular — configured per model and environment. Before executing any shell command, the tool orchestrator (core/src/tools/orchestrator.rs:55) runs: approval decision → sandbox selection → execution → retry with escalated sandboxing on denial. Network restrictions enforce NetworkSandboxPolicy from PermissionProfile, which can block, allow-list, or monitor network access. Hook scripts (configured via settings.json hooks) can intercept tool calls before and after execution, adding a programmable policy layer. The Guardian auto-review system (core/src/guardian/) can independently review actions for approval.

Codex CLI connects primarily to OpenAI's Responses API as the default provider, with model catalog fetched from api.openai.com and cached in models_cache.json (managed by codex-rs/models-manager/src/manager.rs:34). The ModelProvider trait in codex-rs/model-provider/src/provider.rs:108 defines the abstraction for model backends, with implementations for: OpenAI's production API (the default, via CoreAuthProvider in lib.rs:27), Amazon Bedrock (amazon_bedrock in lib.rs:17), LM Studio (codex-rs/lmstudio/), and Ollama (codex-rs/ollama/). The ModelsEndpointClient trait (manager.rs:42) handles remote catalog fetching, while static and OpenAI models managers serve the bundled catalog (bundled_models_response() in lib.rs:13 from a bundled models.json). Model selection uses a pinned model per session, with the option to switch mid-conversation. The ModelInfo struct carries per-model metadata: context window size, reasoning-effort defaults, input/output modalities, auto-compact token limits, and ToolMode (standard, code-mode-only, or code-mode — core/src/tools/mod.rs:75). Models are called through the OpenAI Responses API streaming endpoints via the ModelClientSession in core/src/client.rs:1, which manages WebSocket connections for sticky routing, retries with exponential backoff (core/src/responses_retry.rs:33), and transport fallback. Per-model prompts are rendered via render_model_instructions() in prompts/src/model_instructions.rs:8, which uses the model's instruction template from its metadata. Cost tracking uses TokenUsageInfo collected per turn and aggregated in analytics events. Reasonable efforts (ReasoningEffort) controls are configurable per-turn.

Codex CLI is extensible through multiple mechanisms. MCP (Model Context Protocol) is the primary extension system: the codex-mcp crate in codex-rs/codex-mcp/src/lib.rs:1 implements MCP server management, tool catalog caching, and resource access. MCP servers are declared in config via McpServerConfig entries and discovered through the configured_mcp_servers() function, with their tools surfaced to the model through McpHandler (core/src/tools/handlers/mcp.rs). Skills (a plugin system) let users install task-focused packages — sample skills in codex-rs/skills/src/assets/samples/ include skill-installer, skill-creator, and imagegen — each with scripts and configurations. AGENTS.md files (core/src/agents_md.rs:42) provide per-project instructions: Codex discovers AGENTS.md (and AGENTS.override.md) by walking up from the project root to the current directory, concatenating their contents as system instructions. A fallback project_doc_fallback_filenames config option supports additional filenames. Hooks (core/src/hook_runtime.rs:1) support lifecycle callbacks at session start, user prompt submit, pre/post tool use, compact, and stop events. Hooks can inject context, block/allow actions, and request user permission. Plugins extend tool availability: core/src/plugins/ manages plugin discovery and installation, with tools like RequestPluginInstallHandler for runtime plugin requests. The config system (TOML-based with layered config in core/src/config/) allows full customization of model selection, permissions, approval policies, sandboxing levels, MCP server configuration, and environment definitions. Headless/SDK mode is supported via the exec crate which exposes Codex as an app-server with JSON-RPC (ClientRequest/ServerNotification in exec/src/lib.rs) — consumable by IDE extensions and automated tooling. The codex-cli/bin/package.json enables npm distribution as @openai/codex.