Source Atlas

Reading Contract: Use this atlas only after the narrative is clear. Open pinned links to verify owners, boundaries, and evidence rather than to discover the story from scratch.

This atlas is the source-audit index for the book. All Codex links point to public GitHub code pinned to commit 569ff6a1c400bd514ff79f5f1050a684dc3afde3. The chapters should be readable without opening these links; the atlas exists so a reader can verify the book’s claims without hunting through the repository.

Audit rule: open an anchor only to confirm the claim class. Direct type, function, constant, workflow, or test behavior counts as verified source. A boundary that emerges from several anchors counts as surrounding contract inference and should stay abstract in prose and figures. Anything that depends on private service internals is not visible and is intentionally absent from this atlas.

Chapter Anchors

Chapter 1: The Architectural Bet: Agent as a Bounded Operating System

• Runtime vocabulary: codex-rs/protocol/src/protocol.rs
• Operation enum: codex-rs/protocol/src/protocol.rs
• Event stream: codex-rs/protocol/src/protocol.rs
• Session facade: codex-rs/core/src/session/mod.rs

Chapter 2: From Distribution Wrapper to Rust Router

• npm launch wrapper: codex-cli/bin/codex.js
• Rust command router: codex-rs/cli/src/main.rs
• App command boundary: codex-rs/cli/src/app_cmd.rs
• App-server daemon commands: codex-rs/cli/src/main.rs

Chapter 3: Configuration, Authentication, and Managed Requirements

• Resolved permissions: codex-rs/core/src/config/mod.rs
• Permission compilation: codex-rs/core/src/config/permissions.rs
• Managed feature gates: codex-rs/core/src/config/managed_features.rs
• Public permission profile: codex-rs/app-server-protocol/src/protocol/v2/permissions.rs

Chapter 4: The Protocol Boundary

• Core submissions and events: codex-rs/protocol/src/protocol.rs
• App-server JSON-RPC envelope: codex-rs/app-server-protocol/src/jsonrpc_lite.rs
• V2 protocol families: codex-rs/app-server-protocol/src/protocol/v2/mod.rs
• Event-to-item mapping: codex-rs/app-server-protocol/src/protocol/event_mapping.rs
• Schema export: codex-rs/app-server-protocol/src/export.rs

Chapter 5: Threads, Sessions, and Durable State

• Thread manager boundary: codex-rs/core/src/thread_manager.rs
• Client-facing thread handle: codex-rs/core/src/codex_thread.rs
• Queue-pair runtime facade: codex-rs/core/src/session/mod.rs
• Model-visible history: codex-rs/core/src/context_manager/history.rs
• Accepted prompt recording: codex-rs/core/src/session/mod.rs

Chapter 6: The Turn Loop: Where the Agent Becomes an Agent

• Turn loop implementation: codex-rs/core/src/session/turn.rs
• Prompt hook ordering: codex-rs/core/src/session/turn.rs
• Accepted prompt recording: codex-rs/core/src/session/turn.rs
• Model client session: codex-rs/core/src/client.rs
• Context manager: codex-rs/core/src/context_manager/history.rs

Chapter 7: Model Providers, Streaming, and Backend Tasks

• Model client: codex-rs/core/src/client.rs
• Provider prompt shape: codex-rs/core/src/client_common.rs
• Model client session: codex-rs/core/src/client.rs
• WebSocket behavior tests: codex-rs/core/tests/suite/agent_websocket.rs
• Backend task API contrast: codex-rs/cloud-tasks-client/src/api.rs

Chapter 8: Observability and Rollout Trace

• Trace session model: codex-rs/rollout-trace/src/model/session.rs
• Codex turn trace model: codex-rs/rollout-trace/src/model/session.rs
• Runtime trace payloads: codex-rs/rollout-trace/src/protocol_event.rs
• Core event mapping: codex-rs/core/src/event_mapping.rs

Chapter 9: Tool Specifications, Routing, and Dispatch

• Tool spec planner: codex-rs/core/src/tools/spec_plan.rs
• Tool router: codex-rs/core/src/tools/router.rs
• Tool registry: codex-rs/core/src/tools/registry.rs
• Tool orchestrator: codex-rs/core/src/tools/orchestrator.rs
• Parallel dispatch rules: codex-rs/core/src/tools/parallel.rs

