# How Claude Code works under the hood

Claude Code feels like magic. It is not. It is a small set of components wired together in a loop. Once you see the anatomy, the mystery evaporates and you stop treating it as a black box. You start configuring it on purpose, extending it where it falls short, and giving it exactly the autonomy a task deserves.

This guide is a map, not a tutorial. It names every part, explains what each does, and shows how they connect. By the end you will know which knob to turn when the agent does the wrong thing, and where to plug in your own tools.

## Is a coding agent a loop or a pipeline?

Most people imagine a coding agent as a pipeline: you send a prompt, it sends back code. Claude Code runs a loop. The model never just answers; it acts, observes, and acts again until the task is finished.

That loop is the whole agent. Everything else, the terminal UI, the file system access, the shell runner, is infrastructure that makes the loop useful.

## What are the parts of a coding agent?

Claude Code has the same five parts every coding agent has. Knowing them tells you exactly what you can tune.

| Component | What it does | In Claude Code |
| --- | --- | --- |
| **Model** | Reasons, plans, and decides which tool to call next | Sonnet 4.6 by default, switch with `/model` |
| **Tool layer** | Does things in the real world on the model's behalf | Read, Write, Edit, Bash, Glob, Grep, plus MCP |
| **Context manager** | Decides what fits in the window and what to trim | sliding window, summarisation, `/compact` |
| **Permission system** | Gates what the agent can do without asking you | modes, allow-lists, sandboxes |
| **UI / CLI shell** | The surface you interact with | the terminal session |

None of these is exotic. The craft is in wiring them well, and most of that wiring is yours to control.

## Component 1: the model

The model is the brain. It reads the assembled context, picks the next action (usually a tool call), and generates the arguments for that call. It also knows when to stop and produce a final answer.

One thing that surprises people: the model does not run your code or read your files. It asks a tool to do those things, then reads the result. The model is a pure text-in, text-out function. The tool layer is what gives it hands.

Which model you run matters for coding tasks. You want one that is strong at multi-step reasoning, follows complex instructions, and handles large contexts well, because the context grows with every tool round-trip. Claude Code defaults to Sonnet 4.6, which covers most work at a good cost-to-quality ratio. Switch up to Opus 4.8 with `/model` for hard debugging or architecture, and let subagents lean on cheaper models for mechanical work like bulk searches. See [how agents fan out](/guides/how-agents-fan-out) for that strategy.

## Component 2: the tool layer

Tools are functions the model can call by name. Each has a name, a plain-English description (so the model understands when to use it), and a typed argument schema. The model emits a [tool call](/guides/tool-calling-explained); the runner executes it; the result comes back as an observation.

The built-in toolkit:

```
Read        read a file at a path
Write       create or overwrite a file
Edit        apply a precise diff or string replacement
Bash        run a shell command
Glob        find files matching a pattern
Grep        search file contents for a regex
WebFetch    fetch a URL and return the content
MCP tools   anything you add via the MCP protocol
```

MCP is the extension point, and the most important one for making Claude Code yours. Instead of being stuck with the built-in tools, you run a server that speaks the MCP protocol and Claude Code discovers your tools automatically. That is how you add database access, browser automation, or your own internal APIs without rebuilding anything. The [MCP fundamentals guide](/guides/mcp-fundamentals) covers the concept, and [build an MCP server](/guides/build-an-mcp-server) walks through making your own.Resist bolting on every MCP server you find. Each tool's name and description sit in the context window on every turn, so a wall of barely-used tools both burns tokens and makes the model pick the wrong one. Add a server only when you hit a capability you keep needing, and remove the ones you stopped using.

## Component 3: context management

The context window is the agent's working memory. Everything Claude knows in a given turn lives there: your original prompt, the conversation so far, every file it has read, every tool result it has received.

Context fills up fast. A single file read might be 400 tokens. Three round-trips through a large file and you are burning tens of thousands. Claude Code needs a strategy for what to keep, what to summarise, and what to drop, and you have levers over all of it.

The main strategies:

**Sliding window.** Keep only the recent turns. Simple, cheap, loses early reasoning.

**Summarisation.** When the window gets full, compress older turns into a summary and prepend it. In Claude Code you trigger this yourself with `/compact`, or it happens automatically when the window is near full.

