Learn Claude Code -- A nano Claude Code-like agent, built from 0 to 1

English | 中文 | 日本語

                    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

---

The Core Pattern

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.

Scope (Important)

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.

Quick Start

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 isolation

Web Platform

Interactive visualizations, step-through diagrams, source viewer, and documentation.

cd web && npm install && npm run dev   # http://localhost:3000

Learning Path

Phase 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

Architecture

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

Documentation

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

License

MIT

---

The model is the agent. Our job is to give it tools and stay out of the way.