Read the Loop: an open-source explainer built from real Claude Code sessions
Read the Loop explains how a coding agent works by replaying real, recorded Claude Code sessions you can step through. All eight chapters are now live, from the basic loop to caching, compaction, subagents, failure modes and a harness playground.
Updated November 20, 2026: All eight chapters are now published; expanded with what each chapter shows, how the recordings were made and how to run it locally.
Read the Loop is an illustrated explainer that makes one idea concrete: a coding agent is a loop. A language model can only read text and write more text. The harness around it, here Claude Code, runs the commands the model asks for and pastes the results back in, round after round, until the model replies without a request. Instead of describing that in the abstract, the site shows it on real Claude Code sessions that were recorded and can be stepped through call by call.
The eight chapters
All eight chapters are published, in English and in Chinese (loop.candygoogy.dev/zh/):
- An agent is a loop: a real session fixes a bug in a small paddle-and-bricks game where the ball falls through the right half of the paddle. The model never sees the game. It took 5 calls, and each call read the whole conversation, which grew from 6,858 tokens to 13,244.
- The context window: how much the model reads on every call over a longer session. The last of 44 calls read 57,541 tokens.
- Caching: why rereading everything is cheap. In that session, 96.5% of what the 44 calls read came from the cache, and the chapter shows what breaks it.
- Compaction: what happens when the conversation is squeezed into a summary. One example goes from 58,492 tokens to 4,726, and the chapter checks what the agent still knows afterwards.
- Tools and permissions: what the model is told about each tool and who decides what may run. In the first request, tool descriptions were 60.7% of the characters, the system prompt 24.0% and messages 15.3%.
- Subagents: a fresh conversation for a side task. The subagent's conversation reached 12,649 tokens while the main one grew by only 1,956 across the hand-back.
- Failure modes: loops, made-up functions, a false done and destructive commands, with 22 recorded runs built to catch them. Of 191 requests the model made, 29 were refused.
- The harness playground: flip three switches, the model, whether the Bash tool is available and one rule in the set-up text, and compare 16 real runs of the same bug fix, two for each of the eight settings. Only 5 of the 16 ran the tests before editing, and 8 ran them after.
How it was made
The site was built with Claude Code, and everything it shows comes from recordings of Claude Code. The author gave it real tasks, including the game bug, a bug report filed against the Python formatter black, and small projects designed to trigger known failures, and recorded each session as it ran. The stated rule is that every number and every word the agent wrote or saw comes from a recording: commands, outputs, token counts and the model's own text are read from the trace files when the page loads, and only the explanations are written by hand. Where the recordings cannot settle a point, the page says so; chapter 1 notes, for example, that cache hits on the first call were probably left over from an earlier run. Before a recording goes into the repo, a script replaces the recording folder path and the local user name and changes nothing else.
The first chapter is careful about cherry-picking. Several runs of the game task were recorded, and the one shown was chosen by a rule fixed in advance: the first run that runs the tests both before and after its fix. The runs from that batch are in the repo. An earlier batch of three was discarded because the sessions inherited settings, including a higher effort level, from the session that launched them; all three made the same fix, but their traces were deleted. The page also notes that one success on a toy game proves little, which is what the failure-modes chapter is for.
How to read or run it
Read it at loop.candygoogy.dev, or clone github.com/candygoogy/read-the-loop and open site/index.html in a browser. There is no build step and no server. The repo also includes its tests and page checks; the screenshot script renders every page at three sizes, and the site check covers requests, meta tags and hosting files:
git clone https://github.com/candygoogy/read-the-loop
cd read-the-loop
python -m unittest discover tests
node tests/harness-step-check.js
node scripts/screenshot.js <out-dir>
node scripts/check-site.jsThe chapter 8 playground can be embedded in your own page; the chapter shows the snippet. The code is MIT-licensed, and the text, figures and recordings are CC BY 4.0, so you can reuse the material with credit. The fonts are under the SIL Open Font License, and the excerpts of black's code in recording 03 stay under black's MIT licence; NOTICE.md in the repo has the details.
Who it is for
In our view it suits developers who use Claude Code daily but have never looked at what goes over the wire, and team leads who need to explain why long sessions get expensive (chapter 2), why caching matters (chapter 3) and why an agent's done is only its own judgement (chapter 7). The recorded numbers make those points better than any slide.
Our take
What sets Read the Loop apart from most explainers is that it refuses to hand-wave: every figure is tied to a recording you can inspect, and the chapters say where the evidence stops. Remember that these are recordings of particular sessions, so the exact numbers will shift with other models, versions and tasks. Our suggestion for teams: the same format, replayable traces of your own agent sessions, could make a good onboarding tool.
Built by candygoogy
Source: Read the Loop, candygoogy/read-the-loop (GitHub), Read the Loop, chapter 1: An agent is a loop
This story first appeared in the claudefox daily briefing for November 9, 2026.