Chapter 10: Shell, Exec Server, and Filesystem Tools

• Shell handler: codex-rs/core/src/tools/handlers/shell/shell_handler.rs
• Unified exec handler: codex-rs/core/src/tools/handlers/unified_exec/exec_command.rs
• Exec policy manager: codex-rs/core/src/exec_policy.rs
• Exec-server RPC client: codex-rs/exec-server/src/rpc.rs
• Executor filesystem handler: codex-rs/exec-server/src/server/file_system_handler.rs

Chapter 11: Patches as a First-Class Editing Protocol

• Patch tool handler: codex-rs/core/src/tools/handlers/apply_patch.rs
• Patch runtime: codex-rs/core/src/tools/runtimes/apply_patch.rs
• Patch grammar parser: codex-rs/apply-patch/src/parser.rs
• Patch safety assessment: codex-rs/core/src/safety.rs
• Turn diff tracker: codex-rs/core/src/turn_diff_tracker.rs

Chapter 12: Hooks and Human Approval

• Hook event vocabulary: codex-rs/hooks/src/types.rs
• Hook registry: codex-rs/hooks/src/registry.rs
• Prompt hook runtime: codex-rs/core/src/hook_runtime.rs
• Guardian review path: codex-rs/core/src/guardian/review.rs
• Tool orchestrator gates: codex-rs/core/src/tools/orchestrator.rs

Chapter 13: Sandboxes, Network Policy, and Platform Boundaries

• Sandbox type selection: codex-rs/sandboxing/src/manager.rs
• Platform sandbox choice: codex-rs/sandboxing/src/manager.rs
• macOS Seatbelt policy: codex-rs/sandboxing/src/seatbelt.rs
• Linux helper entry: codex-rs/linux-sandbox/src/main.rs
• Linux proxy routing: codex-rs/linux-sandbox/src/proxy_routing.rs
• Windows sandbox setup: codex-rs/windows-sandbox-rs/src/setup.rs
• Network proxy policy: codex-rs/network-proxy/src/config.rs

Chapter 14: The App-Server Contract

• Protocol envelopes and schemas: codex-rs/app-server-protocol/src
• Transport normalization: codex-rs/app-server-transport/src/transport/mod.rs
• Message processor: codex-rs/app-server/src/message_processor.rs
• Request serialization: codex-rs/app-server/src/request_serialization.rs
• Thread state and pending requests: codex-rs/app-server/src/thread_state.rs

Chapter 15: SDKs, Daemons, and Remote Control

• App-server daemon lifecycle: codex-rs/app-server-daemon/src/lib.rs
• Remote control mode: codex-rs/app-server-daemon/src/lib.rs
• Transport modes: codex-rs/app-server-transport/src/transport/mod.rs
• stdio transport: codex-rs/app-server-transport/src/transport/stdio.rs
• WebSocket transport: codex-rs/app-server-transport/src/transport/websocket.rs
• Python public API: sdk/python/src/codex_app_server/api.py
• TypeScript public API: sdk/typescript/src/codex.ts

Chapter 16: The TUI as an Event Renderer

• TUI chat widget: codex-rs/tui/src/chatwidget.rs
• Bottom pane state: codex-rs/tui/src/bottom_pane/mod.rs
• TUI app-server session: codex-rs/tui/src/app_server_session.rs
• App events: codex-rs/tui/src/app_event.rs
• Rendering tests: codex-rs/tui/src/chatwidget/tests/exec_flow.rs

Chapter 17: MCP: External Tools Without Runtime Entanglement

• MCP configuration: codex-rs/codex-mcp/src/mcp/mod.rs
• Connection manager: codex-rs/codex-mcp/src/connection_manager.rs
• MCP tool info: codex-rs/codex-mcp/src/tools.rs
• Core tool exposure: codex-rs/core/src/mcp_tool_exposure.rs
• Outbound Codex MCP server: codex-rs/mcp-server/src/message_processor.rs

Chapter 18: Skills, Plugins, Connectors, and Typed Extensions

• Skills manager: codex-rs/core-skills/src/manager.rs
• Skill metadata model: codex-rs/core-skills/src/model.rs
• Plugin manifest: codex-rs/core-plugins/src/manifest.rs
• Plugin manager: codex-rs/core-plugins/src/manager.rs
• Connector directory model: codex-rs/connectors/src/lib.rs
• Typed prompt extension API: codex-rs/ext/extension-api/src/contributors/prompt.rs

