How Claude Code Works - Jared Zoneraich, PromptLayer

This talk explores the underlying architecture and design philosophy that have made modern coding agents, particularly Claude Code, so effective. The primary thesis is that the recent explosion in capability is due to two main factors: Simple Architecture and Vastly Improved Models.

The Philosophy: Simplicity and Trust in the Model

The core architectural principle is to “give it tools and then get out of the way.” Instead of building complex, brittle scaffolding with numerous edge cases and classifiers (like Directed Acyclic Graphs or DAGs), the modern approach relies on a simple master loop and trusts the model’s inherent flexibility and instruction-following capabilities. This is summed up by the mantra “less scaffolding, more model.”

This approach discards older paradigms like complex RAG systems, intent classifiers, and parser matching, which were designed to compensate for weaker models. The philosophy is analogous to the Zen of Python: “Simple is better than complex” and “Flat is better than nested.” The speaker argues against over-engineering solutions for current model flaws, as future model improvements will likely render them obsolete.

The Core Architecture: A Master Loop with Tools

The heart of Claude Code is a simple while loop that executes as long as the model generates tool calls. The process is:

1. The model generates one or more tool calls in its response.
2. The system executes these tools.
3. The tool results are fed back into the context.
4. The loop repeats until the model generates a response without tool calls, at which point it typically asks the user for the next step.

Key Tools and Components

The agent is equipped with a small set of powerful, human-like tools:

• bash: The most critical tool, described as the “universal adapter.” It allows the model to run scripts, create/delete files, and use any shell command, leveraging the vast amount of training data available for these common developer actions.
• edit: Uses unified diffs to modify files instead of rewriting them. This is faster, consumes less context, and is less prone to error.
• grep/glob: Simple search tools that mimic how a human would find information, replacing more complex vector search/RAG implementations.
• read: A tool for reading files that is aware of token limits.
• tasks (Sub-agents): A crucial mechanism for context management. A task runs in a separate, isolated context and returns only the final result to the main loop, preventing the primary context from getting cluttered and making the model “stupid.”
• To-Do Lists: A planning mechanism that is surprisingly implemented purely through prompting, not deterministic enforcement. The model is instructed to create, follow, and mark tasks as complete, which enhances steerability, UX, and the ability to resume after crashes.
• Constitution (claude.md): A simple markdown file where users or the agent can place high-level instructions, replacing the need for complex automated repository analysis.

Context Management: The Biggest Enemy

Since a bloated context degrades model performance, several strategies are employed:

• Sub-agents (tasks): As mentioned, they isolate work into separate contexts.
• Context Compression: When the context window nears its limit, the system summarizes the middle of the history, keeping the beginning and end intact.
• External Memory: The agent is encouraged to use the bash sandbox to save long-term memory and research into files, keeping the active context lean.

Comparison with Other Agents

There is no single best architecture; different agents embody different design philosophies (the “AI Therapist Problem”).

• Codex (Sourcegraph): Similar master loop but with a Rust core, more event-driven architecture, and a different, kernel-based approach to sandboxing.
• AMP (Sourcegraph): Focuses on creating “agent-friendly environments” and introduces concepts like “handoff” (starting a new thread with context) as an alternative to context summarization.
• Cursor: A UI-first agent prized for its speed. Its composer model is a prime example of a distilled/fine-tuned model, demonstrating the power of leveraging user data for performance and defensibility.

Takeaways for Builders

1. Trust in the Model: Rely on the model’s exploratory capabilities rather than trying to script every possibility.
2. Simple Design Wins: A simple loop is more robust and maintainable than a complex DAG.
3. bash is (almost) all you need: Start with a small set of powerful, general-purpose tools.
4. Context Management Matters: This is the primary bottleneck and area for optimization in current agent design.
5. Rigorous Tools, Flexible Loop: While the main agent loop should be flexible, the individual tools it calls can and should be rigorously tested like any other function to provide determinism where needed.

• Tags:
• Prompt Engineering
• Feature
• Claude Code
• Sandboxing
• Coding Agents
• Cursor
• Codex
• Tool Calling
• Agent Architecture
• Sourcegraph AMP
• PromptLayer