# How learn-claude-code Teaches Building AI Agents: A 12-Session Progressive Curriculum

> Learn to build AI agents with learn-claude-code's 12-session curriculum. Progressively add capabilities to an immutable core loop and evolve simple scripts into production-grade autonomous systems.

- Repository: [shareAI-Lab/learn-claude-code](https://github.com/shareAI-lab/learn-claude-code)
- Tags: tutorial
- Published: 2026-03-08

---

**The learn-claude-code repository teaches building AI agents through a progressive 12-session curriculum where each session adds one architectural capability to an immutable core loop, demonstrating how production-grade autonomous systems evolve from simple tool-calling scripts.**

Building AI agents requires understanding how to orchestrate LLM reasoning with tool use, state management, and multi-agent coordination. The shareAI-lab/learn-claude-code repository provides a hands-on course that incrementally develops a Claude-style coding agent from a basic loop to a fully autonomous multi-agent system. Each session introduces exactly one new pattern for building AI agents while preserving the stability of the core execution logic.

## The Immutable Agent Loop Foundation

At the heart of every session lies a single, unchanging control flow defined in [`agents/s01_agent_loop.py`](https://github.com/shareAI-lab/learn-claude-code/blob/main/agents/s01_agent_loop.py). This **immutable agent loop** demonstrates the fundamental pattern for building AI agents that can reason and act.

```python
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":   # ← exit condition

        return
    # → execute every tool_use block, append tool_result, repeat

```

The loop never changes across sessions. Every new capability for building AI agents—whether tool dispatch, state management, or multi-agent coordination—simply **adds tools**, **injects state**, or **extends the message flow** without modifying this core runtime logic.

## Progressive Skill Building for AI Agents

The repository organizes learning into twelve incremental sessions, each introducing one architectural mechanism essential for building production-grade AI agents.

### Sessions 1–3: Core Interaction Patterns

**Session 1 ([`agents/s01_agent_loop.py`](https://github.com/shareAI-lab/learn-claude-code/blob/main/agents/s01_agent_loop.py))** establishes the minimal loop with a single `bash` tool, teaching the basic request-response pattern.

**Session 2 ([`agents/s02_tool_use.py`](https://github.com/shareAI-lab/learn-claude-code/blob/main/agents/s02_tool_use.py))** introduces **tool dispatch** through the `TOOL_HANDLERS` map and implements sandboxed file operations via `safe_path`:

```python
def safe_path(p: str) -> Path:
    path = (WORKDIR / p).resolve()
    if not path.is_relative_to(WORKDIR):
        raise ValueError(f"Path escapes workspace: {p}")
    return path

TOOL_HANDLERS = {
    "bash":       lambda **kw: run_bash(kw["command"]),
    "read_file":  lambda **kw: run_read(kw["path"], kw.get("limit")),
}

```

**Session 3 ([`agents/s03_todo_write.py`](https://github.com/shareAI-lab/learn-claude-code/blob/main/agents/s03_todo_write.py))** adds **structured state management** with the `TodoManager`, allowing the LLM to maintain a persistent todo list and receive nag reminders when it forgets tasks.

### Sessions 4–6: Scaling and Memory

**Session 4 ([`agents/s04_subagent.py`](https://github.com/shareAI-lab/learn-claude-code/blob/main/agents/s04_subagent.py))** demonstrates **sub-agent spawning**, where each sub-task receives its own clean message list to prevent context bleed between parent and child agents.

**Session 5 ([`agents/s05_skill_loading.py`](https://github.com/shareAI-lab/learn-claude-code/blob/main/agents/s05_skill_loading.py))** implements **dynamic knowledge retrieval** through a "skill" tool that fetches markdown files on demand, enabling the agent to load specialized capabilities without bloating the system prompt.

**Session 6 ([`agents/s06_context_compact.py`](https://github.com/shareAI-lab/learn-claude-code/blob/main/agents/s06_context_compact.py))** tackles **context compaction** through three-layer compression (summaries, embeddings, pruning) and **identity re-injection** via `make_identity_block` to prevent the LLM from losing its sense of self after message trimming.

### Sessions 7–10: Coordination and Communication

**Session 7 ([`agents/s07_task_system.py`](https://github.com/shareAI-lab/learn-claude-code/blob/main/agents/s07_task_system.py))** introduces a **persistent JSON task board** with dependency tracking, using `scan_unclaimed_tasks` and `claim_task` to implement work-stealing algorithms.

**Session 8 ([`agents/s08_background_tasks.py`](https://github.com/shareAI-lab/learn-claude-code/blob/main/agents/s08_background_tasks.py))** adds **asynchronous execution** through daemon threads that run long-running commands while the agent continues thinking, posting notifications upon completion.

**Session 9 ([`agents/s09_agent_teams.py`](https://github.com/shareAI-lab/learn-claude-code/blob/main/agents/s09_agent_teams.py))** implements **multi-agent communication** via a JSONL mailbox (`MessageBus`) that enables asynchronous messaging between teammates without external services.

**Session 10 ([`agents/s10_team_protocols.py`](https://github.com/shareAI-lab/learn-claude-code/blob/main/agents/s10_team_protocols.py))** establishes **governance patterns** through a request/approval finite state machine (FSM) for coordinated actions like shutdowns and plan reviews.

### Sessions 11–12: Full Autonomy

**Session 11 ([`agents/s11_autonomous_agents.py`](https://github.com/shareAI-lab/learn-claude-code/blob/main/agents/s11_autonomous_agents.py))** enables **self-directed operation** through idle polling, auto-claiming, and identity management. The `_idle_poll` method implements the WORK → IDLE lifecycle:

```python
def _idle_poll(self, name, messages):
    for _ in range(IDLE_TIMEOUT // POLL_INTERVAL):
        time.sleep(POLL_INTERVAL)
        # Check inbox

        inbox = BUS.read_inbox(name)
        if inbox:
            messages.append({"role": "user", "content": json.dumps(inbox)})
            return True
        # Auto-claim tasks

        unclaimed = scan_unclaimed_tasks()
        if unclaimed:
            task = unclaimed[0]
            claim_task(task["id"], name)
            messages.append({"role": "user",
                "content": f"<auto-claimed>Task #{task['id']}: {task['subject']}</auto-claimed>"})
            return True
    return False  # timeout → shutdown

```

**Session 12 ([`agents/s12_worktree_task_isolation.py`](https://github.com/shareAI-lab/learn-claude-code/blob/main/agents/s12_worktree_task_isolation.py))** completes the architecture with **filesystem isolation**, assigning each teammate a dedicated worktree directory to prevent cross-contamination:

```python
def spawn(name, role, prompt):
    workdir = WORKDIR / ".worktrees" / name
    workdir.mkdir(parents=True, exist_ok=True)
    # All file-tool calls resolve relative to workdir

```

## Architectural Patterns for Production AI Agents

The repository demonstrates several critical patterns for building AI agents that scale from prototypes to production:

**Tool-First Design** – Every capability surfaces as a tool with a JSON Schema input definition. The `TOOL_HANDLERS` dispatch map isolates the LLM from raw OS calls, enabling sandboxing through helpers like `safe_path`.

**Message Bus Architecture** – A lightweight JSONL per-teammate inbox (`MessageBus`) implements asynchronous communication without requiring external message queues or databases.

**Persistent Task Board** – Tasks stored as JSON files in `.tasks/` create a human-readable, version-controllable work queue. The `scan_unclaimed_tasks` and `claim_task` utilities demonstrate work-stealing algorithms for distributed agent systems.

**Identity Re-Injection** – After context compression, the `make_identity_block` helper inserts an `<identity>` block into short message lists (≤3 messages) to prevent the LLM from losing its sense of self.

**Worktree Isolation** – Each teammate operates within its own directory subtree (`WORKDIR / ".worktrees" / name`), guaranteeing that file operations cannot accidentally overwrite another agent's work.

## Summary

- **learn-claude-code** teaches building AI agents through twelve incremental sessions that each add one architectural capability to an immutable core loop.
- The **immutable agent loop** in [`agents/s01_agent_loop.py`](https://github.com/shareAI-lab/learn-claude-code/blob/main/agents/s01_agent_loop.py) remains unchanged throughout the curriculum, demonstrating how to evolve capabilities without destabilizing runtime logic.
- Each session introduces production patterns including **tool dispatch**, **state management**, **sub-agents**, **context compaction**, **task boards**, **message buses**, and **worktree isolation**.
- The final sessions (`s11` and `s12`) demonstrate **autonomous operation** with idle polling, auto-claiming, and filesystem isolation, completing the journey from simple script to self-directed multi-agent system.

## Frequently Asked Questions

### What makes learn-claude-code different from other AI agent tutorials?

Unlike tutorials that present monolithic frameworks, learn-claude-code teaches building AI agents through **incremental architectural evolution**. Each of the twelve sessions adds exactly one mechanism to an immutable core loop, allowing you to see precisely how production features like task boards and message buses integrate without breaking existing functionality. This "mechanism-per-session" approach mirrors how real-world agent systems are actually constructed.

### Do I need prior experience with Claude or Anthropic's API?

No prior experience is required. Session 1 ([`agents/s01_agent_loop.py`](https://github.com/shareAI-lab/learn-claude-code/blob/main/agents/s01_agent_loop.py)) starts with a minimal Python script using standard API calls. The repository focuses on **architectural patterns** rather than vendor-specific features, meaning the concepts apply to any LLM that supports tool use. The documentation in `docs/en/` provides narrative explanations alongside the code.

### How does the repository handle safety and sandboxing?

Safety is implemented through **tool-level sandboxing** rather than containerization. The `safe_path` helper in [`agents/s02_tool_use.py`](https://github.com/shareAI-lab/learn-claude-code/blob/main/agents/s02_tool_use.py) resolves all file paths relative to a workspace directory and raises `ValueError` if a path attempts to escape. Session 12 ([`agents/s12_worktree_task_isolation.py`](https://github.com/shareAI-lab/learn-claude-code/blob/main/agents/s12_worktree_task_isolation.py)) adds **worktree isolation**, where each teammate receives its own subdirectory, preventing file-system collisions between agents without requiring Docker or virtual machines.

### Can I use these patterns with other LLM providers?

Yes. While the code uses Anthropic's `messages.create` API, the **architectural patterns** are provider-agnostic. The tool-use loop, dispatch maps, task boards, and message buses work with any LLM that supports function calling or tool use, including OpenAI's GPT models, Google's Gemini, or local models via Ollama. The repository teaches **concepts**, not vendor lock-in.