Learn Claude Code: The Complete Guide to Building an AI Coding Agent from Scratch
Want to understand how Claude Code actually works under the hood? Learn Claude Code is a 12-session progressive tutorial that teaches you to build a nano Claude Code-like agent from zero to one. With 23,000+ GitHub stars, it's the #1 educational resource for understanding AI coding agents — not by reading documentation, but by building one yourself, layer by layer.
What Is Learn Claude Code?
An educational repository by shareAI-lab that deconstructs the internals of a Claude Code-like agent into 12 progressive sessions. Each session adds exactly one mechanism on top of a core agent loop — without changing the loop itself. The mantra: "Bash is all you need."
- Language: TypeScript / Python
- License: MIT
- Stars: 23,000+ ⭐
- Forks: 4,400+
- Documentation: English, Chinese (中文), Japanese (日本語)
- Web Platform: learn-claude-agents.vercel.app
The Core Pattern
Every session builds on this single loop:
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})
That's it. The entire agent is a while loop + stop_reason check + tool dispatch map. Every session layers one mechanism on top — without changing the loop itself.
The 12-Session Learning Path
Phase 1: THE LOOP
| Session | Topic | Tools | What You Learn |
|---|---|---|---|
| s01 | The Agent Loop | 1 | while + stop_reason — the foundation |
| s02 | Tool Use | 4 | Dispatch map: name → handler |
Phase 2: PLANNING & KNOWLEDGE
| Session | Topic | Tools | What You Learn |
|---|---|---|---|
| s03 | TodoWrite | 5 | TodoManager + nag reminder |
| s04 | Subagents | 5 | Fresh messages[] per child agent |
| s05 | Skills | 5 | SKILL.md loaded via tool_result |
| s06 | Context Compact | 5 | 3-layer compression to manage context |
Phase 3: PERSISTENCE
| Session | Topic | Tools | What You Learn |
|---|---|---|---|
| s07 | Tasks | 8 | File-based CRUD + dependency graph |
| s08 | Background Tasks | 6 | Daemon threads + notify queue |
Phase 4: TEAMS
| Session | Topic | Tools | What You Learn |
|---|---|---|---|
| s09 | Agent Teams | 9 | Teammates + JSONL mailboxes |
| s10 | Team Protocols | 12 | Shutdown + plan approval FSM |
| s11 | Autonomous Agents | 14 | Idle cycle + auto-claim |
| s12 | Worktree Isolation | 16 | Task coordination + isolated execution lanes |
Quick Start
git clone https://github.com/shareAI-lab/learn-claude-code
cd learn-claude-code
pip install -r requirements.txt
cp .env.example .env # Add your ANTHROPIC_API_KEY
python agents/s01_agent_loop.py # Start here
python agents/s12_worktree_task_isolation.py # Full endpoint
python agents/s_full.py # Capstone: all combined
Architecture
learn-claude-code/
├── agents/ # Python reference implementations (s01-s12 + s_full)
├── docs/{en,zh,ja}/ # Mental-model-first documentation (3 languages)
├── web/ # Interactive learning platform (Next.js)
├── skills/ # Skill files for s05
└── .github/workflows/ci.yml # CI: typecheck + build
Documentation follows a mental-model-first approach: problem → solution → ASCII diagram → minimal code.
From Learning to Shipping
After 12 sessions, two production paths:
Kode Agent CLI
npm i -g @shareai-lab/kode
Open-source coding agent CLI with Skill & LSP support, Windows-ready, pluggable with GLM/MiniMax/DeepSeek and other open models.
Kode Agent SDK
Standalone library with no per-user process overhead. Embeddable in backends, browser extensions, embedded devices, or any runtime. Unlike the official Claude Code SDK which spawns a separate terminal process per user.
Sister Repo: claw0
Teaches how to turn the agent from "use-and-discard" to "always-on assistant":
claw agent = agent core + heartbeat + cron + IM chat + memory + soul
Adds heartbeat (30s check-in), cron scheduling, multi-channel IM routing (WhatsApp/Telegram/Slack/Discord, 13+ platforms), persistent context memory, and Soul personality system.
Learn Claude Code vs Alternatives
Category: This is an educational AI agent building tutorial / framework.
| Feature | Learn Claude Code | OpenAI Agents SDK | Pydantic AI |
|---|---|---|---|
| Focus | Educational: build agent from scratch | Production multi-agent framework | Production agent framework |
| Stars | 23.7K ⭐ | 19.4K ⭐ | 15.3K ⭐ |
| License | MIT | MIT | MIT |
| Language | Python + TypeScript | Python | Python |
| Progressive Learning | ✅ 12 sessions, 4 phases | ❌ | ❌ |
| Core Pattern Exposed | ✅ while loop + tool dispatch | ❌ Abstracted | ❌ Abstracted |
| Documentation | ✅ EN/ZH/JA, mental-model-first | ✅ EN | ✅ EN |
| Web Platform | ✅ Interactive Next.js | ❌ | ❌ |
| Subagent Pattern | ✅ Session s04 | ✅ Built-in | ✅ |
| Team Orchestration | ✅ Sessions s09-s12 | ✅ Multi-agent | ❌ |
| Context Compression | ✅ Session s06 (3-layer) | ❌ | ❌ |
| Background Tasks | ✅ Session s08 | ❌ | ❌ |
| Worktree Isolation | ✅ Session s12 | ❌ | ❌ |
| Production CLI | ✅ Kode Agent CLI | ❌ | ❌ |
| Embeddable SDK | ✅ Kode Agent SDK | ❌ | ❌ |
| Always-On Mode | ✅ claw0 sister repo | ❌ | ❌ |
| Multi-LLM | ✅ via Kode CLI | ✅ | ✅ OpenAI/Claude/Gemini/etc. |
| Type Safety | ❌ | ❌ | ✅ Pydantic validation |
| Structured Output | ❌ | ✅ | ✅ Pydantic models |
| Guardrails | ❌ Teaching scope | ✅ Built-in | ✅ |
| Tracing | ❌ | ✅ Built-in | ✅ Logfire integration |
| Team | shareAI-lab | OpenAI | Pydantic |
When to choose Learn Claude Code: You want to understand how AI coding agents work from the inside out — not use a black-box framework. The 12-session path takes you from a bare agent loop to team orchestration with worktree isolation. Then graduate to Kode CLI/SDK for production. Best for developers who want deep understanding before building.
When to choose OpenAI Agents SDK: You want a production-ready, lightweight multi-agent framework by OpenAI. Agent handoffs, guardrails, tracing, structured output. Use when you need to ship multi-agent workflows quickly without understanding internals.
When to choose Pydantic AI: You want a type-safe, Pydantic-native agent framework with structured output validation, multi-LLM support, and Logfire tracing. Best for Python teams already using Pydantic who want validated agent outputs.
Conclusion
Learn Claude Code is the definitive "build it to understand it" resource for AI coding agents. In 12 progressive sessions, you go from a bare while loop to a full multi-agent system with teams, protocols, autonomous agents, and worktree isolation — understanding every mechanism along the way. Then the Kode CLI and SDK let you ship what you've learned. The mantra says it all: "The model is the agent. Our job is to give it tools and stay out of the way."
Explore Learn Claude Code on GitHub