CODEX KOANS

FIELD HANDBOOK · CODEX-2026.08-V1

Understand the machine
one failure at a time.

Forty-eight small, deterministic Rust exercises model the architecture of Codex CLI. No API key. No Codex install. No network. Just a failing koan, a focused repair, and the production source beside it.

Begin the path ↓ Repository ↗
RED → GREEN48KOANS
Op ↓ Event ↑ Tool ↻
48
sequential exercises
12
architecture chapters
0
runtime dependencies

01 · THE PRACTICE

Stop. Repair. Reflect.

The runner deliberately stops at the first broken invariant. Resist the urge to skip ahead: the sequence is the curriculum.

  1. 01

    Run

    cargo koans

    Meet the earliest exercise that is not yet green.

  2. 02

    Read

    Use the focused failure, meditation, and pinned production source.

  3. 03

    Repair

    Make the smallest change that restores the modeled invariant.

  4. 04

    Repeat

    Rerun. The next failure becomes the next lesson.

cargo koansnext lesson
cargo koans -- --hintone bounded nudge
cargo koans -- --recapreview what passed
cargo koans -- --listview the trail

02 · SYSTEM MAP

One core, many boundaries.

Select a component to isolate its four koans. Responsibility flows clockwise from entry points to orchestration, state, presentation, and extension.

THE PROTOCOL CONTRACT

Op enters.
EventMsg leaves.

Interfaces submit typed intent. Core emits typed observations. That boundary lets a terminal, a JSONL process, and an app server present the same underlying work.

THE LIFETIME MODEL

Thread ≠ turn ≠ step.

Thread
Durable identity and history.
Turn
One user request and its client session.
Step
One model sample plus resulting tool work.

03 · THE HEARTBEAT

A turn can sample more than once.

A tool call is not the end of a turn. Its typed result returns to context and the model samples again until it produces a final answer.

Ready
00

Step through a complete tool-using turn.

04 · THE TRAIL

Twelve components. Forty-eight repairs.

FROZEN, NOT FORGOTTEN

The lesson is versioned; the comparison is explicit. Upstream drift is reported, never folded silently into an exercise.
UPSTREAMopenai/codex
PINee0247f95a6fe2b094ba2253d82cae2a2b4c2dff
OBSERVED2026-08-01