Reconstructing Claude Code: A Step‑by‑Step Guide to Building AI Programming Agents

Core Logic

All AI programming agents share a single core loop that enables autonomous interaction, independent of the programming language. The same logic can be implemented in Python, Java, Go, etc.

Python core loop

while True:
    response = client.messages.create(messages=messages, tools=tools)
    if response.stop_reason != "tool_use":
        break
    for tool_call in response.content:
        result = execute_tool(tool_call.name, tool_call.input)
        messages.append(result)

Java core loop

while (true) {
    MessageResponse response = client.messagesCreate(messages, tools);
    if (!"tool_use".equals(response.getStopReason())) {
        break;
    }
    for (ToolCall toolCall : response.getContent()) {
        ToolResult result = execute_tool(toolCall.getName(), toolCall.getInput());
        messages.add(result);
    }
}

The loop can be summarized in four steps: invoke the model to receive instructions, execute external tools (file I/O, commands, Git, etc.), feed tool results back to the model, and repeat until the task completes.

Ability Progression

The project organizes 12 stages (s01‑s12) into five capability layers, adding only one core mechanism per stage while keeping the codebase incremental.

s01 Basic Loop – 84 lines implement the minimal agent kernel, enabling file read/write, command execution, and Git operations.

s02 Multi‑Tool Extension – 120 lines add a registration system for arbitrary tools, allowing modular capability expansion.

s03 Explicit Planning – 176 lines introduce a to‑do list tool so the agent generates and follows an execution plan.

s04 Sub‑Agent Isolation – 151 lines create separate message contexts for sub‑tasks, preventing context pollution.

s05 On‑Demand Skill Loading – 187 lines package knowledge as skill bundles injected only when needed, reducing prompt overload.

s06 Context Compression – 205 lines apply a three‑layer compression strategy (sliding window, summarization, selective retention) to support unlimited conversations.

s07 Task System – 207 lines store task dependencies in files, turning the agent into a project coordinator.

s08 Background Tasks – 198 lines use background threads and notification queues for non‑blocking execution of long‑running operations.

s09 Team Asynchronous Communication – 348 lines give each agent a mailbox for persistent, cross‑cycle messaging.

s10 Team Communication Protocol – 419 lines define a request‑ID and finite‑state‑machine protocol for approval, abort, and negotiation flows.

s11 Autonomous Agents – 499 lines let agents scan a task board and claim work autonomously, enabling self‑organizing collaboration.

s12 Worktree Task Isolation – 694 lines assign each task its own Git worktree, preventing directory conflicts and supporting parallel development.

Quick Start

The project is intentionally lightweight, focusing on the agent’s core reasoning model and providing a minimal web UI for visualization.

Environment Setup

# Clone the repository
git clone https://github.com/shareAI-lab/learn-claude-code
cd learn-claude-code
# Install Python dependencies
pip install -r requirements.txt
# Prepare environment variables
cp .env.example .env
# Edit .env to add ANTHROPIC_API_KEY, MODEL_ID, etc.

Run Tests

# Minimal agent loop
python agents/s01_agent_loop.py
# Autonomous agent team
python agents/s11_autonomous_agents.py
# Worktree task isolation version
python agents/s12_worktree_task_isolation.py

Visualization Platform

cd web
npm install
npm run dev
# Open http://localhost:3000 in a browser

Core Value

Progressive Learning : From 84 to 694 lines, each stage adds a single mechanism, making the material approachable for beginners.

Problem‑Driven : Real development pain points are identified first, then concrete solutions are presented.

Generalizable Principles : The design abstracts away language‑specific details, allowing the concepts to be transferred to any tech stack.

Transparent Code : Every stage’s code changes are clearly shown, avoiding black‑box learning.

Immediate Hands‑On : Complete code, configuration, and test cases enable developers to start experimenting without complex setup.

Visual Aid : An accompanying web UI visualizes the agent’s execution flow, lowering the barrier to understanding abstract concepts.

By demystifying Claude Code’s “black box,” the learn‑claude‑code project equips developers with the design mindset and technical insight needed to master AI programming agents, a skill increasingly essential in the AI‑driven software era.