Claude Code Source Leak: 7 Agent Architecture Lessons

1. The Agent Loop Is Dead Simple—The Harness Is Everything

The most surprising thing about Claude Code's core architecture? It's a while loop.

// Simplified representation of Claude Code's core loop
while (true) {
  const response = await model.generate(messages);
  if (!response.hasToolCall()) break;
  const result = await executeTool(response.toolCall);
  messages.push(response, result);
}

The model produces a message. If it contains a tool call, the tool executes, results get appended to the conversation, and the loop continues. No tool call? The loop stops and waits for user input. Everything is stored as immutable messages—full state is reconstructible from conversation history alone.

This sounds almost trivially simple. And that's the point. Teams building their first agent often reach for complex state machines, DAG-based orchestration, or custom control flow engines. Claude Code proves you don't need any of that. A while-loop over tool calls, with message history as the core data structure, handles an enormous range of agentic behavior.

The complexity isn't in the loop—it's in the harness around it. The 512,000 lines of code aren't agent logic. They're context management, permission systems, tool schemas, error recovery, memory, and compression. The loop itself fits in 20 lines.

Takeaway: If your agent framework needs a PhD to understand its control flow, you're overengineering the wrong layer. Keep the loop simple. Invest in the harness.

2. Embed Safety at the Point of Use, Not in a Policy Doc

Most agent frameworks handle safety with a separate policy layer—a permissions file, a guardrails config, maybe a content filter. Claude Code does something different: safety rules are embedded directly inside tool descriptions, exactly where the model encounters them.

The git safety protocol lives inside the Bash tool's description:

- NEVER run destructive git commands (push --force, reset --hard,
  checkout ., restore ., clean -f, branch -D) unless the user
  explicitly requests these actions
- NEVER skip hooks (--no-verify, --no-gpg-sign) unless the user
  explicitly requests it
- CRITICAL: Always create NEW commits rather than amending

This isn't just documentation style—it's an architectural decision. LLMs attend to instructions more reliably when they appear in the immediate context of the action they govern. A safety rule buried in a separate system prompt section is easier for the model to "forget" during long conversations. A rule embedded in the tool it constrains is present every time that tool is invoked.

Beyond inline rules, the codebase reveals a defense-in-depth approach that's genuinely impressive:

Each of those 23 bash checks likely corresponds to a real attack someone tried. That's production security: specific, layered, and born from incidents.

Takeaway: Don't relegate safety to a separate config file. Embed constraints directly in tool descriptions. Use cheap models for cheap safety decisions. And assume every check you write will eventually need to block a real attack.

3. Replace General-Purpose Tools with Structured Alternatives

Claude Code could expose a single bash tool and call it a day. Instead, it provides dedicated tools for every common operation:

The Bash tool's own description explicitly warns: "Avoid using this tool to run find, grep, cat, head, tail, sed, awk, or echo commands."

Why? Three reasons that apply to any agent system:

This mirrors what we've seen at Particula Tech when building agent systems for clients. Agents with 5-8 well-described, purpose-built tools consistently outperform agents with a single omnibus tool—even when the omnibus tool is technically more capable. The specificity of the tool description acts as a form of context engineering that guides the model toward correct behavior.

Takeaway: Every shell command your agent runs frequently should become a dedicated, typed, permission-gated tool. The overhead of building these tools pays for itself in reliability, auditability, and safety.

4. Context Engineering Is the Competitive Moat

The leaked source confirms what we've been telling clients: context engineering—not prompt engineering—is where production AI systems succeed or fail.

Claude Code uses a SYSTEM_PROMPT_DYNAMIC_BOUNDARY pattern that separates static instructions (which never change between sessions) from dynamic context (session-specific data). This isn't just organization—it's a cache optimization. Static content hits the prompt cache; dynamic content sits after the boundary. The team tracks 14 separate cache-break vectors to monitor what invalidates the cache.

Think about that. Anthropic employs some of the best prompt engineers on the planet, and they're spending engineering effort on where things sit in the context window and what breaks the cache. Not on wordsmithing instructions.

The three-layer compression architecture reveals how seriously they take context management:

A bug where autocompaction continuously retried was burning roughly 250,000 API calls per day globally before being patched with just 3 lines of code. That's the scale at which context management decisions matter.

For teams building their own agents, the lesson is clear: instrument what goes into your context window. Measure which context elements correlate with successful outcomes. Build compression and eviction strategies. This is the infrastructure work that separates demos from products. Our guide on prompt compression and context window optimization covers the practical implementation patterns.

Takeaway: Cache-aware prompt architecture, aggressive context compression, and meticulous tracking of what breaks the cache are table stakes for production agents. If you're not measuring your context window composition, you're flying blind.

5. Memory Should Be Indexed Hints, Not Trusted Truth

