# What is shareAI-lab/learn-claude-code? A 12-Session Guide to Building Autonomous Coding Agents

> Explore shareAI-lab/learn-claude-code. This 12-session guide teaches you to build autonomous coding agents, starting simple and progressing to complex team coordination.

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

---

**shareAI-lab/learn-claude-code is a teaching-oriented repository that demonstrates how to build a Claude-Code-style autonomous coding agent through 12 progressive sessions, evolving from a minimal agent loop to a full-featured system with worktree isolation and team coordination.**

The **shareAI-lab/learn-claude-code** repository serves as an educational codebase for developers interested in autonomous AI agents. It provides a step-by-step implementation guide that starts with a basic while-loop and gradually adds sophisticated features like tool dispatch, context compression, and multi-agent coordination. Each session builds upon the previous one while keeping the core agent loop stable, making it an ideal reference for understanding how modern coding assistants function under the hood.

## The 12-Step Architecture Evolution

The repository is structured around **12 progressive sessions** (s01 through s12) that each introduce a single new mechanism to the agent. This layered approach ensures that learners can understand each concept in isolation before seeing how it integrates into the full system.

### Session 1: The Minimal Agent Loop

At the foundation lies a perpetual while-loop implemented in [`agents/s01_agent_loop.py`](https://github.com/shareAI-lab/learn-claude-code/blob/main/agents/s01_agent_loop.py). This minimal reference implementation calls the Anthropic LLM, feeds tool results back to the model, and terminates only when `stop_reason != "tool_use"`. This file represents the simplest possible autonomous agent capable of tool use.

### Sessions 2-11: Building the Core Capabilities

As implemented in [`agents/s_full.py`](https://github.com/shareAI-lab/learn-claude-code/blob/main/agents/s_full.py), sessions two through eleven add essential mechanisms:

- **Tool Dispatch (s02)**: A registry (`TOOLS`) maps tool names to Python callables (`TOOL_HANDLERS`), enabling the loop to invoke appropriate handlers whenever the LLM emits a `tool_use` block.
- **Planning & TodoWrite (s03)**: The `TodoManager` class maintains a simple checklist that the LLM updates via the `TodoWrite` tool.
- **Sub-agents (s04)**: The `run_subagent` function spawns isolated agent instances with their own message history for clean sub-task contexts.
- **Skills (s05)**: The `SkillLoader` class loads Markdown **SKILL.md** files on demand via the `load_skill` tool, keeping the system prompt lightweight.
- **Context Compression (s06)**: Automatic `microcompact` (clearing old tool results) and `auto_compact` (summarizing conversations when token limits are exceeded) manage context window constraints.
- **Persistent Task Graph (s07)**: The `TaskManager` class creates file-based task objects (`.tasks/task_*.json`) that form a dependency graph surviving across runs.
- **Background Tasks (s08)**: The `BackgroundManager` class uses daemon threads to execute long-running shell commands, injecting results back as messages.
- **Teams & Mailboxes (s09)**: The `MessageBus` and `TeammateManager` classes enable persistent teammates to communicate through JSONL inboxes.
- **Team Protocols (s10)**: Functions like `handle_shutdown_request` and `handle_plan_review` implement request/response handshakes for autonomous negotiation.
- **Autonomous Agents (s11)**: Teammates can claim tasks themselves via auto-claim logic in `TeammateManager._loop`, removing the need for central assignment.

### Session 12: Worktree Isolation and Task Sandboxing

The final session, located in [`agents/s12_worktree_task_isolation.py`](https://github.com/shareAI-lab/learn-claude-code/blob/main/agents/s12_worktree_task_isolation.py), introduces directory-level sandboxing using Git worktrees. The `WorktreeManager` and `TaskManager` classes bind tasks to isolated worktrees under `.worktrees/`, while the `EventBus` logs lifecycle events to `.worktrees/events.jsonl`. This allows parallel task execution without repository contamination.

## Running the Autonomous Agent

The repository provides runnable implementations at every stage of development.

### Starting with the Basic Loop

To run the minimal agent loop from session one:

```bash
pip install -r requirements.txt
python agents/s01_agent_loop.py

```

The REPL displays a prompt `s01 >>`. Enter natural language requests like `list files in the current directory`, and the agent invokes the `bash` tool, executes the command, and returns the output.

### Using the Full-Featured Agent

For the complete implementation including planning, skills, and team coordination:

```bash
python agents/s_full.py

```

When you enter `create a small todo list for the project`, the model calls the `TodoWrite` tool, which updates the in-memory `TodoManager`. Subsequent rounds automatically remind you of pending items.

### Advanced Task Isolation (s12)

To experiment with worktree-based sandboxing:

```bash
python agents/s12_worktree_task_isolation.py

```

Create isolated tasks and worktrees:

```

s12 >> task_create subject="Refactor auth module" description="Move auth to its own package"
s12 >> worktree_create name="auth-refactor" task_id=1 base_ref="main"

```

Execute commands within the sandbox:

```

s12 >> worktree_run name="auth-refactor" command="git status"

```

Query the event log:

```

s12 >> worktree_events limit=5

```

## Supporting Infrastructure

Beyond the Python agent implementations, the repository includes:

- **Documentation**: Mental-model-first guides in English, Chinese, and Japanese (`docs/en/`, `docs/zh/`, `docs/ja/`) explain each session's architecture and usage patterns.
- **Web UI**: A Next.js frontend (`web/`) visualizes the agent's step-through diagrams, source files, and provides an interactive REPL.
- **Skills Library**: The `skills/` directory contains Markdown teaching modules (e.g., `pdf/`, `code-review/`) that the agent loads at runtime via the `load_skill` tool.

## Summary

- **shareAI-lab/learn-claude-code** teaches autonomous agent construction through 12 progressive Python sessions.
- The architecture evolves from a simple while-loop in [`agents/s01_agent_loop.py`](https://github.com/shareAI-lab/learn-claude-code/blob/main/agents/s01_agent_loop.py) to a complex system with worktree isolation in [`agents/s12_worktree_task_isolation.py`](https://github.com/shareAI-lab/learn-claude-code/blob/main/agents/s12_worktree_task_isolation.py).
- Key classes include `TodoManager`, `SkillLoader`, `BackgroundManager`, and `WorktreeManager`.
- The capstone implementation [`agents/s_full.py`](https://github.com/shareAI-lab/learn-claude-code/blob/main/agents/s_full.py) combines sessions s01-s11 with tool dispatch, sub-agents, and team coordination.
- Git worktrees provide directory-level sandboxing for parallel task execution without repository state conflicts.
- Skills are loaded dynamically from Markdown files, keeping the system prompt lightweight and modular.

## Frequently Asked Questions

### What programming language is shareAI-lab/learn-claude-code written in?

The repository is primarily written in **Python 3**, with a Next.js (React/TypeScript) frontend for the web visualization interface. The core agent logic relies on the Anthropic Python SDK for LLM communication.

### How does the context compression mechanism work?

As implemented in [`agents/s_full.py`](https://github.com/shareAI-lab/learn-claude-code/blob/main/agents/s_full.py), the context compression layer (s06) provides two strategies: `microcompact` clears old tool results to save tokens, while `auto_compact` triggers conversation summarization when the token count exceeds a configurable threshold. This prevents the context window from overflowing during long-running sessions.

### Can multiple agents work together in this system?

Yes, sessions s09 through s11 implement multi-agent coordination. The `TeammateManager` and `MessageBus` classes enable persistent teammates to communicate through JSONL mailboxes. Agents can spawn sub-agents with isolated histories (s04), and autonomous teammates can claim tasks themselves (s11) using protocols like `handle_shutdown_request` and `handle_plan_review`.

### What is the difference between s_full.py and s12_worktree_task_isolation.py?

[`agents/s_full.py`](https://github.com/shareAI-lab/learn-claude-code/blob/main/agents/s_full.py) contains the capstone implementation combining sessions s01 through s11, featuring todo lists, skills, background tasks, and team coordination. [`agents/s12_worktree_task_isolation.py`](https://github.com/shareAI-lab/learn-claude-code/blob/main/agents/s12_worktree_task_isolation.py) implements session 12 specifically, adding `WorktreeManager` and `EventBus` classes that provide Git worktree-based directory isolation for tasks, which is essential for parallel development workflows.