How Claude Code works: the agent loop, tools and context

Claude Code feels like a colleague typing in your terminal, but it is a simple machine repeated many times. Knowing the machine explains most of what it does well and most of what it gets wrong.

A model and a set of tools, in a loop

There are 2 parts. The model is Claude, running on Anthropic's servers. It reads text and writes text; on its own it cannot open a file or run a command. The tools are small programs on your computer that can. Claude Code is the layer between them, often called the harness: it gives the model the list of tools, runs the one the model asks for, and hands back the result.

Ask it to fix a failing test and the turns go roughly like this:

1. The model asks to run the test command. Claude Code runs it and returns the output.
2. The model reads the error and asks to search for the function named in it. Claude Code returns the matching files.
3. The model asks to read 2 of them, then to edit one.
4. It asks to run the tests again. They pass, and it tells you what it changed.

Anthropic describes this as 3 phases that blend together: gather context, take action, verify the result. Nothing in it is planned in full up front. Each step is chosen from what the last one returned, which is what makes it an AgentAgentA model that uses tools in a loop, deciding each next step from what the last one returned, until the task is done. rather than a script, and why it can recover from a wrong guess.

You are part of the loop. Press Esc and it stops after cancelling the running tool. Type a correction while it works and it reads it before its next step.

The tools it has

The built-in tools fall into 5 groups:

On top of these are tools for running work: starting a SubagentSubagentAn agent started by another agent for one part of a task. It works in its own fresh context and returns only its findings. with its own context, asking you a multiple-choice question, keeping a task list. You can add more tools by connecting MCP servers.

Each tool has a name, such as Read, Edit or Bash. Those names are what you write in permission rules and hooks, so they are worth knowing.

What it can reach

When you run claude in a folder, the agent can work with:

• Your project: every file in the folder and below it, and files elsewhere if you allow it.
• Your terminal: any command your user account can run. This is the reason permissions matter. It has your access, not a smaller one.
• Your Git state: the branch, uncommitted changes and recent commits.
• Your instructions: CLAUDE.md files and the notes in its auto memory.
• What you add: MCP servers, skills, subagents and plugins.

By default all of this runs on your machine. Claude Code on the web runs the same loop on a cloud machine instead, so it keeps going when you close the laptop.

The context window fills as it works

The model only knows what is in its Context WindowContext WindowEverything a model can see at once while it writes an answer, counted in tokens. When the window is full, something has to be left out. this turn: the system instructions, your CLAUDE.md, the conversation so far, and every file it has read and every command output it has seen. Before you type anything, CLAUDE.md, auto memory, the names of MCP tools and the descriptions of skills are already in there. Each file read adds more.

That has 3 consequences you will notice:

• Long sessions get worse. The more there is in the window, the more old detail competes with the task at hand. Run /clear between unrelated tasks.
• It does not see what it has not read. It never holds your whole codebase at once. A pointer to the right file or test saves it a search and saves you tokens.
• Big outputs are expensive. One huge log in the conversation costs tokens on every later turn. A Read call returns at most 25,000 tokens by default, so very large files are read in pages.

Type /context to see what is using space right now.

When it fills up: compaction

As the window nears its limit, Claude Code makes room. First it clears old tool output, then, if it must, it replaces the conversation with a summary. This is CompactionCompactionReplacing the older part of a long conversation with a summary, so an agent can keep working when its context fills up.. Your requests and the main code survive; detailed instructions from early in the chat may not.

After compacting it reloads CLAUDE.md and auto memory from disk, re-reads up to 5 of the files it worked on most recently, and puts back the skills it was using, up to a size cap. So the rule is simple: anything that must hold for the whole session belongs in CLAUDE.md, not in a message you typed an hour ago. You can also compact on your own terms before a new phase of work, telling it what to keep:

/compact keep the decisions about the payment API and the failing test names

Sessions are files, and each starts empty

Every message, tool call and result is saved as you go, in a file under ~/.claude/projects/. That is what lets you resume, branch and rewind a session.

But a new session starts with an empty context window. It does not remember yesterday's conversation unless you reopen it, or unless what mattered was written into CLAUDE.md or its auto memory. If you find yourself explaining the same thing every morning, that sentence belongs in CLAUDE.md.