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

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. 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, 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, 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:

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:

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:

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 to a complex system with worktree isolation in agents/s12_worktree_task_isolation.py.
• Key classes include TodoManager, SkillLoader, BackgroundManager, and WorktreeManager.
• The capstone implementation 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, 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 contains the capstone implementation combining sessions s01 through s11, featuring todo lists, skills, background tasks, and team coordination. 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.

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