Codex Decoded

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.

What it covers

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.

How this book was built

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.

The pipeline

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 &amp; 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 &amp; 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.

Lifecycle of a single chapter

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

The roles

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.

Quick start

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/ locally

The 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.

#	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.

Part II — The engine room

#	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.

Part III — The mind

#	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.

Part IV — The hands

#	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.

Part V — The nervous system

#	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.

Part VI — Coordinated minds

#	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.

Part VII — The edges

#	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.

Part VIII — Patterns & retrospective

#	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.

Project layout

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

How it works

Routing — src/main.js reads location.hash (#/ch5), looks the id up in the CONTENT registry, calls that chapter's render function to produce an HTML string, and injects it into #view. A stubPage fallback renders an outline for any chapter not yet in the registry.
Chapters as data — every page is a module that default-exports a () => htmlString function. 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 ?raw and injected into the collapsible "read the full prompt" panels.

Tech stack

Vanilla ES modules bundled by Vite — no UI framework. Runtime libraries: highlight.js (code), D3 (force graph), Chart.js (charts), and Mermaid (diagrams).

Adding or editing content

A chapter lives in src/chapters/<id>.js and default-exports a function that returns an HTML string. Register it in src/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 .txt file in src/prompts/, imported in src/lib/prompts.js and keyed pr-<name> so fullPrompt('pr-<name>', …) can render it.
Table of contents / ordering is driven by src/data/book.js.

Contributing

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.

License

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).

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.

Notes

Chapter 13 surfaces a benign unhandled-rejection from Mermaid's async renderer; the diagrams still render and it is harmless.

Codex Decoded

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.

What it covers

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.

How this book was built

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.

The pipeline

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 &amp; 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 &amp; 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.

Lifecycle of a single chapter

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

The roles

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.

Quick start

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/ locally

The 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.

#	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.

Part II — The engine room

#	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.

Part III — The mind

#	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.

Part IV — The hands

#	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.

Part V — The nervous system

#	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.

Part VI — Coordinated minds

#	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.

Part VII — The edges

#	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.

Part VIII — Patterns & retrospective

#	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.

Project layout

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

How it works

Routing — src/main.js reads location.hash (#/ch5), looks the id up in the CONTENT registry, calls that chapter's render function to produce an HTML string, and injects it into #view. A stubPage fallback renders an outline for any chapter not yet in the registry.
Chapters as data — every page is a module that default-exports a () => htmlString function. 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 ?raw and injected into the collapsible "read the full prompt" panels.

Tech stack

Vanilla ES modules bundled by Vite — no UI framework. Runtime libraries: highlight.js (code), D3 (force graph), Chart.js (charts), and Mermaid (diagrams).

Adding or editing content

A chapter lives in src/chapters/<id>.js and default-exports a function that returns an HTML string. Register it in src/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 .txt file in src/prompts/, imported in src/lib/prompts.js and keyed pr-<name> so fullPrompt('pr-<name>', …) can render it.
Table of contents / ordering is driven by src/data/book.js.

Contributing

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.

License

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).

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.

Notes

Chapter 13 surfaces a benign unhandled-rejection from Mermaid's async renderer; the diagrams still render and it is harmless.

Codex Decoded

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.

What it covers

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.

How this book was built

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.

The pipeline

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 &amp; 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 &amp; 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.

Lifecycle of a single chapter

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

The roles

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.

Quick start

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/ locally

The 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.

#	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.

Part II — The engine room

#	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.

Part III — The mind

#	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.

Part IV — The hands

#	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.

Part V — The nervous system

#	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.

Part VI — Coordinated minds

#	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.

Part VII — The edges

#	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.

Part VIII — Patterns & retrospective

#	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.

Project layout

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

How it works

Routing — src/main.js reads location.hash (#/ch5), looks the id up in the CONTENT registry, calls that chapter's render function to produce an HTML string, and injects it into #view. A stubPage fallback renders an outline for any chapter not yet in the registry.
Chapters as data — every page is a module that default-exports a () => htmlString function. 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 ?raw and injected into the collapsible "read the full prompt" panels.

Tech stack

Vanilla ES modules bundled by Vite — no UI framework. Runtime libraries: highlight.js (code), D3 (force graph), Chart.js (charts), and Mermaid (diagrams).

Adding or editing content

A chapter lives in src/chapters/<id>.js and default-exports a function that returns an HTML string. Register it in src/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 .txt file in src/prompts/, imported in src/lib/prompts.js and keyed pr-<name> so fullPrompt('pr-<name>', …) can render it.
Table of contents / ordering is driven by src/data/book.js.

Contributing

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.

License

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).

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.

Notes

Chapter 13 surfaces a benign unhandled-rejection from Mermaid's async renderer; the diagrams still render and it is harmless.

Codex Decoded

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.

What it covers

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.

How this book was built

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.

The pipeline

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 &amp; 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 &amp; 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.

