s01
Agent Loop
“One loop & Bash is all you need”
You ask the model: "List the files in my directory and run XXX.py."
messageswhile Truestop_reason
The Core Pattern — every coding agent is one loop
while True:
response = model(messages, tools)
if response.stop_reason != "tool_use":
return response.text
results = execute(response.tool_calls)
messages.append(results)Every coding agent is this loop. The model calls tools until it is done — everything else in these 20 lessons is refinement around it.
20 of 20 lessons
Stage 1: Let the Agent Act
Core capabilities
s02
Tool Use
“Adding a tool means adding one handler”
The s01 Agent has only one tool: bash. To read a file, `cat`; to write, `echo "..." > file.py`; to edit, `sed`.
TOOL_HANDLERSdispatch mapconcurrency
s03
Permission System
“Set boundaries first, then grant freedom”
s02's Agent has 5 tools. File tools are protected by `safe_path`, but bash is unrestricted. Ask it to "clean up the project," and it might run `rm -rf /`.
PermissionRuleapproval pipeline
s04
Hook System
“Hook around the loop, never rewrite the loop”
The s03 Agent has permission checks. But every new check, "log every bash call", "auto git add after writes", requires modifying the `agent_loop` function.
PreToolUsePostToolUseextension points
Stage 2: Handle Complex Work
Plan, delegate, make room
s05
TodoWrite
“An agent without a plan drifts”
Give the Agent a complex task: "Rename all Python files to snake_case, run tests, and fix failures."
TodoItemplan-then-execute
s06
Subagent
“Big tasks split small, each subtask gets clean context”
The Agent is fixing a bug. It reads 30 files to trace the call chain, chatting for 60 rounds along the way. The messages list grows to 120 entries, most of which are intermediate steps from "tracing the call chain" — unrelated to the final goal of "fixing the bug."
fresh messages[]context isolation
s08
Context Compact
“Context always fills up -- have a way to make room”
The agent is running along, then freezes.
snipCompactmicroCompacttoolResultBudgetautoCompact
Stage 3: Remember & Recover
Memory and resilience
s09
Memory System
“Remember what matters, forget what doesn't”
s08's autoCompact preserves current goals, remaining work, and user constraints in the summary, but details get lost: "use tabs not spaces" might get simplified to "user has code style preferences". And when you start a new session, even the summary is gone.
selectionextractionconsolidation
s10
System Prompt
“Prompts are assembled at runtime, not hardcoded”
From s01 to s09, the system prompt was always one hardcoded line:
runtime assemblysection concatenation
s11
Error Recovery
“Errors aren't the end, they're the start of a retry”
The Agent is running along and then errors out:
token escalationfallback modelretry strategies
Stage 4: Run Long Tasks
Persist, background, schedule
s12
Task System
“Big goals break into small tasks, ordered, persisted to disk”
The agent receives a project: set up a database, write APIs, add tests. It uses s05's TodoWrite to create a checklist, then starts writing the API first, gets halfway through and realizes there are no database tables, goes back to fix them; when adding tests, discovers the API interface signatures have changed again...
TaskRecordblockedBydisk persistence
s13
Background Tasks
“Slow ops go background, agent keeps thinking”
Ever used a washing machine? Throw clothes in, press start, then go do other things — cook, reply to messages, read papers. 30 minutes later the machine beeps: done. You don't stand there waiting for 30 minutes.
threaded executionnotification queue
s14
Cron Scheduler
“Fire on schedule, no human kick needed”
An alarm clock doesn't need you to watch it. You set 7:00, it rings at 7:00 — you could be sleeping, showering, cooking, it rings regardless.
durable schedulingsession-scoped triggers
Stage 5: Coordinate Many Agents
Teams and protocols
s15
Agent Teams
“Too big for one agent -- delegate to teammates”
"Refactor the entire backend" touches auth, database layer, API routes, and tests. One agent working on API routes no longer has auth module details in context. The context window is limited, a single agent can't cover every module.
MessageBusinboxpermission bubbling
s16
Team Protocols
“Teammates need shared communication rules”
s15's teammates can work, but coordination is loose: Lead sends a message, teammate replies, no structured protocol. Two scenarios expose the gap:
shutdown handshakeplan approval
s17
Autonomous Agents
“Teammates check the board, claim work themselves”
s16's teammates can communicate and handshake shutdown. But each teammate waits for Lead to assign tasks — with 10 unclaimed tasks on the board, Lead has to manually assign 10 times. This doesn't scale. Teammates should check the task board themselves, claim unowned tasks, and look for the next one when done.
idle cycleauto-claimself-organization
s18
Worktree Isolation
“Each works in its own directory, no interference”
In s17, Alice and Bob both work in the same directory. Alice's task is "refactor auth module", Bob's task is "refactor UI login page".
WorktreeRecordtask-directory binding
Stage 6: Extend & Assemble
Skills, MCP, the full loop
s07
Skill Loading
“Load knowledge on demand, not upfront”
Your project has a React component spec, a SQL style guide, and an API design doc. You want the Agent to follow these specs automatically. The most straightforward idea — stuff them all into the system prompt:
SkillManifeston-demand injection
s19
MCP Plugin
“Not enough capability? Plug in more via MCP”
From s01 through s18, every tool the agent uses was hand-written — bash, read, write, task, worktree. Input validation, execution logic, error handling — all written line by line.
multi-transportchannel routingtool pool assembly
s20
Comprehensive Agent
“Many mechanisms, one loop”
The first 19 chapters add one mechanism at a time. That is the right way to learn, but a real agent does not run with only one mechanism enabled.
all mechanisms around one loop
