Learn how Codex CLI works by making one small Rust exercise green at a time.
Codex Koans is a deterministic, offline curriculum built from faithful miniature models of production concepts. It does not compile Codex, call an API, or require a Codex installation. The course is pinned to openai/codex@ee0247f95a6fe2b094ba2253d82cae2a2b4c2dff, observed on 2026-08-01.
Start with the failure in front of you. Repair it, rerun, and reflect before moving on.
Install Rust 1.85 or newer, then:
git clone https://github.com/amphetamarina/codex-koans.git
cd codex-koans
cargo koansThe first incomplete koan fails intentionally. Nothing else needs to be installed or configured, and all fixtures stay on your machine.
| Command | Purpose |
|---|---|
cargo koans |
Run in curriculum order and stop at the first failure |
cargo koans -- --hint |
Show one bounded hint for the current failure |
cargo koans -- --list |
List all chapters and koans |
cargo koans -- --chapter <slug> |
Work within one chapter |
cargo koans -- --recap |
Summarize green and red lessons by chapter |
cargo koans -- --all |
Run every koan instead of stopping early |
Each failure names the chapter, progress, exercise, source location, broken expectation, a short technical meditation, and a permalink into the pinned Codex source.
| # | Chapter | Koans | Chapter command |
|---|---|---|---|
| 01 | Orientation and entry points | 01–04 | cargo koans -- --chapter orientation |
| 02 | Protocol spine | 05–08 | cargo koans -- --chapter protocol |
| 03 | Threads, turns, and steps | 09–12 | cargo koans -- --chapter threads |
| 04 | Context construction | 13–16 | cargo koans -- --chapter context |
| 05 | Model streaming | 17–20 | cargo koans -- --chapter streaming |
| 06 | Tool plane | 21–24 | cargo koans -- --chapter tools |
| 07 | Policy and sandboxing | 25–28 | cargo koans -- --chapter policy |
| 08 | Agent orchestration loop | 29–32 | cargo koans -- --chapter agent-loop |
| 09 | Rollouts and state | 33–36 | cargo koans -- --chapter rollouts |
| 10 | Presentation surfaces | 37–40 | cargo koans -- --chapter surfaces |
| 11 | Extension edge | 41–44 | cargo koans -- --chapter extensions |
| 12 | Collaboration and capstone | 45–48 | cargo koans -- --chapter collaboration |
Difficulty moves from filling expected values through event ordering and state transitions to debugging invariants and integrating a complete miniature agent turn.
crates/codex-minicontains reusable teaching equivalents of Codex types and subsystems.crates/koanscontains the 48 learner-owned exercises and their metadata.crates/koan-runnerimplements the ordered, stop-at-first-failure experience.course-version.tomlis the single release pin and source-map record.docs/is a zero-dependency field handbook.scripts/contains standard-library-only metadata, source-drift, and handbook checks.
main is the intentional starter state. The matching solutions branch contains completed exercises for comparison after you have worked through a lesson.
Model streams, tool calls, approvals, sandbox decisions, rollouts, and collaboration events are fixed in-memory or file fixtures. Running or completing the course never needs credentials, network access, an upstream checkout, or writes outside the repository's build directory.
The upstream source links are for deeper reading when a network is available; they are not needed by the compiler or runner.
Validate the frozen metadata and handbook locally:
python3 scripts/validate_course.py
python3 scripts/build_handbook.py --check
python3 scripts/build_handbook.pyAudit the mappings against a local Codex clone, at the pin or at a candidate revision:
python3 scripts/check_upstream.py --checkout ../codex
python3 scripts/check_upstream.py --checkout ../codex --revision origin/mainThe drift command is read-only. It reports deleted or changed mapped files and never updates lessons. Curriculum changes ship as versioned releases and use tags such as codex-2026.08-v1; see CONTRIBUTING.md.
The red–green learning mechanic follows the tradition of Ruby Koans and Python Koans. The handbook adapts the system-map approach of the local Codex Internals Explorer. Teaching implementations are original and intentionally smaller than production Codex; upstream names and links are included for study and attribution.
Licensed under Apache License 2.0. Codex and OpenAI are trademarks of OpenAI. This independent educational project is not endorsed by or affiliated with OpenAI.