Chapter 19: External Migration and Backward Compatibility

• External config model: codex-rs/app-server/src/config/external_agent_config.rs
• Migration request processor: codex-rs/app-server/src/request_processors/external_agent_config_processor.rs
• TUI migration startup: codex-rs/tui/src/external_agent_config_migration_startup.rs
• Protocol compatibility surface: codex-rs/app-server-protocol/src/protocol/mod.rs
• Thread store: codex-rs/thread-store/src

Chapter 20: Multi-Agent Coordination

• Graph edge status: codex-rs/agent-graph-store/src/types.rs
• Local graph store: codex-rs/agent-graph-store/src/local.rs
• Agent trace reducer: codex-rs/rollout-trace/src/reducer/tool/agents.rs
• Session multi-agent integration: codex-rs/core/src/session/multi_agents.rs
• Multi-agent tool handlers: codex-rs/core/src/tools/handlers/multi_agents.rs

Chapter 21: Cloud Tasks, Identity, and Remote Work

• Cloud task API: codex-rs/cloud-tasks-client/src/api.rs
• HTTP backend client: codex-rs/cloud-tasks-client/src/http.rs
• Mock backend: codex-rs/cloud-tasks-mock-client/src/mock.rs
• Agent identity material: codex-rs/agent-identity/src/lib.rs
• Local diff discipline: codex-rs/core/src/turn_diff_tracker.rs

Chapter 22: Memories and User-Level State

• Memory usage kinds: codex-rs/memories/read/src/usage.rs
• Citation parser: codex-rs/memories/read/src/citations.rs
• Read-only MCP memory service: codex-rs/memories/mcp/src
• Stage 1 extraction: codex-rs/memories/write/src/phase1.rs
• Stage 2 consolidation: codex-rs/memories/write/src/phase2.rs

Chapter 23: Build Systems and Generated Contracts

• Cargo workspace: codex-rs/Cargo.toml
• Bazel module: MODULE.bazel
• Bazel crate macros: defs.bzl
• Bazel release-build verification: .github/workflows/bazel.yml
• App-server schema export: codex-rs/app-server-protocol/src/bin/export.rs

Chapter 24: Packaging, Release, and Native Dependencies

• npm wrapper package: codex-cli/package.json
• npm package builder: codex-cli/scripts/build_npm_package.py
• Native dependency installer: codex-cli/scripts/install_native_deps.py
• Cargo release build workflow: .github/workflows/rust-release.yml
• Release artifact staging: .github/workflows/rust-release.yml
• npm package staging: .github/workflows/rust-release.yml
• V8 dependency release surface: third_party/v8/README.md

Chapter 25: CI, Policy, and Architectural Governance

• Main CI workflow: .github/workflows/rust-ci.yml
• Full CI matrix: .github/workflows/rust-ci-full.yml
• Bazel verification workflow: .github/workflows/bazel.yml
• Blob-size policy: scripts/check_blob_size.py
• TUI/core boundary check: .github/scripts/verify_tui_core_boundary.py
• Cargo workspace governance: .github/scripts/verify_cargo_workspace_manifests.py

Epilogue: What to Steal

• protocol: protocol
• core session runtime: core session runtime
• app-server: app-server
• tool execution: tool execution
• rollout trace: rollout trace
• repository governance: repository governance

Reading Order

If you only have one hour for source audit, read in this order:

1. Submission, Op, Event, and EventMsg to learn the runtime vocabulary.
2. Codex, CodexThread, and ThreadManager to understand ownership.
3. session/turn.rs to see the turn loop, hook ordering, sampling, continuation, and completion.
4. Tool planning, routing, registry, and orchestration to see why tools are governed side effects rather than callbacks.
5. App-server message processing and TUI rendering to see how clients share the runtime.
6. Sandbox management, cloud tasks, memory write phases, and release workflows for the advanced subsystems.

Audit Rule

When a chapter and this atlas disagree, treat it as a book bug. The atlas is not a replacement for chapter narrative; it is the compact map that lets the narrative remain source-grounded without turning every chapter into a file listing.