Codex Source Reader Map: Follow the Turn, Not the Tree

Reading Contract: This page assumes the Preface has already explained why Codex is best read as a governed turn. The question here is more practical: when one user request enters the system, which source path should you choose next? Track the owner, the typed carrier, the authority boundary, and the evidence that survives after the UI has rendered.

The Codex repository is large enough to reward almost any first guess. You can start from the CLI and find a real product surface. You can start from the TUI and find user-visible state. You can start from protocol types and find the shared vocabulary. You can start from tools, MCP, sandboxing, app-server code, memory, plugins, cloud-task clients, or release workflows and still be looking at something important.

That is exactly why a reader map needs a route, not a directory inventory. This page is for the moment after the Preface has supplied the mental model. Instead of asking “what is Codex?”, ask a narrower question: given one ordinary user turn, which source owner has the next decision?

The source snapshot used here is 569ff6a1c400bd514ff79f5f1050a684dc3afde3. Every source link is pinned to that commit so the reading route remains auditable after main changes.

File Tree Pressure

A file tree is good at showing nouns: cli, core, protocol, tui, app-server, mcp, exec, sandbox, plugins, cloud-tasks, release. It is bad at showing ownership. The same user request may pass through several of those nouns before anything visible happens.

The pressure point is therefore not “which folder is most important?” It is “which boundary would be wrong if I skipped it?”

Read folders as pressure points. A chapter should earn attention because it protects one of the turn’s invariants: intent must be typed, context must be owned, model output must not become authority by itself, side effects must cross policy, and evidence must remain reviewable.

Follow One User Turn

Use a deliberately ordinary request:

Change a file in this workspace, run a check if needed, and report what happened.

That request gives you a live routing test. At each step, stop reading the current file as soon as you know who owns the next decision.

This route keeps the Preface’s queue-pair model in the background without repeating it. The Preface explains why submissions and events are the smallest runtime contract. This page uses that contract as a compass: when the request leaves one owner, find the typed handoff to the next owner.

The Source Mechanism: Choose The Next Owner

The source route has three common switching points. Each one is a place where a reader should change files because the current owner has done its job.

Entry Code Shows Surfaces, Not The Whole Architecture

At the pinned commit, the CLI’s Subcommand enum is enough to show that Codex exposes many entry surfaces. An abridged excerpt makes the point:

enum Subcommand {
    Exec(ExecCli),
    Review(ReviewArgs),
    // login, logout, and other local commands omitted
    Mcp(McpCli),
    Plugin(PluginCli),
    McpServer,
    AppServer(AppServerCommand),
    RemoteControl,
    Sandbox(SandboxArgs),
    Debug(DebugCommand),
}

Do not turn that snippet into “the CLI is the architecture.” It is a route marker. Once an entry surface has converted a command into a typed request, the next question belongs to the protocol and runtime, not to argument parsing.

The Turn Function Marks Runtime Ownership

The governed turn is where context, model streaming, pending input, tool calls, compaction, cancellation, and completion start meeting in one place. The signature of run_turn is a compact source anchor:

pub(crate) async fn run_turn(
    sess: Arc<Session>,
    turn_context: Arc<TurnContext>,
    input: Vec<UserInput>,
    prewarmed_client_session: Option<ModelClientSession>,
    cancellation_token: CancellationToken,
) -> Option<String> {

Read this as an ownership signal. The turn is not just a model call. It receives session state, turn-scoped context, user input, optional provider session state, and cancellation. If you are auditing a claim about what happens during a user request, this is the point where entry-surface reading should become runtime reading.

Tool Code Matters Only After Authority Is In View

Tool implementation files are attractive because they are concrete: shell, patch, filesystem, MCP, network, and sandbox behavior all look like “the action.” The map is safer if you first ask how the action is authorized and attempted. ToolOrchestrator shows the owner that sits before concrete execution:

pub(crate) struct ToolOrchestrator {
    sandbox: SandboxManager,
}

That small struct points to a larger route: approval context, sandbox selection, permission hooks, network approval, attempts, retry behavior, and result shaping. A source reader should open the concrete shell or patch handler only after locating the authority path that lets the handler run.

Common Misreadings

These mistakes have the same shape: they stop at the first familiar surface. The corrective move is always to ask which owner carries the request next.

Reading Routes

The timed routes are not the argument. They are ways to spend attention after the turn route is clear.

30-Minute Route

Use this path when you need the fastest reliable mental model.

After this route, you should be able to narrate one request from entry surface to typed operation, turn owner, model stream, tool authority, event evidence, and client-visible result.

2-Hour Route

Use this path when you want source-grounded architecture knowledge without opening every GitHub link.

1. Read the Preface, then Chapters 1-8. This gives the bounded runtime model, startup narrowing, configuration, protocol, session ownership, turn loop, provider streaming, and rollout evidence.
2. Read Chapters 9-16. This follows model-visible tool specifications into routing, shell, patch, hooks, human approval, sandboxing, app-server, SDKs, daemon control, and TUI rendering.
3. Read Chapters 17-22. This covers MCP, skills, plugins, migration, multi-agent coordination, cloud task boundaries, identity, and memory.
4. Read Chapters 23-25 and the epilogue. This explains why build systems, generated contracts, packaging, release workflows, and CI policy are part of the architecture rather than delivery chores.
5. Use the Pattern Index, Source Atlas, and Implementation Reference only after the narrative route is stable.

The two-hour route should leave you with owner boundaries, not trivia. You should know which facts are runtime contracts, which are client projections, which are authority gates, and which are release-time enforcement.

Source-Audit Route

Use this path when you want to verify claims against the pinned commit.

For a focused audit, open only these anchors first:

1. Submission, Op, Event, and EventMsg for the shared protocol vocabulary.
2. Codex, submit, and next_event for the session facade.
3. session/turn.rs for the governed turn.
4. ToolOrchestrator for approval, sandbox, attempt, and retry ownership.
5. MessageProcessor and ChatWidget for client projection.
6. rust-release.yml and verify_tui_core_boundary.py for release and governance evidence.

Transferable Rules

The reusable lesson is to design a reading route before you design a reading list.

If a source tree feels too large, do not open more files. Pick one ordinary request and follow the owners that carry it. When the owner changes, change files. When the owner is still the same, keep reading.

Source Map

The map below is the compact version of the whole route. It is intentionally claim-oriented rather than folder-oriented.

Use the Source Atlas when you need denser anchors, and use the Implementation Reference when you already know the route and need exact subsystem facts. This page’s job is simpler: keep one request moving through the right owners until the source tree becomes a path instead of a pile.