Overview
Relevant source files
learn-claude-code is a pedagogical project that teaches harness engineering — the discipline of building environments for AI agent models to operate effectively. This repository teaches a fundamental truth: the model IS the agent, and everything else is harness README.md7-11
For installation and first steps, see Prerequisites and Installation. For the complete file structure, see Repository Structure.
Core Philosophy: Agent vs Harness
The repository is built on a critical architectural distinction:
The Agent is the trained neural network (Claude, GPT, etc.) — the intelligence that perceives, reasons, and decides README.md13-32 Every agent in history, from DeepMind's DQN playing Atari to Claude writing code, is fundamentally a model that learned to act through training README.md19-29
The Harness is everything else — the environment, tools, knowledge base, observation mechanisms, action interfaces, and permission boundaries that allow the agent to function in a specific domain README.md51-63
Harness = Tools + Knowledge + Observation + Action + Permissions
Tools: bash, read_file, write_file, edit_file, load_skill, task_*
Knowledge: skills/*.md, product docs, API references
Observation: git diff, error logs, task board state, teammate messages
Action: CLI commands, file I/O, team coordination, worktree management
Permissions: safe_path validation, dangerous command blocking, approval workflows
This distinction matters: you cannot "develop an agent" by writing if-else logic around LLM API calls README.md33-42 You can only train a model (gradient updates on action-sequence data) or build a harness (the infrastructure the model operates within) README.md43-50 This repository teaches the latter.
Sources: README.md5-85
Purpose and Scope
learn-claude-code demonstrates harness engineering through 20 progressive sessions (s01–s20), each introducing exactly one harness mechanism without modifying the core agent loop README.md162-187 By session 20, the reader has encountered every major subsystem: tool dispatch, planning, context management, task persistence, background execution, multi-agent teams, autonomous behavior, and worktree isolation README.md107-109
The repository is explicitly a 0-to-1 learning project, not a production-ready system. It intentionally simplifies or omits:
- Full event/hook buses (e.g., PreToolUse, SessionStart/End, ConfigChange) README.md219-223
- Rule-based permission governance and trust workflows README.md224-225
- Session lifecycle controls (resume/fork) README.md226-227
- Full MCP runtime details (transport/OAuth/resource subscribe/polling) README.md228-230
The team JSONL mailbox protocol is a teaching implementation for demonstrating async multi-agent communication patterns, not a claim about any specific production system's internals README.md215-217
Sources: README.md107-111 README.md219-230
Repository Structure
The codebase organizes learning materials, reference implementations, and supporting infrastructure into five directories:
Diagram: Repository Directory Structure and Key Files
Sources: README.md289-297
The Core Agent Loop Pattern
Every session implements the same fundamental loop. The agent (the model) decides when to call tools and when to stop. The harness (the code) executes what the model requests README.md155-157 The loop never changes across sessions — only the harness mechanisms surrounding it expand.
The model controls flow through stop_reason. The harness provides execution through TOOL_HANDLERS (a Python dictionary mapping tool names to handler functions) and TOOLS (JSON schemas describing tool interfaces) README.md141-152
Diagram: Agent Loop with Code Entity Mapping
The function implementing this loop is agent_loop() in each session file. The dispatch table is TOOL_HANDLERS. The schema list is TOOLS.
Sources: README.md139-159 README.md190-217
The 20-Session Learning Progression
Each session in agents/ introduces exactly one harness mechanism README.md163 The agent loop remains unchanged — mechanisms attach via new entries in TOOL_HANDLERS, new manager classes, or pre-processing hooks.
| Session | File | Mechanism | Key Classes/Functions |
|---|---|---|---|
| s01 | s01_agent_loop.py | Foundation | agent_loop, run_bash |
| s02 | s02_tool_use.py | Tool Dispatch | TOOL_HANDLERS, safe_path |
| s03 | s03_permission.py | Governance | Permission gates, approval workflows |
| s04 | s04_hooks.py | Event System | HOOKS dictionary, loop extension |
| s05 | s05_todo_write.py | Planning | TodoManager, rounds_since_todo |
| s06 | s06_subagents.py | Context Isolation | run_subagent, CHILD_TOOLS |
| s07 | s07_skill_loading.py | On-demand Knowledge | SkillLoader, get_descriptions |
| s08 | s08_context_compression.py | Infinite Sessions | micro_compact, auto_compact |
| s09 | s09_memory_system.py | Persistence | .memory/, extract_memories |
| s10 | s10_system_prompt_assembly.py | Dynamic Prompts | assemble_system_prompt |
| s11 | s11_error_recovery.py | Resilience | Truncation escalation, backoff |
| s12 | s12_task_system.py | Task Board | TaskManager, .tasks/*.json |
| s13 | s13_background_tasks.py | Async Execution | BackgroundManager, daemon threads |
| s14 | s14_cron_scheduler.py | Scheduling | CronJob, deferred injection |
| s15 | s15_agent_teams.py | Multi-Agent | TeammateManager, MessageBus |
| s16 | s16_team_protocols.py | Coordination | Plan approval FSMs, handshakes |
| s17 | s17_autonomous_agents.py | Self-Organization | Idle cycles, task claiming |
| s18 | s18_worktree_isolation.py | Parallelism | WorktreeManager, git worktrees |
| s19 | s19_mcp_plugin.py | External Tools | MCPClient, tool discovery |
| s20 | s20_complete_reference.py | Integration | All mechanisms combined |
s_full.py combines all mechanisms into a production-ready reference implementation with REPL commands (/compact, /tasks, /team, /inbox, /help) README.md283-286
Diagram: Learning Progression and Conceptual Phases
Sources: README.md161-187 README.md254-286
Harness Architecture: Tools, Managers, and State Layers
The harness architecture organizes mechanisms into three categories: tools (agent's hands), managers (stateful subsystems), and state layers (persistence boundaries) README.md52-62
Diagram: Harness Components and State Management
State Lifecycle Table
| Component | Scope | Storage | Survives Process Restart? |
|---|---|---|---|
messages[] | Conversation turn | RAM | No |
TodoManager | Session | RAM | No |
BackgroundManager | Session | RAM | No |
.transcripts/ | Compression event | Filesystem | Yes (archived) |
TaskManager (.tasks/*.json) | Cross-session | Filesystem | Yes |
TeammateManager (.team/config.json) | Cross-session | Filesystem | Yes |
MessageBus (.team/inbox/*.jsonl) | Cross-session | Filesystem | Yes |
WorktreeManager (.worktrees/) | Cross-session | Filesystem | Yes |
MemoryManager (.memory/) | Cross-session | Filesystem | Yes |
Sources: README.md52-60 README.md289-297
Design Principle: Extend Around, Never Modify Within
Every harness mechanism in this repository attaches around the agent loop, never inside it README.md190-217 The loop in s20_complete_reference.py is structurally identical to s01_agent_loop.py. Only the surrounding machinery differs.
New functionality is introduced through three extension points:
1. Tool Registration
Add an entry to TOOL_HANDLERS (Python dict mapping tool name to handler function) and a corresponding schema to TOOLS (list of JSON tool definitions) README.md193-196
2. Manager Classes
Encapsulate stateful subsystems as manager objects instantiated before the loop. Handler functions delegate to manager methods README.md200-205
3. Pre-Processing Hooks
Insert logic at the top of the while True: loop before the API call README.md209-217 Common hooks: micro_compact() (context cleanup), drain_notifications() (background task results), inbox reads (team messages), and memory injection.
This architectural discipline ensures the agent loop remains simple and unchanged — a critical property for understanding and debugging agent behavior.
Sources: README.md190-217
External Products and Sister Projects
The patterns taught in this repository form the foundation for production tools and sister projects extending the harness with additional capabilities.
Kode Agent CLI — Production-ready coding agent CLI distributed via npm (@shareai-lab/kode). Supports multiple LLM providers, Windows compatibility, LSP integration, and skill management README.md319-326
Kode Agent SDK — Embeddable agent library for integrating agent capabilities into applications, browser extensions, or backend services README.md327-331
OpenClaw / claw0 — Sister repository demonstrating "always-on" harness extensions: heartbeat, cron, IM routing (WhatsApp/Telegram/Slack/Discord), persistent context memory, and Soul personality system README.md333-346
Web Learning Platform — Interactive Next.js application at http://localhost:3000 with visualizations, step-through diagrams, and source viewer README.md348-362
Diagram: Ecosystem Architecture
Sources: README.md319-362
Where to Go Next
Refresh this wiki
On this page
- Overview
- Core Philosophy: Agent vs Harness
- Purpose and Scope
- Repository Structure
- The Core Agent Loop Pattern
- The 20-Session Learning Progression
- Harness Architecture: Tools, Managers, and State Layers
- Design Principle: Extend Around, Never Modify Within
- External Products and Sister Projects
- Where to Go Next