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

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. This immutable agent loop demonstrates the fundamental pattern for building AI agents that can reason and act.

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) establishes the minimal loop with a single bash tool, teaching the basic request-response pattern.

Session 2 (agents/s02_tool_use.py) introduces tool dispatch through the TOOL_HANDLERS map and implements sandboxed file operations via safe_path:

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) 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) 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) 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) 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) 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) 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) 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) 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) enables self-directed operation through idle polling, auto-claiming, and identity management. The _idle_poll method implements the WORK → IDLE lifecycle:

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) completes the architecture with filesystem isolation, assigning each teammate a dedicated worktree directory to prevent cross-contamination:

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 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) 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 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) 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}