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

Claude Code is a harness around a Claude model. You give it a task, the model chooses a tool (search, read a file, edit, run a command), Claude Code runs it on your machine and returns the result, and the model decides the next step from that result, over and over, until the task is done or you stop it.

- Page: https://tecyfy.com/coding-agents/claude-code/how-it-works
- Guide: Claude Code (https://tecyfy.com/coding-agents/claude-code), from Anthropic's documentation (https://code.claude.com/docs/en/overview)

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 [Agent](https://tecyfy.com/concepts/agent) 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:

| Group | What it can do | Asks first, in Manual mode? |
| --- | --- | --- |
| Files | Read, edit and create files | Reading no; editing yes, in Manual mode |
| Search | Find files by name and text by pattern | No |
| Commands | Run anything you could type: tests, builds, git, package managers | Yes, except a set of read-only commands |
| Web | Search the web and fetch a page | Yes |
| Code intelligence | Type errors, go to definition, find references | No; needs a plugin for your language |

On top of these are tools for running work: starting a [Subagent](https://tecyfy.com/concepts#subagent) with its own context, asking you a multiple-choice question, keeping a task list. You can add more tools by connecting [MCP servers](/coding-agents/claude-code/mcp).

Each tool has a name, such as `Read`, `Edit` or `Bash`. Those names are what you write in [permission rules](/coding-agents/claude-code/permissions) and [hooks](/coding-agents/claude-code/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](/coding-agents/claude-code/project-instructions) 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 Window](https://tecyfy.com/concepts/context-window) 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 [Compaction](https://tecyfy.com/concepts#compaction). 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:

```text
/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](/coding-agents/claude-code/sessions) 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](/coding-agents/claude-code/project-instructions).

## Questions

### Does Claude Code run on my computer or in the cloud?

The tools run on your computer by default, in the folder you started it in, with the access your user account has. The model runs on Anthropic's servers, which is why it needs an internet connection. Claude Code on the web runs the whole session in a cloud machine instead.

### Does Claude Code remember my last session?

Not by itself. Each session starts with an empty context window. What carries over is what is written down - your CLAUDE.md files and the notes it saves in its auto memory - and you can reopen an old conversation with claude --resume.

### What happens when the context window is full?

Claude Code compacts the conversation. It first clears old tool output, then replaces the conversation with a summary. Your CLAUDE.md and auto memory are reloaded from disk afterwards, but instructions you only typed early in the chat can be lost, so put lasting rules in CLAUDE.md.

### Can Claude Code see my whole codebase at once?

No. It sees what it reads. It searches the project and opens the files it needs, and each read takes up room in its context window. That is why naming the right file, or pointing it at a test, makes it faster and more accurate.

## Sources

- [How Claude Code works](https://code.claude.com/docs/en/how-claude-code-works)
- [Tools reference](https://code.claude.com/docs/en/tools-reference)
- [Explore the context window](https://code.claude.com/docs/en/context-window)