Claude Code, under the hood

What actually happens when you press Enter? Less magic than you'd think. Claude Code is a plain loop over a growing list of text — a model that can only act by calling tools, wrapped in a harness that decides which of those calls are allowed to run. Here's the life of one message through the system.

The whole thing is one loop

Strip away the terminal UI and Claude Code is a cycle: your message and its context go to the model, the model asks to use a tool, the request passes through a permission gate, the tool runs, and its result feeds back in — around and around until the model has nothing left to call. Everything below is just that loop, slowed down.

The Claude Code agent loop Your message and context flow left to right into the model. The model's tool requests pass through a permission gate to the tools, and each tool result curves back into the model, repeating until no tool calls remain. You Context Model Gate Tools results feed back — repeat until no tool calls
The agent loop. Your message and context enter the model once; from there, each tool request passes the gate, runs, and its result loops back to inform the next decision — until a turn arrives with no tool calls and the final answer is delivered.

What happens when you press Enter

  1. Your message joins the transcript

    Your text is appended to a running transcript — a plain JSONL log of every message, tool call, and result, which is what lets sessions be rewound, resumed, or forked. Slash commands and skills aren't secret keywords: they expand into ordinary markdown instructions. Your project's CLAUDE.md is pulled in too — delivered as a user message right after the system prompt, not baked into it. Skills are different: only their names load up front; the full instructions load only when a skill is actually used.

    Official docsHow Claude remembers your project →

  2. Context is assembled — as plain text, in order

    Everything the model will "see" lands in one shared context window in a fixed order: system prompt → memory → environment info → tool and skill names → CLAUDE.md as a user message → the conversation so far. It's genuinely all just text — no search index or hidden business logic reshapes it, which is a deliberate design choice. But it isn't all loaded up front: most tool schemas and full skill bodies load lazily, only when they're needed. (Tool definitions, not prose, dominate the token budget — which is exactly why they're deferred.)

    Official docsExplore the context window →

  3. The model decides — and can only act through tools

    Now the model reads that context and responds: with text, with one or more tool calls, or with both in the same turn. Tools are the only way it can touch your machine — read and edit files, run bash, search the codebase, dispatch a subagent. No tool call, no side effect. And each result feeds back in to shape the next decision; that feedback is what turns a single call into an agent rather than a one-shot answer.

    Official docsHow the agent loop works →

  4. The gate: the model proposes, the harness disposes

    A requested tool call doesn't run just because the model asked. First, any PreToolUse hook you've configured fires and can deny it, force a confirmation, or wave it through. If the hook doesn't settle it, the harness checks your permission rules in strict deny → ask → allow order (first match wins). And for bash specifically, an OS-level sandbox can further restrict filesystem and network access. Prompts and CLAUDE.md shape what Claude tries; only this gate governs what actually executes.

    Official docsConfigure permissions →

  5. The loop turns

    If a tool ran, its result is appended to the same flat transcript and the model reasons again — read a file, decide, edit, run tests, decide again — chaining dozens of steps. It repeats until the model produces a turn with no tool calls; then the loop ends and you get the final answer. This one plain loop over one growing transcript is the whole engine. (Subagents branch off it with their own fresh context and return just a summary; Stop hooks can keep it looping until, say, tests pass — but neither replaces the base mechanism.)

    Official docsHow Claude Code works →

  6. The window is finite — so files carry the memory

    The context window has a hard size, so as it fills Claude Code first drops old tool outputs, and only if that isn't enough does it compact — summarizing the conversation while keeping your intent, key files, and errors-and-fixes, and discarding verbatim output. Your project-root CLAUDE.md is re-read from disk and re-injected after a compaction; MEMORY.md is a separate file Claude can write to carry facts forward. Every session starts with a fresh, empty window — durable knowledge lives in files, not in the model.

    Official docsHow Claude Code works →

The throughline: do the simplest thing

Across on-record interviews, the team describes the same rule for almost every decision — pick the simplest option that works, and give the model as raw a view as possible. The recurring examples:

  • One main loop, not a multi-agent swarm by default — Claude Code as a composable Unix-style utility.
  • Plain agentic glob/grep for code search instead of a vector index.
  • Auto-compaction that simply asks Claude to summarize the conversation, rather than bespoke logic.
  • A markdown file (CLAUDE.md) as "memory," instead of a memory architecture.
  • Scaffolding treated as a temporary crutch: shipping Claude 4 let them delete roughly half the system prompt.

Sources: on-record interviews with Boris Cherny & Cat Wu — Latent Space, The Pragmatic Engineer, and Every's "How to Use Claude Code Like the People Who Built It."

How we know this — and what's left out

This page is built only from publicly available information: Anthropic's official Claude Code documentation, its engineering blog, and on-record interviews with the people who built it. Community write-ups are used only where they describe observed behavior anyone can reproduce by using the tool. Nothing here relies on decompiling or reverse-engineering the CLI — a research method Anthropic's terms prohibit, and one whose results are unverified and go stale. When in doubt, the claim was cut rather than dressed up as fact.