Codex Architecture Overview

源码版本rust-v0.145.0

codex is OpenAI's open-source coding agent. This version is the Rust rewrite (the earlier TypeScript version has been demoted to codex-cli/ as an npm install shim). The main source body lives in codex-rs/, a Cargo workspace that pulls in 90+ independent crates, sliced along responsibility lines. This site breaks it down by crate, and every key file carries a SrcLink that points directly at the corresponding GitHub line.

Overall layering

Major crates at a glance

Layer	crate	Responsibility
CLI entry	cli	subcommand dispatch, doctor, login, mcp_cmd
Agent core	core	agent main loop, LLM client, compaction, session thread, tools
Patch protocol	apply-patch	apply_patch text patch format
Sandbox	sandboxing / linux-sandbox / bwrap / windows-sandbox-rs	cross-platform command isolation
Execution policy	execpolicy	command classification and gating policy
Execution	exec / exec-server	command execution and exec-server protocol
TUI	tui	terminal UI, chatwidget, diff_model
App-server	app-server / app-server-protocol / app-server-transport	orchestration service and protocol
MCP	mcp-server / rmcp-client / codex-mcp / connectors	Model Context Protocol integration
Provider	model-provider / model-provider-info / backend-client	model provider abstraction
Cloud	cloud-tasks / cloud-config	cloud task execution
Config	config / codex-home	config system and home directory
Peripheral	prompts / skills / memories / hooks / plugin / rollout	prompts, skills, memories, hooks, plugins, trace

One sentence per layer

• CLI entry: subcommand dispatch for the codex command; main.rs parses with clap and then routes to each subcommand.
• Agent core: the agent main loop consumes Op, drives LLM calls and tool execution; CodexThread is the entry point for session orchestration.
• Sandbox execution: commands run inside a sandbox; execpolicy first classifies the command to decide allow / block / approve, then hands off to the platform sandbox for isolation.
• TUI / App-server: TUI is the terminal frontend; App-server exposes Agent capabilities to IDEs / external clients via a protocol.
• Provider / Cloud: model-provider abstracts different backends; cloud-tasks ships tasks to run on the cloud.

Design motivation

codex chose Rust for the rewrite; the core motivation is sandbox and performance. A coding agent runs arbitrary shell commands on the user's machine, and without reliable process isolation there is no safety. Rust's type system and zero-cost abstractions let the 90+ crates be sliced at fine granularity without bringing runtime overhead. The workspace splits crates by responsibility rather than one big crate, for incremental compilation and clear boundaries — touching the TUI does not recompile core.

Common misreadings

• "codex is a CLI tool" — only half right. The CLI is just the entry point; what actually runs is the combination of core + sandbox + tui / app-server.
• "The Rust rewrite is for speed" — Rust brings sandbox isolation and process-level security; performance is a byproduct.
• "apply_patch is codex's private format" — it is the text patch protocol codex uses; the model generates it, and the apply-patch crate parses and applies it.

Recommended reading order

1. CLI entry and subcommand dispatch — from the codex command in, see how it dispatches
2. Agent main loop — how the Agent consumes Op to drive the LLM
3. LLM client and Responses API — how it talks to the OpenAI backend
4. Cross-platform sandbox — how commands are isolated
5. execpolicy command classification — how commands are classified and gated
6. App-server architecture — how it exposes itself to external clients via a protocol

After reading this thread, you can basically explain the full chain of codex from "user types a command" to "the LLM runs tools and edits files".