Architecture, Patterns, Internals

Codex From Source: read Codex as a system.

A source-pinned architecture book that explains Codex as an event-sourced agent runtime with typed contracts, policy-gated tools, replayable state, multiple clients, extensions, cloud workflows, and executable governance.

Start reading Source atlas

Codex From Source as a bounded agent runtime with entry points, protocol, session runtime, tools, clients, and governance — Codex is best read as one bounded agent runtime: entry points, typed protocol, session runtime, tools and policy, clients, and governance.

Contracts first

Start with operations, events, threads, turns, and items before reading UI code.

Runtime spine

Follow session state, turn scheduling, provider streaming, and rollout trace as one loop.

Side effects

Read tools, shell, patches, approvals, hooks, sandboxes, and network policy as one authority stack.

Surfaces and governance

Finish with app-server, SDKs, TUI, extensions, cloud tasks, release, and CI.

Source-Grounded

The book is designed so readers can understand architecture, data flow, contracts, and trade-offs before opening the pinned source links.

Publication-Grade

Chapters are organized as a technical book: each layer solves one problem and prepares the next.

Source-Pinned

All source links point to 569ff6a1c400bd514ff79f5f1050a684dc3afde3, so auditability does not depend on branch state.

Part 1

Establish the Contract

A complex agent becomes legible when every actor speaks typed runtime language.

1 The Architectural Bet Agent as a bounded operating system. 2 From Distribution Wrapper to Rust Router How startup narrows user intent into a typed command path. 3 Configuration, Authentication, and Managed Requirements How policy and identity become runtime constraints. 4 The Protocol Boundary The typed vocabulary shared by clients, sessions, and replays.

Part 2

Build the Runtime

The runtime is a scheduler for context, streaming, tools, cancellation, and replay.

5 Threads, Sessions, and Durable State Ownership, queues, history, rollout, and resumability. 6 The Turn Loop Where context, model streaming, tools, and continuation meet. 7 Model Providers, Streaming, and Backend Tasks Provider transport, event normalization, and backend-task boundaries. 8 Observability and Rollout Trace How raw runtime facts become replayable and inspectable.

Part 3

Execute Side Effects

The model can suggest an action. Codex decides whether it becomes an effect.

9 Tool Specifications, Routing, and Dispatch How model-visible tools become governed side effects. 10 Shell, Exec Server, and Filesystem Tools Process and filesystem capabilities under runtime policy. 11 Patches as a First-Class Editing Protocol Structured mutation instead of opaque shell edits. 12 Hooks and Human Approval Policy gates before risky actions reach the world. 13 Sandboxes, Network Policy, and Platform Boundaries Platform containment and network mediation.

Part 4

Open the Runtime

A runtime becomes a platform when many clients share one thread model.

14 The App-Server Contract The JSON-RPC boundary for clients and SDKs. 15 SDKs, Daemons, and Remote Control How external clients reach the same runtime. 16 The TUI as an Event Renderer Terminal UI as projection, not alternate runtime.

Part 5

Extend the System

Extension points are useful only when every trust boundary is explicit.

17 MCP: External Tools Without Runtime Entanglement External tool servers behind provenance and routing boundaries. 18 Skills, Plugins, Connectors, and Typed Extensions Extension packaging with explicit trust planes. 19 External Migration and Backward Compatibility Compatibility as a runtime and product constraint.

Part 6

Coordinate Work

Durable work needs graph edges, task contracts, and controlled memory.

20 Multi-Agent Coordination Threads, graph edges, and child-agent outcomes. 21 Cloud Tasks, Identity, and Remote Work Remote work as task contracts plus local verification. 22 Memories and User-Level State Long-term context as a controlled side channel.

Part 7

Ship and Govern

Architecture survives when release and CI enforce it.

23 Build Systems and Generated Contracts How build overlays and generated schemas enforce boundaries. 24 Packaging, Release, and Native Dependencies The path from Rust workspace to npm-distributed binaries. 25 CI, Policy, and Architectural Governance Executable checks that keep architecture honest.

E Epilogue: What to Steal The transferable design lessons from the full system.

Reference pages

Pattern Index A compact index of transferable patterns. Source Atlas Pinned source anchors for auditability. Implementation Reference Dense subsystem reference for source-level review. Bibliography Source and reference bibliography. Production Pipeline How the book was produced and checked.