Claude Code from the Inside Out

If you've used large language models like ChatGPT or Claude, you've probably experienced this: you ask it to write some code, it gives you an answer, and then you have to manually copy it into your editor, manually run it, manually debug it — every step requires you, the human, to act as the middleman.

Claude Code breaks this pattern. When you type "fix this bug" in your terminal, it reads files on its own, searches through the codebase, edits files, runs tests — all you need to do is click "Allow" at key decision points.

This is the fundamental difference between a ChatBot and an Agent: A ChatBot is an advisor. An Agent is an executor.

1.1 Starting with a Simple Chatbot

The simplest LLM application looks like this:

User input → Call LLM API → Return text → Display to user

That's a ChatBot. Its defining characteristic is that it's one-directional and one-shot — you ask a question, it answers once, then waits for your next question.

But real-world tasks don't work that way. When you say "convert this function from JavaScript to TypeScript," you need to:

1. Find which file the function lives in
2. Read the file contents
3. Understand the existing code logic
4. Generate the TypeScript version
5. Write it back to the file
6. Run the type checker to see if there are errors
7. If there are errors, fix them and check again…

This is a multi-step process with feedback loops that requires external tools. A ChatBot can't do this.

1.2 Agent = LLM + Tools + Loop

The core formula for an Agent is simple:

Agent = LLM (the brain) + Tools (the hands) + Loop (the action cycle)

The LLM is the brain. It's responsible for understanding user intent, analyzing the current situation, and deciding what to do next. In Claude Code, this brain is a Claude model (Sonnet or Opus).

Tools are the hands. An LLM by itself can only generate text, but through "tool use," it can read files, write files, execute shell commands, search code — these are real operations, not hallucinations.

The Loop is the action cycle. This is the most critical part of an Agent. The LLM isn't called just once and done. Instead:

Think → Call a tool → Observe the result → Think again → Call another tool → ... until the task is complete

This loop is known in the research community as the ReAct (Reasoning + Acting) pattern. The core of Claude Code is a production-grade implementation of this ReAct loop.

1.3 From Demo to Production: The Chasm

You might think: isn't this just adding a few function calls to an LLM? How hard can it be?

The answer: there's an enormous chasm between a prototype and a production-grade product.

A simple Agent demo can be built in 100 lines of code. But Claude Code is a 510,000-line TypeScript codebase. Why so much code? Because a production-grade Agent must solve a mountain of problems that demos never have to worry about:

Problem	Demo Approach	Claude Code Approach
Tool execution safety	Execute directly	Multi-layer permission system (rules + classifier + user confirmation)
Context too long	Truncate	Auto-compaction + micro-compaction + trimming (three strategies)
Tool execution efficiency	Serial	Smart orchestration (read ops in parallel, write ops serial)
Cost control	Ignore it	Real-time tracking + budget caps + per-model breakdown
Extensibility	Hardcoded	MCP protocol + plugin system + skill framework
Error recovery	Crash	Exponential backoff retry + circuit breaker + error classification
Multi-Agent	Not supported	Coordinator pattern (main Agent manages sub-Agents)
User experience	print()	346 React components powering a terminal UI

This is why it's worth studying Claude Code's source in depth — it's not an Agent toy, it's a production system validated by millions of users.

1.4 Source Code Overview: Project Structure

src/
├── entrypoints/          # Entry files
├── QueryEngine.ts        # The Agent's core brain
├── query.ts              # The ReAct loop implementation
├── Tool.ts               # Base contract for all tools
│
├── tools/                # 43 tool implementations
│   ├── BashTool/         #   Shell commands
│   ├── FileReadTool/     #   Read files
│   ├── FileEditTool/     #   Edit files
│   ├── AgentTool/        #   Spawn sub-Agents
│   └── ...               #   Plus 35 more
│
├── commands/             # 85+ slash commands
├── services/             # Backend services (API, MCP, analytics)
├── components/           # 346 React/Ink UI components
├── coordinator/          # Multi-Agent coordination
└── utils/                # 290+ utility functions

Six Core Systems

From the architecture, we can identify six core systems that form the backbone of the book:

1. The Query Loop System (Ch 2–3) — The Agent's heart: think → act → observe
2. The Tool System (Ch 4) — The Agent's hands: 43 tools with unified interface design
3. The Permission System (Ch 5) — The Agent's reins: multi-layer defense ensuring safety
4. The Context Management (Ch 6) — The Agent's memory: compaction, trimming, CLAUDE.md
5. The Multi-Agent System (Ch 7) — The Agent's team: Coordinator pattern for parallel tasks
6. The Extension System (Ch 10) — The Agent's ecosystem: MCP, plugins, skills

1.5 How the Program Starts

The startup process reveals Claude Code's design philosophy: defer loading as much as possible.

// entrypoints/cli.tsx - Startup (simplified)

// Fast path: if user just wants --version, don't load anything
if (process.argv.includes('--version')) {
  console.log(version);
  process.exit(0);
}

// Otherwise, load the main module
const { init } = await import('../main');
await init();

// main.tsx - Parallel prefetch optimization

// These I/O operations run in parallel during module loading
startMdmRawRead();       // Read security config
startKeychainPrefetch(); // Read auth tokens (~65ms)

// Then load tools and commands
const tools = await getTools();        // 43 tools
const commands = await getCommands();  // 85+ commands
const mcpClients = await initMCP();    // MCP connections

await launchRepl({ tools, commands, mcpClients });

Reading tokens from macOS Keychain takes ~65ms. By kicking off I/O in parallel during module loading, these costly operations complete essentially "for free."

Key Takeaways

1. Agent = LLM + Tools + Loop. The LLM thinks, Tools act, and the Loop makes them cycle until done.
2. The chasm from demo to product. Permission controls, context management, error recovery, performance optimization — this is where real engineering lives.
3. Claude Code's scale. 510,000 lines, 43 tools, 85+ commands, 346 UI components.
4. Six core systems form the architecture: query loop, tools, permissions, context, multi-agent, extensions.

That's Chapter 1. The remaining 11 chapters dive deep into each system with source code analysis, architecture diagrams, and implementation patterns.