Build an AI Agent Harness from Scratch: Deep Dive into Claude Code Architecture

Project Overview

learn-claude-code is an educational repository that demonstrates how to build an AI Agent Harness similar to Claude Code. It provides twelve progressive Python lessons that incrementally add mechanisms such as a basic agent loop, tool dispatch, planning, sub‑agents, skill loading, context compression, persistence, background tasks, team coordination, autonomous task claiming, and worktree isolation.

Core Concepts

Agent = trained model that decides when to invoke tools. Harness = execution environment that supplies tools, domain knowledge, observation data, action interfaces, and permission controls.

Harness = Tools + Knowledge + Observation + Action Interfaces + Permissions

Tools:        File I/O, Shell, Network, Database, Browser
Knowledge:   Product docs, API specs, style guides
Observation: Git diff, error logs, browser state, sensor data
Action:      CLI commands, API calls, UI interactions
Permissions: Sandbox, approval workflow, trust boundaries

Harness Engineer Responsibilities

Implement tools (file I/O, shell execution, API calls, browser control, database queries).

Load domain‑specific knowledge on demand rather than injecting everything at startup.

Manage context: sub‑agent isolation, multi‑layer context compression, task system.

Enforce sandboxing and approval for destructive actions.

Record each action sequence as training data for future model fine‑tuning.

You are not writing intelligence; you are building the world in which intelligence lives.

Lesson 1 – Agent Loop

Core idea: a loop plus a tool equals an Agent.

def agent_loop(messages):
    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":
            return
        results = []
        for block in response.content:
            if block.type == "tool_use":
                output = TOOL_HANDLERS[block.name](**block.input)
                results.append({"type": "tool_result",
                                "tool_use_id": block.id,
                                "content": output})
        messages.append({"role": "user", "content": results})

Insights: the loop belongs to the Agent; the code only executes the model’s requests; the model decides when to call a tool and when to stop.

Lesson 2 – Tool Use

Adding a tool requires registering a single handler in a dispatch map.

TOOL_HANDLERS = {
    "bash": bash_handler,
    "read": read_handler,
    "write": write_handler,
    # new tools only need registration here
}

Design pattern: the main loop remains unchanged; each tool is atomic, composable, and clearly described.

Lesson 3 – TodoWrite (Planning & Knowledge)

Agents that list steps before execution achieve roughly double the task‑completion rate.

TodoManager creates a step list.

Nag reminder issues periodic prompts.

Execution trace links each step to its result.

Lesson 4 – Subagents

Large tasks are split into independent sub‑agents, each with its own messages array, preventing context leakage and enabling parallel execution.

Main Agent
    ├─ Subagent 1 (independent messages[])
    ├─ Subagent 2 (independent messages[])
    └─ Subagent 3 (independent messages[])

Lesson 5 – Skills

Domain knowledge is loaded on demand via tool_result instead of static system prompts.

# Skill file (SKILL.md) structure
# Skill Name

## Description
When the skill should trigger

## Context
Domain knowledge, best practices, examples

## Scripts
Optional script library

Loading strategy: avoid injecting all knowledge at startup; load the corresponding SKILL.md only when required.

Lesson 6 – Context Compression

Three‑layer compression keeps conversations affordable.

First layer: tight index (≈50‑100 tokens per result).

Second layer: timeline context.

Third layer: full detail (≈500‑1,000 tokens per result).

Result: reduces token consumption by roughly tenfold.

Lesson 7 – Tasks (Persistence)

A file‑based task graph stores dependencies and supports multi‑Agent collaboration.

pending → in_progress → completed
                ↓
            blocked (waiting for dependencies)

Lesson 8 – Background Tasks

Daemon threads run slow commands asynchronously; upon completion they push a notification into the agent’s queue.

Main Agent loop ←─ Notification queue ←─ Daemon thread
                                      │
                                      └─ Background command

Lesson 9 – Agent Teams

Team members are persisted as JSONL mailboxes, allowing request‑response and asynchronous communication.

Lead Agent
    ├─ Teammate 1 (JSONL mailbox)
    ├─ Teammate 2 (JSONL mailbox)
    └─ Teammate 3 (JSONL mailbox)

Lesson 10 – Team Protocols

Shared communication rules are enforced by a finite‑state machine that handles graceful shutdown and plan approval.

Lesson 11 – Autonomous Agents

Each teammate periodically scans the task board and claims available tasks without explicit assignment.

while True:
    task = scan_task_board()
    if task:
        claim_and_execute(task)
    else:
        sleep(30)  # retry after 30 seconds

Lesson 12 – Worktree Task Isolation

Every task runs in its own worktree directory, preventing interference and enabling Git‑branch isolation.

Task-001 → worktree-001 → /path/to/wt-001
Task-002 → worktree-002 → /path/to/wt-002
Task-003 → worktree-003 → /path/to/wt-003

Architecture Overview

Claude Code = one agent loop
            + tools (bash, read, write, edit, glob, grep, browser…)
            + on‑demand skill loading
            + context compression
            + sub‑agent spawning
            + task system with dependency graph
            + team coordination with async mailboxes
            + worktree isolation for parallel execution
            + permission governance

Project Structure

learn-claude-code/
|-- agents/          # Python reference implementations (s01‑s12, s_full)
|-- docs/{en,zh,ja}/ # Model‑first documentation in three languages
|-- web/             # Interactive learning platform (Next.js)
|-- skills/          # Skill definition files (e.g., s05)
+-- .github/workflows/ci.yml  # CI: type checking + build

Quick Start

Installation

git clone https://github.com/shareAI-lab/learn-claude-code
cd learn-claude-code
pip install -r requirements.txt
cp .env.example .env   # edit .env and add ANTHROPIC_API_KEY

Run

python agents/s01_agent_loop.py          # start with the basic loop
python agents/s12_worktree_task_isolation.py  # run the full advanced endpoint
python agents/s_full.py                  # combine all mechanisms

Web Platform

cd web && npm install && npm run dev   # http://localhost:3000

Reference

GitHub repository: https://github.com/shareAI-lab/learn-claude-code

Official site: https://learn.shareai.run