**Retrieval.** Embed the codebase, retrieve only the chunks relevant to the current step. Powerful for large repos, complex to build well. See [RAG for coding agents](/guides/rag-for-coding-agents) for how this works on source code specifically.

**Tight tool output.** The cheapest strategy: make each tool return only what is needed. A Bash command that returns the last 50 lines instead of all 10,000 saves more context than any compression scheme. This is why a focused prompt beats a vague one: it keeps the loop's reads small.

Most serious sessions combine these. The [context engineering guide](/guides/context-engineering) goes deep on the tactics, and a well-written project memory file is your single biggest lever, covered below.

## Component 4: the permission system

An agent that can run arbitrary shell commands and edit any file is dangerous without guardrails. The permission system is how you control what Claude Code does on its own versus what needs your approval.

The design space looks like this:

The modes, from most cautious to most autonomous:

- **plan** · Claude reads and reasons but touches nothing. Best for "tell me how you would do this before doing it".
- **default** · file edits and shell commands pause for confirmation.
- **acceptEdits** · file edits run automatically, shell still prompts.
- **bypassPermissions** · everything runs. Only use this inside a sandbox.

The allow-list gives you finer control than a mode alone: you can permit specific Bash commands, or scope Edit to a single directory. That combination of mode plus allow-list is how you tune exactly how much autonomy Claude Code has on a given project. Set sensible defaults once and most sessions stop interrupting you.When the confirmation prompts get annoying, the tempting fix is `bypassPermissions`, but that mode lets the agent run any shell command and edit any file with no approval, so one wrong `rm` or `git reset` on your working tree is unrecoverable. Reach for a scoped allow-list of the commands you trust instead, and keep bypass for a throwaway sandbox or container where a mistake costs nothing.

## Component 5: the CLI shell

The shell is the surface between you and the loop. It is the least interesting component architecturally, but the most visible.

Claude Code streams the agent's steps to your terminal as they happen. You see each tool call and its result in real time. You can interrupt, steer, or approve actions inline. That live visibility is the point: you watch the loop think, and you redirect it the moment it drifts.

The shell's job is to assemble the initial context (open project, system prompt, your message), stream the loop's output to you in a readable form, handle interrupts and permission prompts, and pass tool results back into the loop. That is all. The intelligence is in the model and the quality is in the context you give it.

## What happens in one full turn?

Here is a concrete example. You type: "Add input validation to the login form."

Four tool calls, five model calls, one task done. The loop ran without you touching anything. That is the agent working.

## What makes a Claude Code session good?

The loop is fixed. What you control is the input to it, and a handful of inputs do most of the work.

**Context quality.** A session where Claude reads only what is relevant beats one that dumps the whole file system into the window. Point it at the right files and ask focused questions. Good context assembly is the biggest single lever on quality.

**Project memory.** A memory file at the root of your project is read at the start of every session. Put your build and test commands, your conventions, and anything you find yourself repeating into it. It is the difference between re-explaining your codebase every time and Claude already knowing it. The [rules and memory files guide](/guides/rules-and-memory-files) covers what to put where.

**Permission setup.** Match autonomy to risk. Use plan mode to review an approach first, allow-list the commands you trust, and reserve bypass for a sandbox. Tuned once, this removes the constant prompting without removing the safety.

**Custom tools via MCP.** When Claude keeps lacking a capability (your database, your design system, your deploy pipeline), expose it as an MCP server. The agent gains a new tool and uses it like a built-in.

## Set it up well: a starting checklist

You now have the full map. Turning it into a smooth setup is a short list:

- Write a project memory file with your build, test, and lint commands and your core conventions.
- Set a default permission mode that fits the repo, and allow-list the commands you run constantly.
- Keep prompts focused so the context window stays clean; reach for `/compact` on long sessions.
- Use `/model` deliberately: Sonnet for normal work, Opus for the hard problems.
- Add an MCP server the first time you notice Claude lacking access to something it needs.

If you want Claude to help you set up a project on these lines, try this:

Look at this project and propose a setup for Claude Code: a project memory file with the right build and test commands and conventions, a sensible default permission mode, and an allow-list of commands that are safe to run without asking. Explain each choice before writing anything.

You now know the architecture that runs every time you open Claude Code, and knowing the loop is what lets you tune it.