Learn how to build production-grade AI agents by studying Claude Code's architecture
This documentation provides a structured learning path for understanding AI agent development through the Claude Code codebase - a production-grade AI coding assistant that was accidentally exposed through an npm source map leak.
What makes this unique: Unlike toy examples or tutorials, this is real production code (~512,000 lines) from Anthropic, showing how they architect autonomous AI agents at scale.
Before diving in, you should have:
- Strong TypeScript/JavaScript knowledge
- Understanding of async/await and Promises
- Basic familiarity with AI/LLM concepts (prompts, tokens, API calls)
- Terminal/CLI experience
- Git and npm basics
Optional but helpful:
- React knowledge (for understanding the UI layer)
- Experience with tool-calling LLMs (Claude, GPT-4)
- Understanding of software architecture patterns
┌─────────────────────────────────────────────────────────────┐
│ LEARNING JOURNEY │
├─────────────────────────────────────────────────────────────┤
│ │
│ Week 1-2: Fundamentals │
│ ├─ Architecture overview │
│ ├─ Core concepts (tools, permissions, context) │
│ └─ Codebase navigation │
│ │
│ Week 3-4: Tool System │
│ ├─ Tool definition and schemas │
│ ├─ Permission system │
│ └─ Building custom tools │
│ │
│ Week 5-6: Agent Orchestration │
│ ├─ Query Engine deep-dive │
│ ├─ Tool-calling loops │
│ └─ State management │
│ │
│ Week 7-8: Advanced Patterns │
│ ├─ Multi-agent systems │
│ ├─ Context management │
│ └─ MCP integration │
│ │
│ Week 9-10: Practical Projects │
│ └─ Build your own agent system │
│ │
└─────────────────────────────────────────────────────────────┘
Time: 1-2 weeks
- What is an AI agent?
- Claude Code architecture overview
- Core components and their roles
- Execution flow diagram
- Key design patterns
Outcome: Understand the big picture and how all pieces fit together.
Time: 2 weeks
- Tool anatomy and structure
- Schema definition with Zod
- Permission system architecture
- Tool execution lifecycle
- Building your first tool
Outcome: Build custom tools and understand the tool-calling pattern.
Time: 2 weeks
- QueryEngine architecture
- The tool-calling loop
- Streaming and real-time updates
- Error handling and retries
- Context window management
Outcome: Understand how to orchestrate AI-driven workflows.
Time: 2 weeks
- Multi-agent coordination
- Sub-agent spawning
- Context compression
- MCP (Model Context Protocol)
- Plugin architecture
- Memory systems
Outcome: Build complex multi-agent systems.
Time: 2+ weeks
- Hands-on coding exercises
- Progressive projects (beginner → advanced)
- Building a complete agent from scratch
- Best practices and patterns
Outcome: Apply your knowledge to build production-quality agents.
# This repo is already cloned
cd /Users/ahmedkhaled/claude-code
# Explore the structure
tree -L 2 src/ # or use 'ls -R src/ | head -50'Create bookmarks for these core files:
Essential Reading:
├── src/Tool.ts # Tool type definitions
├── src/tools.ts # Tool registry
├── src/QueryEngine.ts # Agent orchestration engine
├── src/main.tsx # Entry point
└── README.md # Architecture overview
Example Tools (Start Here):
├── src/tools/BashTool/
├── src/tools/FileReadTool/
└── src/tools/AskUserQuestionTool/
Advanced (Study Later):
├── src/tools/AgentTool/ # Sub-agents
├── src/coordinator/ # Multi-agent systems
└── src/services/mcp/ # MCP integration
# Install dependencies (if you want to run code examples)
bun install
# Create your own experimental directory
mkdir -p experiments/my-first-agent- Read each part sequentially - they build on each other
- Code along - type out examples, don't just read
- Do the exercises - learning by doing is essential
- Build projects - apply concepts to real problems
| Concept | What You'll Learn | Where to Find It |
|---|---|---|
| Tool Calling | How LLMs invoke functions | src/QueryEngine.ts |
| Permission Gates | Controlling dangerous operations | src/hooks/toolPermission/ |
| Context Management | Managing conversation state | src/context.ts |
| Streaming | Real-time response updates | src/QueryEngine.ts |
| Error Recovery | Handling failures gracefully | src/QueryEngine.ts |
| Pattern | Description | Implementation |
|---|---|---|
| Agent Swarms | Multiple agents working together | src/coordinator/ |
| Sub-agents | Spawning specialized agents | src/tools/AgentTool/ |
| Skills | Reusable workflows | src/skills/ |
| Plugins | Extensibility system | src/plugins/ |
| MCP | Third-party tool integration | src/services/mcp/ |
- Linear approach: Go through parts 1-5 in order
- Time commitment: ~2-3 hours per day for 10 weeks
- Active learning: Code along with every example
- Projects: Build at least 3 projects from Part 5
This guide can support:
- CS Capstone Projects: Build an AI agent as a semester project
- Software Engineering: Study architecture patterns
- AI/ML Courses: Understand practical LLM applications
- Security Courses: Analyze permission systems and safety
- Week 1-2: Group study of fundamentals
- Week 3-4: Team builds simple tools
- Week 5-6: Pair programming on agent orchestration
- Week 7-8: Team project: multi-agent system
- Week 9-10: Code review and presentations
- Duration: 4-5 weeks
- Schedule: 8 hours/day, deep focus
- Projects: 2-3 substantial projects
- Duration: 10-12 weeks
- Schedule: 2 hours/day on weekdays
- Projects: 1-2 projects
- Duration: 12-15 weeks
- Schedule: Saturday + Sunday sessions
- Projects: 1 comprehensive project
- Start with simple files: Begin with
BashTool.js, notQueryEngine.ts - Use TypeScript features: Cmd+Click (VS Code) to navigate to definitions
- Search patterns: Use
grep -r "pattern" src/to find examples - Read tests: Look for
.test.tsfiles for usage examples
| Challenge | Solution |
|---|---|
| "Too much code!" | Start with single tools, don't read everything |
| "Don't understand TypeScript types" | Focus on runtime behavior first, types second |
| "Lost in the codebase" | Use the file reference guide in Part 1 |
| "Concepts too advanced" | Build simple versions first, iterate |
By the end of this guide, you should be able to:
- Explain how tool-calling agents work
- Build custom tools with proper schemas
- Implement a basic permission system
- Create a simple agent orchestration loop
- Handle streaming LLM responses
- Build a multi-agent coordinator
- Integrate external tools via MCP
- Deploy a production-ready agent
This is a living document. If you:
- Find errors or outdated information
- Want to add examples or clarifications
- Have suggestions for improvements
- Built something cool using this guide
Feel free to submit issues or PRs!
Important Reminders:
- This code was accidentally exposed, not intentionally open-sourced
- Original code remains Anthropic's property
- Use for educational and defensive security research only
- Do not use this to build competing commercial products
- Respect intellectual property and licensing
Ready to begin? Start with Part 1: Fundamentals →
Questions before starting? Review the prerequisites and ensure you have the required background knowledge.
Want to jump ahead? While possible, each part builds on previous concepts. Sequential learning is recommended.
Happy learning! 🚀
Last updated: March 31, 2026