Lifecycle of a single chapter

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

The roles

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.

Quick start

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/ locally

The 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.

#	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.

Part II — The engine room

#	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.

Part III — The mind

#	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.

Part IV — The hands

#	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.

Part V — The nervous system

#	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.

Part VI — Coordinated minds

#	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.

Part VII — The edges

#	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.

Part VIII — Patterns & retrospective

#	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.

Project layout

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

How it works

Routing — src/main.js reads location.hash (#/ch5), looks the id up in the CONTENT registry, calls that chapter's render function to produce an HTML string, and injects it into #view. A stubPage fallback renders an outline for any chapter not yet in the registry.
Chapters as data — every page is a module that default-exports a () => htmlString function. 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 ?raw and injected into the collapsible "read the full prompt" panels.

Tech stack

Vanilla ES modules bundled by Vite — no UI framework. Runtime libraries: highlight.js (code), D3 (force graph), Chart.js (charts), and Mermaid (diagrams).

Adding or editing content

A chapter lives in src/chapters/<id>.js and default-exports a function that returns an HTML string. Register it in src/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 .txt file in src/prompts/, imported in src/lib/prompts.js and keyed pr-<name> so fullPrompt('pr-<name>', …) can render it.
Table of contents / ordering is driven by src/data/book.js.

Contributing

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.

License

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).

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.

Notes

Chapter 13 surfaces a benign unhandled-rejection from Mermaid's async renderer; the diagrams still render and it is harmless.

Codex Decoded

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.

What it covers

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.

How this book was built

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.

The pipeline

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 &amp; 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 &amp; 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.

Lifecycle of a single chapter

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

The roles

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.

Quick start

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/ locally

The 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.

#	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.

Part II — The engine room

#	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.

Part III — The mind

#	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.

Part IV — The hands

#	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.

Part V — The nervous system

#	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.

Part VI — Coordinated minds

#	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.

Part VII — The edges

#	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.

Part VIII — Patterns & retrospective

#	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.

Project layout

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

How it works

Routing — src/main.js reads location.hash (#/ch5), looks the id up in the CONTENT registry, calls that chapter's render function to produce an HTML string, and injects it into #view. A stubPage fallback renders an outline for any chapter not yet in the registry.
Chapters as data — every page is a module that default-exports a () => htmlString function. 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 ?raw and injected into the collapsible "read the full prompt" panels.

Tech stack

Vanilla ES modules bundled by Vite — no UI framework. Runtime libraries: highlight.js (code), D3 (force graph), Chart.js (charts), and Mermaid (diagrams).

Adding or editing content

A chapter lives in src/chapters/<id>.js and default-exports a function that returns an HTML string. Register it in src/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 .txt file in src/prompts/, imported in src/lib/prompts.js and keyed pr-<name> so fullPrompt('pr-<name>', …) can render it.
Table of contents / ordering is driven by src/data/book.js.

Contributing

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.

License

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).

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.

Notes

Chapter 13 surfaces a benign unhandled-rejection from Mermaid's async renderer; the diagrams still render and it is harmless.

Codex Decoded

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.

What it covers

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.

How this book was built

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.

The pipeline

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 &amp; 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 &amp; 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.

Lifecycle of a single chapter

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

The roles

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.

Quick start

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/ locally

The 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.

#	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.

Part II — The engine room

#	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.

Part III — The mind

#	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.

Part IV — The hands

#	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.

Part V — The nervous system

#	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.

Part VI — Coordinated minds

#	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.

Part VII — The edges

#	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.

Part VIII — Patterns & retrospective

#	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.

Project layout

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

How it works

Routing — src/main.js reads location.hash (#/ch5), looks the id up in the CONTENT registry, calls that chapter's render function to produce an HTML string, and injects it into #view. A stubPage fallback renders an outline for any chapter not yet in the registry.
Chapters as data — every page is a module that default-exports a () => htmlString function. 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 ?raw and injected into the collapsible "read the full prompt" panels.

Tech stack

Vanilla ES modules bundled by Vite — no UI framework. Runtime libraries: highlight.js (code), D3 (force graph), Chart.js (charts), and Mermaid (diagrams).

Adding or editing content

A chapter lives in src/chapters/<id>.js and default-exports a function that returns an HTML string. Register it in src/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 .txt file in src/prompts/, imported in src/lib/prompts.js and keyed pr-<name> so fullPrompt('pr-<name>', …) can render it.
Table of contents / ordering is driven by src/data/book.js.

Contributing

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.

License

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).

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.

Notes

Chapter 13 surfaces a benign unhandled-rejection from Mermaid's async renderer; the diagrams still render and it is harmless.

Codex Decoded

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.

What it covers

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.

How this book was built

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.

The pipeline

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 &amp; 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 &amp; 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.

Lifecycle of a single chapter

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

The roles

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.

Quick start

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/ locally

The 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.

#	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.

Part II — The engine room

#	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.