Claude Code's memory system treats its own memories as unreliable.

The architecture uses a lightweight MEMORY.md index file—always loaded, always under 200 lines—with each entry being a one-line pointer to a detailed topic file. Detailed notes live in separate files (debugging.md, patterns.md) that are fetched on demand, not loaded by default.

The critical design choice: the agent is explicitly instructed to treat memories as hints and verify them against the actual codebase before acting. A memory that says "function X exists in file Y" is treated as a claim that may be stale. Before recommending based on that memory, the agent greps for the function to confirm it still exists.

This "skeptical memory" pattern solves a problem we've seen repeatedly in client deployments: agents that confidently recommend outdated information because their memory says it's correct. The fix isn't better memory storage—it's building verification into the retrieval flow.

The memory system also includes an autoDream feature that runs during idle periods as a forked sub-agent, performing "memory consolidation"—merging observations across sessions, removing contradictions, and converting tentative notes into confirmed facts. It's essentially garbage collection for agent memory.

Write discipline is another underappreciated detail: the agent only updates its memory index after a successful file write, preventing pollution from failed attempts. This is defensive programming applied to agent cognition.

Takeaway: Design agent memory as a lightweight index with on-demand retrieval, not a monolithic knowledge store. Always verify memories against current state before acting. Build consolidation and cleanup into your memory lifecycle. For a deeper dive on memory architecture, see our guide on how AI agents maintain context across conversations.

6. Multi-Agent Parallelism Through Cache Sharing

The economics of multi-agent systems usually kill them. If spawning a sub-agent means paying for a full context window of tokens, parallelism becomes prohibitively expensive. Claude Code solves this elegantly: when it forks a sub-agent, it creates a byte-identical copy of the parent context so they share the KV cache.

This means sub-agents process only their unique instructions—not the entire shared context. Parallelism becomes nearly free in token cost.

The orchestration pattern follows a coordinator/worker model:

Workers operate in isolated git worktrees—each gets its own copy of the repository, preventing merge conflicts during parallel edits. Dangerous operations use a mailbox pattern: workers can't independently approve high-risk actions. Instead, they send a request to the coordinator's mailbox for evaluation.

Sub-agents are spawned as regular tool calls—no special orchestration framework. The AgentTool is just another tool in the registry. This keeps the architecture flat and composable rather than introducing a separate multi-agent runtime.

For teams building multi-agent systems, the implication is clear: if your sub-agents don't share cache with the parent, you're paying a massive token tax on parallelism. Design your agent spawning with cache sharing as a first-class concern.

Takeaway: Cache sharing makes multi-agent systems economically viable. Use a coordinator/worker pattern with isolated execution environments. Make sub-agent spawning just another tool call to keep architecture flat.

7. Use Cheap Models for Cheap Decisions

Not every decision in an agent system needs your most expensive model. Claude Code demonstrates this principle consistently:

This tiered approach to model routing isn't just cost optimization—it's latency optimization. A Haiku safety check takes milliseconds. A full Opus inference for the same check would add seconds of latency to every dangerous command.

We've written extensively about model routing patterns that route cheap requests to cheap models first. Claude Code's architecture validates this approach at scale: the main model handles reasoning and generation, while everything else—safety checks, compression, sentiment—uses the cheapest tool that can do the job reliably.

Takeaway: Audit every LLM call in your agent and ask: does this need frontier reasoning? Permission checks, classification, compression, and formatting can usually be handled by smaller models or deterministic code.

What This Means for Your Agent Architecture

The Claude Code leak is, unintentionally, the most comprehensive open-source reference architecture for production AI agents. Here's how to apply it:

If you're starting a new agent project: Begin with a simple while-loop over tool calls. Build dedicated, typed tools instead of exposing a generic shell. Embed safety rules in tool descriptions. This foundation will take you further than any framework.

If you have an existing agent in production: Instrument your context window—measure what goes in, what correlates with success, and what breaks your cache. Build a three-tier compression strategy. Replace your monolithic memory with an indexed, skeptical system.

If you're scaling to multi-agent: Design cache sharing from day one. Use isolated execution environments (worktrees, containers) for parallel workers. Keep orchestration flat—sub-agents as tool calls, not a separate runtime.

The irony is that none of these patterns are theoretically novel. Simple agent loops, structured tools, defense-in-depth security, cache-aware prompting, skeptical memory—these are all things the community has discussed. What the Claude Code leak provides is proof that these patterns work at scale, in the most demanding production environment for AI agents that exists today.

The hype will fade. The architecture lessons won't.

The hype cycle around this leak will follow the usual pattern: intense coverage for a week, memes for two, then silence. But six months from now, the teams that studied the architecture—not the drama—will be shipping better agents because of it.