# Learn Claude Code -- Build an AI Agent From Scratch

[English](./README.md) | [中文](./README-zh.md) | [日本語](./README-ja.md)

```
                    THE AGENT PATTERN
                    =================

    User --> messages[] --> LLM --> response
                                      |
                            stop_reason == "tool_use"?
                           /                          \
                         yes                           no
                          |                             |
                    execute tools                    return text
                    append results
                    loop back -----------------> messages[]


    That's it. Every AI coding agent is this loop.
    Everything else is refinement.
```

**11 progressive sessions, from a simple loop to full autonomous teams.**
**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 logic
>
> **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

---

## The Core Pattern

```python
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.

## Quick Start

```sh
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
```

### Web Platform

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

```sh
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

                                     [N] = number of tools
```

## Architecture

```
learn-claude-code/
|
|-- agents/                        # Python reference implementations (s01-s11 + 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](./docs/en/) | [中文](./docs/zh/) | [日本語](./docs/ja/).

| Session | Topic | Motto |
|---------|-------|-------|
| [s01](./docs/en/s01-the-agent-loop.md) | The Agent Loop | *Bash is all you need* |
| [s02](./docs/en/s02-tool-use.md) | Tools | *The loop didn't change* |
| [s03](./docs/en/s03-todo-write.md) | TodoWrite | *Plan before you act* |
| [s04](./docs/en/s04-subagent.md) | Subagents | *Process isolation = context isolation* |
| [s05](./docs/en/s05-skill-loading.md) | Skills | *Load on demand, not upfront* |
| [s06](./docs/en/s06-context-compact.md) | Compact | *Strategic forgetting* |
| [s07](./docs/en/s07-task-system.md) | Tasks | *State survives /compact* |
| [s08](./docs/en/s08-background-tasks.md) | Background Tasks | *Fire and forget* |
| [s09](./docs/en/s09-agent-teams.md) | Agent Teams | *Append to send, drain to read* |
| [s10](./docs/en/s10-team-protocols.md) | Team Protocols | *Same request_id, two protocols* |
| [s11](./docs/en/s11-autonomous-agents.md) | Autonomous Agents | *Poll, claim, work, repeat* |

## License

MIT

---

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