100% free  ·  12 lessons  ·  48 exercises

What actually happens
when you run Claude Code?

A hands-on course that takes you inside the 8 architecture layers — with animated videos, Python exercises, and real code patterns you can reuse in your own agents.

claude-code
8
Architecture layers
12
Video lessons
48
Python exercises
$0
Forever
Try it

The Agent Loop — step by step

Every Claude Code interaction flows through this 11-step loop. Click through to explore.

1User Input

You type a prompt and press Enter. The terminal captures your keypress and the React renderer picks it up.

> "Add error handling to utils.py"
1 / 11
The Roadmap

Your path through the architecture

4 parts, 12 lessons. Each teaches a production pattern with Python code you can run and reuse.

1
Part 1
Architecture & Core Concepts

Understand the 8 architecture layers, entry points, and how Claude Code's data flows from CLI invocation to API response and back.

Animated video walkthroughArchitecture layer diagramCLI router pattern in PythonScreen buffer diffing exercise5 quiz questions
class ExecutionMode(Enum):
    INTERACTIVE = "interactive"
    ONE_SHOT = "one_shot"
    BRIDGE = "bridge"

Trace a single conversation turn end-to-end through QueryEngine.submitMessage() down to the streaming API call and tool execution sub-loop.

Agentic loop patternAsync generator streamingTool execution sub-loopAuto-compaction strategyMessage type system
async def query(messages, tools):
    while True:
        response = await call_api(messages)
        tool_calls = extract_tools(response)
        if not tool_calls: break

Understand the Tool interface, how tools are registered in assembleToolPool(), and how StreamingToolExecutor runs them safely.

Tool interface contractSorted pool for cache stabilityConcurrent vs exclusive executionJSON Schema validationMCP tool wrapping
class Tool(ABC):
    @property
    def name(self) -> str: ...
    @property
    def is_read_only(self) -> bool:
        return False  # fail-closed default
2
Part 2
Agent Intelligence

Explore sub-agent spawning via AgentTool, the mailbox isolation pattern, and coordinator mode for multi-agent orchestration.

AgentTool spawningMailbox isolation patternGit worktree isolationBudget propagationFan-out / Pipeline / CoordinatorBonus: Coordinator Mode & Teams
class MailboxAgent:
    messages: list  # own history
    budget: float   # own budget
    async def run(self, prompt) -> str:
        # parent only sees the return value

Deep dive into memdir constants, loadMemoryPrompt(), context compaction strategies, and FileStateCache.

Enterprise → User → Project → LocalloadMemoryPrompt() flowContext compaction algorithmFileStateCache LRUThe /compact commandBonus: Kairos & Auto-Dream
levels = [
    "/Library/.claude/",     # enterprise
    "~/.claude/CLAUDE.md",   # user
    "./CLAUDE.md",           # project
    "src/CLAUDE.md",         # subdirectory
]

Understand the multi-layer permission model, ToolPermissionContext, denial tracking, and the YOLO classifier.

Three-outcome modelDenial tracking + escalationYOLO mode internalsTool-specific checkPermissions()Permission rule sources
class PermissionResult(Enum):
    ALLOW = "allow"  # proceed
    ASK = "ask"      # prompt user
    DENY = "deny"    # block + tell Claude
3
Part 3
Extensibility & State

How Claude Code manages UI state in a CLI using a Zustand-like store, React in the terminal, and the SpeculationState pattern.

35-line Zustand-like storeAppState shapeMutation pathsReact-terminal connectionSpeculationState patternBonus: Buddy companion
def create_store(initial):
    state = [initial]
    listeners = []
    def set_state(fn):
        state[0] = fn(state[0])
        for cb in listeners: cb()

The three extensibility layers: slash commands, skills loaded at runtime, and plugins via pluginLoader.

Slash commands (/commit, /review-pr)Skills system (markdown + YAML)Plugin loaderCustom commandsLifecycle hooks
---
# skill frontmatter
name: commit
tools: [Bash, Read, Grep]
model: sonnet
---
Create a git commit...
4
Part 4
Integration & Advanced Topics

How Claude Code implements Model Context Protocol — transports, MCPServerConnection states, and MCPTool wrapping.

MCP protocol overviewTransport types (stdio/HTTP)Connection lifecycle statesMCPTool adapter patternResource accessBonus: UDS Inbox
class MCPTool(Tool):
    def __init__(self, defn, conn):
        self._defn = defn
    async def call(self, args):
        return await self._conn.call_tool(...)

Token budget management, BudgetTracker, streaming retry categories, and the full query() function flow.

BudgetTracker + token limitsStreaming response handling5 retry strategiesFallback model switchingStop hooks
class BudgetTracker:
    continuation_count: int = 0
    def check(self) -> str:
        if self.used > threshold * 0.9:
            return "stop"

Settings hierarchy, getInitialSettings(), Growthbook feature flags, and the bun:bundle DCE system.

4-level settings hierarchyMerge precedence rulesGrowthbook feature flagsDead code eliminationKill switchesBonus: Proactive Mode
# Settings merge precedence:
# enterprise > user > project > local
def merge(*levels):
    result = {}
    for level in levels:
        result.update(level)

How Claude Code connects to IDEs via bridge mode, the replBridge transport, and WebSocket/stdio transports.

Bridge mode architecturereplBridge transportWebSocket (remote)stdio (MCP servers)VS Code + JetBrains
# Bridge mode: headless agent
# IDE ↔ replBridge ↔ Claude Code
# Web ↔ WebSocket ↔ Claude Code
# MCP ↔ stdio ↔ Claude Code
Bonus

Hidden & experimental features

Features found in the source code that aren't fully released yet.

🐾BuddyEXPERIMENTAL

A terminal pet companion that reacts to your coding activity

KairosEXPERIMENTAL

Persistent memory mode — Claude remembers across sessions without CLAUDE.md

📋Proactive ModeEXPERIMENTAL

Claude works while you're idle — monitors files, runs tasks, and sleeps between actions via SleepTool

🎯Coordinator ModeEXPERIMENTAL

Multi-agent orchestration where Claude acts as team lead dispatching to workers

📱Bridge ModeEXPERIMENTAL

Control Claude Code from your phone or browser via WebSocket transport

👥TeamsEXPERIMENTAL

Spawn teammate agents with TeamCreateTool — multi-agent swarms with shared namespaces and in-process workers

📬UDS InboxEXPERIMENTAL

Unix Domain Socket inbox for inter-session communication between Claude instances

💭Auto-DreamEXPERIMENTAL

Automatic session review that extracts learnings and saves them to memory

More courses

Other deep dives

NEW COURSEStandalone · Interactive

vLLM — GPU Memory Architecture

How PagedAttention packs the KV cache into GPU memory like an OS manages RAM. Block tables, prefix caching, and the allocator that makes high-throughput LLM serving possible.

Explore course →

Understand how AI agents
actually work

Every lesson is free. Start with the architecture overview and go from there.

Start Course →