THE AGENT PATTERN
=================
User --> messages[] --> LLM --> response
|
stop_reason == "tool_use"?
/ \
yes no
| |
execute tools return text
append results
loop back -----------------> messages[]
That's the minimal loop. Every AI coding agent needs this loop.
Production agents add policy, permissions, and lifecycle layers.
12 progressive sessions, from a simple loop to isolated autonomous execution. Each session adds one mechanism. Each mechanism has one motto.
s01 "Bash is all you need" — one tool + one loop = an agent
s02 "The loop didn't change" — adding tools means adding handlers, not rewriting the loop
s03 "Plan before you act" — visible plans improve task completion
s04 "Process isolation = context isolation" — fresh messages[] per subagent
s05 "Load on demand, not upfront" — inject knowledge via tool_result, not system prompt
s06 "Strategic forgetting" — forget old context to enable infinite sessions
s07 "State survives /compact" — file-based state outlives context compression
s08 "Fire and forget" — non-blocking threads + notification queue
s09 "Append to send, drain to read" — async mailboxes for persistent teammates
s10 "Same request_id, two protocols" — one FSM pattern powers shutdown + plan approval
s11 "Poll, claim, work, repeat" — no coordinator needed, agents self-organize
s12 "Isolate by directory, coordinate by task ID" — task board + optional worktree lanes
def agent_loop(messages):
while True:
response = client.messages.create(
model=MODEL, system=SYSTEM,
messages=messages, tools=TOOLS,
)
messages.append({"role": "assistant",
"content": response.content})
if response.stop_reason != "tool_use":
return
results = []
for block in response.content:
if block.type == "tool_use":
output = TOOL_HANDLERS[block.name](**block.input)
results.append({
"type": "tool_result",
"tool_use_id": block.id,
"content": output,
})
messages.append({"role": "user", "content": results})Every session layers one mechanism on top of this loop -- without changing the loop itself.
This repository is a 0->1 learning project for building a nano Claude Code-like agent. It intentionally simplifies or omits several production mechanisms:
- Full event/hook buses (for example PreToolUse, SessionStart/End, ConfigChange).
s12 includes only a minimal append-only lifecycle event stream for teaching. - Rule-based permission governance and trust workflows
- Session lifecycle controls (resume/fork) and advanced worktree lifecycle controls
- Full MCP runtime details (transport/OAuth/resource subscribe/polling)
Treat the team JSONL mailbox protocol in this repo as a teaching implementation, not a claim about any specific production internals.
git clone https://github.com/shareAI-lab/learn-claude-code
cd learn-claude-code
pip install -r requirements.txt
cp .env.example .env # Edit .env with your ANTHROPIC_API_KEY
python agents/s01_agent_loop.py # Start here
python agents/s11_autonomous_agents.py # Full autonomous team
python agents/s12_worktree_task_isolation.py # Task-aware worktree isolationInteractive visualizations, step-through diagrams, source viewer, and documentation.
cd web && npm install && npm run dev # http://localhost:3000Phase 1: THE LOOP Phase 2: PLANNING & KNOWLEDGE
================== ==============================
s01 The Agent Loop [1] s03 TodoWrite [5]
while + stop_reason TodoManager + nag reminder
| |
+-> s02 Tools [4] s04 Subagents [5]
dispatch map: name->handler fresh messages[] per child
|
s05 Skills [5]
SKILL.md via tool_result
|
s06 Compact [5]
3-layer compression
Phase 3: PERSISTENCE Phase 4: TEAMS
================== =====================
s07 Tasks [8] s09 Agent Teams [9]
file-based CRUD + deps graph teammates + JSONL mailboxes
| |
s08 Background Tasks [6] s10 Team Protocols [12]
daemon threads + notify queue shutdown + plan approval FSM
|
s11 Autonomous Agents [14]
idle cycle + auto-claim
|
s12 Worktree Isolation [16]
task coordination + optional isolated execution lanes
[N] = number of tools
learn-claude-code/
|
|-- agents/ # Python reference implementations (s01-s12 + full)
|-- docs/{en,zh,ja}/ # Mental-model-first documentation (3 languages)
|-- web/ # Interactive learning platform (Next.js)
|-- skills/ # Skill files for s05
+-- .github/workflows/ci.yml # CI: typecheck + build
Mental-model-first: problem, solution, ASCII diagram, minimal code. Available in English | 中文 | 日本語.
| Session | Topic | Motto |
|---|---|---|
| s01 | The Agent Loop | Bash is all you need |
| s02 | Tools | The loop didn't change |
| s03 | TodoWrite | Plan before you act |
| s04 | Subagents | Process isolation = context isolation |
| s05 | Skills | Load on demand, not upfront |
| s06 | Compact | Strategic forgetting |
| s07 | Tasks | State survives /compact |
| s08 | Background Tasks | Fire and forget |
| s09 | Agent Teams | Append to send, drain to read |
| s10 | Team Protocols | Same request_id, two protocols |
| s11 | Autonomous Agents | Poll, claim, work, repeat |
| s12 | Worktree + Task Isolation | Isolate by directory, coordinate by task ID |
MIT
The model is the agent. Our job is to give it tools and stay out of the way.