The Codex Codex — an architectural field guide to openai/codex.
An interactive, book-style technical guide that reads the Codex source tree
(openai/codex, ~90 Rust crates) and explains how a production coding agent is
actually built — the turn loop, context engineering, the tool system, the safety
model, extensibility, and the protocol that fronts it all. It is 36 chapters of
prose backed by annotated real source, interactive diagrams (a D3 dependency
graph of every crate, Chart.js breakdowns, Mermaid sequence/flow diagrams), an
architecture map, and the verbatim Codex system prompts.
It ships as a small single-page app: a hash router renders one chapter module at a time into the page, with per-chapter interactive widgets wired up on navigation.
The book is a top-to-bottom pass over the agent, following a single request from the interface it arrives on, through the engine that runs it, to the world it acts on:
- The agent loop — how a thread holds sessions, how a turn is assembled, sent to the model, and folded back in; how work is made durable and replayable.
- Context engineering — treating the prompt as a budget: layered per-model system prompts, diffed self-rendering context fragments, compaction when the window fills, and cross-session memory.
- The tool system — the registry/router and spec-vs-handler split; running shell commands; editing files through a formal patch grammar; deferring rarely-used tools and discovering them on demand; and Code Mode, where the model writes a program instead of making tool calls.
- The safety model — the mandatory gate every side-effect crosses: approval policy, a risk-scoring guardian model, execution policy, and kernel-level OS sandboxes.
- The nervous system — MCP (Codex as both client and server), model providers and auth, and the typed duplex app-server protocol every client speaks.
- Coordinated minds — planning discipline, sub-agent delegation, reusable Skills, and hooks/plugins that extend the loop without forking.
- The edges — the 226k-line terminal UI, headless/cloud execution, and observability (traces, analytics, replay).
- Patterns & retrospective — the recurring design grammar of the codebase and a distilled "what to steal" for building your own agent.
In a fitting twist, the book about Codex was researched and written by a fleet of Codex agents — with Claude Code as the orchestrator and every sub-agent a separate Codex instance. No chapter was written in one pass. Each one was mapped, verified, drafted, reviewed, illustrated, reviewed again, and only then put in front of a human — repeatedly.
The fleet ran continuously for ~9 hours (excluding the author's own reading and comments), then a further ~3 hours of autonomous polishing — roughly 12 hours of agent work in total, wrapped around several human review passes.
flowchart TD
O["Orchestrator · Claude Code"]
O ==> A1["Recon — Researcher + Scanner agents<br/>map ~90 crates into an architecture model"]
A1 --> A2["Deep-dive — one Codex agent per<br/>module & client, running in parallel"]
A2 --> A3{"Reviewers confirm<br/>findings against source"}
A3 -->|gaps| A2
A3 -->|verified| O
O ==> B1["Draft — technical writer<br/>Codex sub-agents"]
B1 --> B2{"Reviewers check<br/>prose against source"}
B2 -->|rewrite| B1
B2 -->|approved| O
O ==> C1["Visualise — diagram & visual<br/>Codex sub-agents"]
C1 --> C2{"Reviewers verify<br/>every diagram"}
C2 -->|fix| C1
C2 -->|approved| O
O ==> H["Author review — human<br/>multiple passes, re-reads, comments"]
H -->|change requests| O
O ==> D["Codex Decoded"]
classDef orch fill:#C8102E,stroke:#8E0A1F,color:#fff;
classDef out fill:#F6C851,stroke:#B57A16,color:#211A0E;
class O orch;
class D out;
Every stage ends at a gate: reviewers loop back to their producers until the work holds up against the actual source, and the orchestrator only advances once a stage is clean. The author sits at the end of the loop — reading the material multiple times and feeding comments back in, which re-opens whichever stages the feedback touches.
sequenceDiagram
autonumber
participant O as Orchestrator (Claude Code)
participant S as Scanner (Codex)
participant R as Reviewer (Codex)
participant W as Writer (Codex)
participant V as Visualiser (Codex)
participant A as Author (human)
O->>S: assign a module / client
S-->>O: findings + source map
O->>R: verify findings vs source
R-->>O: confirmed (or gaps → re-scan)
O->>W: draft chapter from verified findings
W-->>O: chapter draft
O->>R: review prose vs source
R-->>O: approved (or rewrite)
O->>V: create diagrams & visuals
V-->>O: visuals
O->>R: review diagrams
R-->>O: approved (or fix)
O->>A: submit for human review
A-->>O: comments + re-reads (several passes)
O->>O: polish, consolidate, finalise
| Role | Model | What it did |
|---|---|---|
| Orchestrator | Claude Code | Planned the work, dispatched sub-agents, held the quality gates, consolidated everything, and drove the polish pass. |
| Researcher + Scanner | Codex | Read the source tree, mapped ~90 crates and their dependencies, and produced the high-level architecture model. |
| Module deep-dive | Codex | One agent per module/client, in parallel, extracting how each subsystem actually works. |
| Findings reviewers | Codex | Confirmed each agent's findings against the real source before anything was written. |
| Technical writers | Codex | Turned verified findings into chapter prose with annotated, real code. |
| Writing reviewers | Codex | Checked every draft back against the source for accuracy and clarity. |
| Visualisers | Codex | Built the diagrams, interactive graphs, and technical illustrations. |
| Visual reviewers | Codex | Verified each diagram matched the architecture it depicted. |
| Author | Human | Reviewed at multiple checkpoints, re-read the material several times, and sent comments that reopened the loop. |
By the numbers — 1 orchestrator (Claude Code) · a fleet of Codex sub-agents · ~90 crates mapped · 36 chapters · every module and chapter double-reviewed against source · ~9h autonomous + ~3h polish + multiple human review passes.
npm install # install dependencies
npm run dev # start the dev server (http://localhost:5173)
npm run build # produce a static site in dist/
npm run preview # serve the built dist/ locallyThe built dist/ is fully static — deploy it to any static host (Netlify, Vercel,
GitHub Pages, S3, nginx). base: './' in vite.config.js means it also works from
a sub-path.
| Page | What's on it |
|---|---|
| Cover | The book cover and entry point. |
| Contents & roadmap | The full table of contents with a per-chapter brief. |
| The complete map | An interactive architecture map linking every subsystem to its chapter. |
| Preface | How to read this field guide, and the conventions used. |
| # | Chapter | What's covered |
|---|---|---|
| 1 | Architecture at a glance | The whole request path on one page: interfaces, engine, world. |
| 2 | Repository topology | Monorepo layout and the three build systems. |
| 3 | Build & distribution | The npm launcher, platform binaries, and the SDKs. |
| 4 | The crate map | Interactive dependency graph of all ~90 crates. |
| # | Chapter | What's covered |
|---|---|---|
| 5 | Thread · Session · Turn | The core abstractions, walked through with an interactive turn loop. |
| 6 | The ThreadManager | The factory that vends threads and shares services. |
| 7 | Sessions & turn context | Session state, owns-vs-borrows, and steering mid-turn. |
| 8 | Rollout: state & replay | Append-only JSONL rollout: durability, resume, replay. |
| # | Chapter | What's covered |
|---|---|---|
| 9 | System prompts & personalities | System prompts as data — layered, per-model, with full verbatim prompts. |
| 10 | Context assembly | Context assembled from diffed, self-rendering fragments. |
| 11 | Compaction & token budget | Compaction and the token budget when the window fills. |
| 12 | Memories | Cross-session memory via a background consolidation agent. |
| # | Chapter | What's covered |
|---|---|---|
| 13 | The tool system | The registry, router, and the spec/handler split. |
| 14 | Dispatch lifecycle | Dispatch, the RwLock parallel gate, and result mapping. |
| 15 | Shell & unified exec | Running commands: one-shot shell and long-lived exec. |
| 16 | apply_patch | Editing files through a formal patch grammar. |
| 17 | Approvals, safety & sandboxing | Four safety layers: approvals, guardian, execution policy, sandbox. |
| 18 | Tool search & dynamic tools | Deferred tools discovered on demand via BM25 search. |
| 19 | Code Mode | A sandboxed V8 runtime where tools become callable functions. |
| # | Chapter | What's covered |
|---|---|---|
| 20 | MCP: the protocol | Multiplexed MCP clients, transports, and Codex as a server. |
| 21 | MCP tools, resources, elicitation | MCP tool exposure, resources, and elicitation. |
| 22 | Providers & connections | Model providers, transport, and authentication. |
| 23 | The app-server | The typed duplex protocol every client speaks. |
| # | Chapter | What's covered |
|---|---|---|
| 24 | The planning tool | The update_plan checklist and plan discipline. |
| 25 | Sub-agents & delegation | Spawning sub-agents: roles, names, and delegation. |
| 26 | Skills | Reusable SKILL.md capabilities with dependencies. |
| 27 | Hooks & extensibility | Hooks and plugins: extend the loop without forking. |
| # | Chapter | What's covered |
|---|---|---|
| 28 | The TUI | The 226k-line ratatui terminal interface. |
| 29 | Headless: exec & cloud | Headless exec (JSONL) and cloud tasks. |
| 30 | Observability & ops | Telemetry, analytics, replayable traces, and prompt-debug. |
| # | Chapter | What's covered |
|---|---|---|
| 31 | Cross-cutting patterns | The recurring design patterns across the codebase. |
| 32 | What to steal | A distilled checklist, a glossary, and the crate index. |
index.html # page shell + fonts; mounts /src/main.js
vite.config.js
src/
main.js # boot: builds the TOC, hash router, per-chapter initializers
data/
book.js # BOOK (table of contents) + FLAT (flattened chapter list)
chapters/
index.js # CONTENT registry: chapter id -> render function
cover.js … # one module per page (cover, contents, map, preface, ch1–ch32)
lib/
vendor.js # third-party libs (highlight.js, d3, chart.js, mermaid)
code.js # annotated code-block renderer
mermaid.js # mermaid theme + diagram helpers
graph.js # dependency-graph data + D3 force graph + Chart.js charts
map.js # architecture-map data + SVG builder
prompts.js # loads the verbatim prompts and hydrates them into the page
marks.js # decorative inline SVGs
prompts/ # the 8 verbatim Codex system prompts, as plain-text files
base.txt, codex52.txt, compact.txt, friendly.txt,
pragmatic.txt, consolidation.txt, apply-patch.txt, guardian.txt
styles/
base.css # design tokens, reset, layout, typography
components.css # code viewer, diagrams, tables, map, cover, etc.
assets/
cover.jpg # book cover
- Routing —
src/main.jsreadslocation.hash(#/ch5), looks the id up in theCONTENTregistry, calls that chapter's render function to produce an HTML string, and injects it into#view. AstubPagefallback renders an outline for any chapter not yet in the registry. - Chapters as data — every page is a module that default-exports a
() => htmlStringfunction. Shared helpers (code,mmd,fullPrompt, …) are imported at the top of each chapter, so content stays declarative. - Interactive widgets — after a chapter renders, the router runs the relevant initializer: the D3 crate graph and Chart.js charts (crate map), the animated turn stepper (Thread · Session · Turn), the spec/handler toggle (tool system), Mermaid diagrams, and prompt hydration.
- Prompts — the verbatim system prompts live as plain-text files under
src/prompts/, imported with Vite's?rawand injected into the collapsible "read the full prompt" panels.
Vanilla ES modules bundled by Vite — no UI framework. Runtime libraries: highlight.js (code), D3 (force graph), Chart.js (charts), and Mermaid (diagrams).
- A chapter lives in
src/chapters/<id>.jsand default-exports a function that returns an HTML string. Register it insrc/chapters/index.js. Chapters compose content with the helpers imported at the top of each file (code,mmd,fullPrompt, etc.). - A prompt is a plain
.txtfile insrc/prompts/, imported insrc/lib/prompts.jsand keyedpr-<name>sofullPrompt('pr-<name>', …)can render it. - Table of contents / ordering is driven by
src/data/book.js.
Contributions are welcome — corrections, clearer explanations, better diagrams, and coverage of new subsystems. Because this is a source-level guide, technical changes should reflect the actual Codex source and cite the file(s) they come from.
main is protected, so all changes land through pull requests: branch off main,
make sure npm run build passes, open a PR (CI runs a build check), and a maintainer
reviews and merges. On merge the site auto-deploys to
GitHub Pages.
See CONTRIBUTING.md for the full guide — setup, project layout, commit conventions (Conventional Commits), and how to add a chapter, prompt, or diagram.
This project is dual-licensed:
- Code — the application source (everything that makes the site build and run) is licensed under the MIT License.
- Book content — the prose, diagrams, and images are licensed under Creative Commons Attribution 4.0 International (CC BY 4.0).
© 2026 Ahmed Alaa.
Attribution. This is an independent field guide to
openai/codex and is not affiliated with or
endorsed by OpenAI. The verbatim system prompts reproduced under
src/prompts/ originate from openai/codex, which is licensed under
Apache-2.0; all rights to that material remain with its authors.
- Chapter 13 surfaces a benign unhandled-rejection from Mermaid's async renderer; the diagrams still render and it is harmless.