Part III — The mind

#	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.

Part IV — The hands

#	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.

Part V — The nervous system

#	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.

Part VI — Coordinated minds

#	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.

Part VII — The edges

#	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.

Part VIII — Patterns & retrospective

#	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.

Project layout

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

How it works

Routing — src/main.js reads location.hash (#/ch5), looks the id up in the CONTENT registry, calls that chapter's render function to produce an HTML string, and injects it into #view. A stubPage fallback renders an outline for any chapter not yet in the registry.
Chapters as data — every page is a module that default-exports a () => htmlString function. 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 ?raw and injected into the collapsible "read the full prompt" panels.

Tech stack

Vanilla ES modules bundled by Vite — no UI framework. Runtime libraries: highlight.js (code), D3 (force graph), Chart.js (charts), and Mermaid (diagrams).

Adding or editing content

A chapter lives in src/chapters/<id>.js and default-exports a function that returns an HTML string. Register it in src/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 .txt file in src/prompts/, imported in src/lib/prompts.js and keyed pr-<name> so fullPrompt('pr-<name>', …) can render it.
Table of contents / ordering is driven by src/data/book.js.

Contributing

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.

License

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).

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.

Notes

Chapter 13 surfaces a benign unhandled-rejection from Mermaid's async renderer; the diagrams still render and it is harmless.

Codex Decoded

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.

What it covers

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.

How this book was built

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.

The pipeline

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 &amp; 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 &amp; 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.

Lifecycle of a single chapter

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

The roles

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.

Quick start

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/ locally

The 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.

#	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.

Part II — The engine room

#	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.

Part III — The mind

#	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.

Part IV — The hands

#	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.

Part V — The nervous system

#	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.

Part VI — Coordinated minds

#	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.

Part VII — The edges

#	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.

Part VIII — Patterns & retrospective

#	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.

Project layout

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

How it works

Routing — src/main.js reads location.hash (#/ch5), looks the id up in the CONTENT registry, calls that chapter's render function to produce an HTML string, and injects it into #view. A stubPage fallback renders an outline for any chapter not yet in the registry.
Chapters as data — every page is a module that default-exports a () => htmlString function. 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 ?raw and injected into the collapsible "read the full prompt" panels.

Tech stack

Vanilla ES modules bundled by Vite — no UI framework. Runtime libraries: highlight.js (code), D3 (force graph), Chart.js (charts), and Mermaid (diagrams).

Adding or editing content

A chapter lives in src/chapters/<id>.js and default-exports a function that returns an HTML string. Register it in src/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 .txt file in src/prompts/, imported in src/lib/prompts.js and keyed pr-<name> so fullPrompt('pr-<name>', …) can render it.
Table of contents / ordering is driven by src/data/book.js.

Contributing

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.

License

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).

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.

Notes

Chapter 13 surfaces a benign unhandled-rejection from Mermaid's async renderer; the diagrams still render and it is harmless.

Name		Name	Last commit message	Last commit date
.github/workflows		.github/workflows
public		public
src		src
.gitignore		.gitignore
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
LICENSE-CONTENT		LICENSE-CONTENT
README.md		README.md
index.html		index.html
package-lock.json		package-lock.json
package.json		package.json
vite.config.js		vite.config.js

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.

Name		Name	Last commit message	Last commit date
.github/workflows		.github/workflows
public		public
src		src
.gitignore		.gitignore
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
LICENSE-CONTENT		LICENSE-CONTENT
README.md		README.md
index.html		index.html
package-lock.json		package-lock.json
package.json		package.json
vite.config.js		vite.config.js

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.

Name		Name	Last commit message	Last commit date
.github/workflows		.github/workflows
public		public
src		src
.gitignore		.gitignore
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
LICENSE-CONTENT		LICENSE-CONTENT
README.md		README.md
index.html		index.html
package-lock.json		package-lock.json
package.json		package.json
vite.config.js		vite.config.js

Latest commit

History

Folders and files

Repository files navigation

Codex Decoded

What it covers

How this book was built

The pipeline

Lifecycle of a single chapter

The roles

Quick start

Contents

Start here

Part I — The lay of the land

Part II — The engine room

Part III — The mind

Part IV — The hands

Part V — The nervous system

Part VI — Coordinated minds

Part VII — The edges

Part VIII — Patterns & retrospective

Project layout

How it works

Tech stack

Adding or editing content

Contributing

License

Notes

About

Resources

Contributing

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

Codex Decoded

What it covers

How this book was built

The pipeline

Lifecycle of a single chapter

The roles

Quick start

Contents

Start here

Part I — The lay of the land

Part II — The engine room

Part III — The mind

Part IV — The hands

Part V — The nervous system

Part VI — Coordinated minds

Part VII — The edges

Part VIII — Patterns & retrospective

Project layout

How it works

Tech stack

Adding or editing content

Contributing

License

Notes

About

Resources

Contributing

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation