Learn Claude Code: Harness Engineering for Real Agents
Go from 0 to 1 building a nano Claude Code–like agent harness that turns any trained model into a working agent product.
- Source repo
- shareAI-lab/learn-claude-code
- Stars
- ★ 79k
- Last updated
- 20d ago
- License
- MIT
- Primary language
- Python
- FA score
- 48/100 · Major gaps
At a glance
- How it runs
- Works with
- Platform-specificClaude API
- Cost
- Free software; you pay for model usage
- Setup effort
- Low · running in minutes
- You'll need
- Typical use
- Software engineers who want to understand what Claude Code actually does under the hood and build their own harness from scratch.
- Not a fit if
- Teams wanting production-ready deployment; full hook lifecycle, permission governance, and session resume are omitted
- Readers unwilling to work through 17 chapters; some Python and API familiarity is expected
- Source review
- 48/100 · Major gaps 1 safety controls not found
What does this agent do, and when should you use it?
This repository is a 0-to-1 harness engineering learning project: it shows how to build the operational environment around an agent model, where agency comes from model training and the product is Model + Harness. It delivers 20 progressive lessons (s01–s20), each adding one harness mechanism to a core agent loop: tool use, permission rules, hooks, todo planning, subagents, skill loading, context compaction, memory, error recovery, task persistence, background tasks, cron scheduling, multi-agent teams, worktree isolation, and MCP plugins. Every lesson includes a full narrative README, bilingual (Chinese/English/Japanese) translations, a runnable code.py, and diagrams. The loop itself never changes; only the harness mechanisms layer on. The repo is MIT licensed and offers a clear learning path, legacy track mapping, and pointers to production spinoffs like Kode CLI and the claw0 always-on assistant. It is aimed at developers who want to understand the machinery behind agent products and build their own. The core philosophy: build the harness well, and the model will do the rest.
Each chapter ships a standalone Python file (code.py) that implements one Agent Loop plus a specific harness feature. The main loop calls the Anthropic Messages API (client.messages.create), appends tool results, and continues until stop_reason is 'tool_use'. Tools are dispatched through a TOOL_HANDLERS mapping, starting with a single Bash tool. Mechanisms include permission handling (PermissionRule), pre/post tool hooks, TodoWrite as a planning aid, subagents that spawn fresh message contexts, on-demand skill loading via SkillManifest, multi-layer context compaction (snipCompact, microCompact, toolResultBudget, autoCompact), memory selection/extraction/consolidation, a system prompt assembler, retry logic, a disk-backed task system (TaskRecord, blockedBy), background threads, a cron scheduler, a message bus for agent teams, worktree isolation helpers, and an MCP plugin channel. The learner runs scripts like python s01_agent_loop/code.py, python s08_context_compact/code.py, or the endpoint python s20_comprehensive/code.py to observe each mechanism. The repo also includes a legacy 12-lesson track and a web app.
- Software engineers who want to understand what Claude Code actually does under the hood and build their own harness from scratch.
- Developers frustrated by drag-and-drop workflow builders or no-code agent platforms who want a principled, model-centric approach.
- Teams planning to embed agent capabilities into their products and considering the provided Kode SDK as a foundation.
- Educators and self-learners looking for a progressive, code-first curriculum with runnable examples and diagrams in multiple languages.
- Researchers exploring always-on assistant patterns beyond the use-and-discard model, using the OpenClaw/claw0 comparison.
How do you install or deploy this agent?
- Clone the repo: git clone https://github.com/shareAI-lab/learn-claude-code
- Enter the directory: cd learn-claude-code
- Install Python dependencies: pip install -r requirements.txt
- Create your .env from .env.example and set ANTHROPIC_API_KEY (Anthropic API key).
How do you use this agent?
Work through the 20 lessons in order. Start with python s01_agent_loop/code.py to see the minimal agent loop with a single Bash tool, then run increasingly complex chapters such as python s08_context_compact/code.py, and finish with python s20_comprehensive/code.py to see all mechanisms combined. Each lesson's README.md (English/Chinese/Japanese) explains the concepts with inline code and diagrams. Alternatively, the legacy track (agents/*.py) and web app are available.
What are this agent's strengths and limitations?
- Teaches harness engineering from first principles, with every lesson adding exactly one mechanism and providing a runnable example—very effective for learning.
- Strong conceptual clarity: separates 'training a model' (agency) from 'building a harness' (product), avoiding common over-engineering traps.
- High-quality multilingual documentation (EN/ZH/JA) with SVG diagrams and self-contained code for each chapter.
- Requires an Anthropic API key and thus locks you to a single provider; you cannot easily swap in a different model without code changes.
- Deliberately omits production-grade features (full hook lifecycle, rigorous permission governance, session resume, full MCP), so you must extend it for real deployment.
- Substantial time investment: 20 chapters with detailed reading; some entry-level Python and API familiarity expected.
How does this agent compare with similar options?
Compared to Claude Code itself, this repo is a teaching-grade minimal reimplementation—not a drop-in replacement. Compared to OpenClaw, this repo focuses on the use-and-discard harness, while OpenClaw demonstrates how heartbeat and cron transform an agent into an always-on assistant; both projects complement each other.
Key facts side by side with the most closely related agents.
| Agent | Source review | Form / cost | Stars | Updated | Language | Full support on |
|---|---|---|---|---|---|---|
| Learn Claude Code: Harness Engineering for Real Agents This agent | 48 · Major gaps | CLIFree + model costs | ★ 79k | 20d ago | Python | Claude API |
| Claude Code From Scratch | 60 · Some gaps | CLIFree + model costs | ★ 2.8k | 3mo ago | Python | OpenAI API · Claude API |
| Build Your Own OpenClaw | 21 · Major gaps | CLIFree + model costs | ★ 1.9k | 3mo ago | Python | — |
| claw0: Build an AI Agent Gateway from Scratch | 28 · Major gaps | CLIFree + model costs | ★ 3.4k | 3mo ago | Python | Claude API |
How does FollowAgents rate this agent?
Why each dimension lost points
Evidence: README describes permission control (s03 Permission) and user confirmation (s03 'execute, stop, or ask user'), but no implementation details. Data flow transparency: README mentions tool execution and result appending, but not how data flows or if logged. Sensitive data handling: No mention of API key handling, but .env.example exists, implying key management. Dependency security: requirements.txt lists anthropic, python-dotenv, pyyaml without pinned versions, no vulnerability scanning mentioned. External effects: Tool execution may have external effects, but no security boundaries discussed. Rollback: No rollback mechanism mentioned. Source attribution: README mentions 'shareAI-lab' and 'Kode Agent CLI', but no author or maintainer info. Deductions: Permission and confirmation mechanisms only mentioned, not implemented; data flow and sensitive data handling lack specifics; dependencies not pinned; external effects not discussed; rollback missing; source attribution unclear.
Evidence: README describes multiple sessions (s01-s20) and legacy migration, but no consistency guarantee. Dependency availability: requirements.txt lists dependencies without pinned versions, affecting reproducibility. Failure messages: README mentions error recovery (s11), but no specific failure message examples. Deductions: Self-consistency reduced by coexistence of old and new versions; dependency versions not pinned; failure messages not specified.
Evidence: README targets Harness engineers, provides learning paths and multiple scenarios (e.g., agriculture, hotel). Capability boundaries: README explicitly states simplified or omitted production mechanisms (e.g., full event/Hook bus, rule-based permission governance). Trigger precision: README describes sessions and tools, but not detailed trigger conditions. Environment fit: README mentions web platform and CLI, but no system requirements. Deductions: Trigger precision not detailed; environment fit info insufficient.
Evidence: README provides project structure, install instructions (pip install, npm install), examples (s01-s20 code), known limitations (scope section), MIT license. Naming stability: README mentions coexistence of old and new versions, potentially confusing. Versioning changelog: Not provided. Maintenance responsibility: Not clear. Deductions: Naming stability reduced by old/new coexistence; versioning changelog missing; maintenance responsibility unclear.
Evidence: README provides runnable code examples (code.py), output usability high. Marginal value: As a learning project, provides 0-to-1 Harness building tutorial, educational value. Cost-benefit: Few dependencies, simple install, low cost. Deductions: Output usability not verified by actual run; marginal value based on description, not verified.
Evidence: README cites external links (e.g., Nature, OpenAI) to support arguments, but no internal code verification. Cross-source corroboration: No other sources provided. Fact-inference separation: README mixes facts (historical events) and inferences (Harness engineering principles). Deductions: Claim traceability insufficient; cross-source corroboration lacking; facts and inferences not clearly separated.
- Not found in source: rollback or recovery pathBack up first, or work on a git branch or snapshot, so its changes can be undone.
- Dependencies are not pinned, potentially introducing incompatibility or security risks.
- Permission and user confirmation mechanisms are only described, not implemented, so actual security is unknown.
- Coexistence of old and new versions may cause naming confusion, affecting usage.
- No versioning changelog provided, maintenance responsibility unclear.