How Claude Code works

Claude Code feels like magic until you understand the moving parts, and then it feels like a very capable colleague with a predictable way of working. This page explains that way of working: the loop it runs, the tools it uses, what it can see on your machine, how conversations are stored, and how you stay in control.

It is useful for more than code. Anything you can do from a terminal (drafting docs, running builds, searching logs, researching an unfamiliar library) is fair game.

The agentic loop

Every task runs through the same rough cycle:

1. Gather context. Search the repository, read files, check git state, look things up.
2. Act. Edit files, run commands, call tools.
3. Verify. Run the tests, re-read the output, check the result against what you asked for.

The phases are not rigid steps. A question about the code may never leave the first phase. A bug fix might go round all three a dozen times. Claude decides each next step based on what the previous one revealed, which is why it can chain many actions together and recover when something unexpected happens.

You are part of the loop as well. You can interrupt at any moment to add context, correct course or ask for a different approach.

Two things make the loop work: a model that reasons and tools that act. Claude Code itself is the layer in between, supplying the tools and deciding what the model sees. That surrounding layer is what people mean by an "agentic harness".

The model

The model reads code in any language, works out how pieces connect and decides what needs to change. Several Claude models are available with different trade-offs: Sonnet is a strong everyday choice for most coding, while Opus brings deeper reasoning to architecture and gnarly debugging. Switch mid-session with /model, or start with claude --model <name>. Model configuration covers aliases and defaults.

Whenever this handbook says "Claude decides", it means the model is doing the reasoning.

The tools

Without tools, a model can only produce text. Tools let it do things, and every tool result feeds back into the next decision. The built-in set falls into five broad groups:

There are also orchestration tools for spawning subagents, asking you clarifying questions and similar jobs. The tools reference lists them all.

Here is a realistic trace for "the CSV export test is failing, sort it out":

1. Run the test file to reproduce the failure.
2. Read the assertion error and stack trace.
3. Grep for the export function and the serialiser it calls.
4. Read both files.
5. Spot that a date column is formatted with the local timezone and fix it.
6. Re-run the test, then the wider suite to make sure nothing else broke.

Each step only makes sense because of the one before it. That is the loop in action.

Extending the loop

The built-in tools are the foundation. On top of them you can add knowledge with skills, external systems with MCP, deterministic automation with hooks and delegated work with subagents. Features overview helps you choose between them.

What Claude can see and touch

Running claude in a folder gives it access to:

• Your project files, in that folder and below. Files elsewhere need your permission.
• Your terminal. Any command you could run yourself: compilers, package managers, git, Docker, scripts.
• Your git state: the current branch, uncommitted changes and recent history.
• Your CLAUDE.md files, holding project instructions loaded every session. An existing AGENTS.md can be read instead. See memory.
• Auto memory: notes Claude has saved for itself in earlier sessions. The first 200 lines or 25 KB of MEMORY.md, whichever is reached first, are loaded at startup.
• Extensions you have configured: MCP servers, skills, subagents and Claude in Chrome.

Because it sees the whole project rather than one open file, it can make coordinated changes: update a type, every call site that uses it, the tests and the docs, then run the suite.

Where it runs and how you talk to it

The loop and tools are the same everywhere. What changes is where commands execute and what the interface looks like.

Interfaces include the terminal, the desktop app, VS Code and JetBrains, claude.ai/code, Remote Control, Slack and CI through GitHub Actions. Platforms compares them.

Sessions

Every conversation is saved locally as you go. Messages, tool calls and results are appended to a plain-text JSONL file under ~/.claude/projects/. That transcript is what makes resuming, forking and rewinding possible. Before Claude edits a file it also snapshots the original. See the .claude directory for exact paths, retention and how to clean up.

Each new session starts empty. It does not inherit the previous conversation. Continuity comes from CLAUDE.md, which you write, and auto memory, which Claude writes.

Branches and worktrees

Sessions belong to the directory you started them in. The /resume picker shows sessions for the current worktree by default and has shortcuts to widen the list to other worktrees or projects (sessions has the details).

If you switch git branches mid-conversation, Claude sees the new branch's files but keeps the conversation history. To run truly parallel work, give each branch its own directory with git worktrees and run a session in each.

Resuming versus forking

• claude --continue and claude --resume reopen an existing session with the same session ID and append to it.
• --fork-session (on the command line) or /branch (inside a session) copies the history into a new session ID and leaves the original untouched.

Fork when you want to try an alternative approach without polluting the original thread.

The context window

Everything Claude is working with lives in its context window: your messages, file contents it has read, command output, CLAUDE.md, auto memory, loaded skills and the system instructions. It fills up as you work. Run /context to see what is taking space. Context window walks through what loads and when.

Context Claude Code adds by itself

If Claude follows a rule you never wrote, such as adding a Co-Authored-By trailer to commits, it probably came from a system reminder that Claude Code injected. These include your CLAUDE.md content, your output style instructions, a heads-up when a file it read has changed on disk, and commit and pull request attribution lines.

• Change or remove attribution with the attribution setting.
• Drop the built-in git commit and pull request guidance by setting includeGitInstructions to false.

Both are described in the settings reference.

When the window fills

As you approach the limit, Claude Code first clears older tool output and then, if needed, summarises the conversation (compaction). Your requests and important code survive; detailed instructions from early on may not. That is why lasting rules belong in CLAUDE.md rather than in chat.

You can steer compaction by adding a "Compact Instructions" section to CLAUDE.md, or by running it manually with a focus:

/compact keep the migration plan and the list of failing tests, drop the exploration

If one enormous file or output refills the window straight after every summary, Claude Code gives up auto-compacting after a few attempts and shows a thrashing error rather than looping forever. Troubleshooting explains how to recover.

MCP tool definitions are deferred by default: only tool names and server instructions take up space until Claude actually needs a tool, at which point tool search loads its full definition.

Keeping context lean

• Skills load on demand. Only names and descriptions sit in context until a skill is used. For skills you only ever trigger yourself, set disable-model-invocation: true in the frontmatter to keep even the description out. For skills you did not write, the skillOverrides setting does the same. See skills.
• Subagents have their own window. A subagent starts fresh (or, if it is a fork, with a copy of the conversation so far), does its searching and reading in isolation, and hands back a summary. Its tool calls never clutter your session. See subagents.

Features overview lists what each feature costs in context, and costs has more ways to save tokens.

Safety nets

Checkpoints undo file edits

Before every edit Claude snapshots the file. Press Esc twice to rewind to an earlier point, or just ask Claude to undo. Checkpoints are independent of git and survive resuming a session.

They have limits: they only cover file changes made through Claude's edit tools, restores skip symlinked and hard-linked files, and nothing that touches the outside world (a database migration you ran, an API call, a deploy) can be rolled back. Checkpointing has the full picture.

Permissions control what happens without asking

Press Shift+Tab to cycle the permission mode:

For commands you trust, add allow rules in .claude/settings.json so you are not asked every time:

{
  "permissions": {
    "allow": ["Bash(pnpm test:*)", "Bash(git status)", "Bash(git diff:*)"]
  }
}

Rules can be layered from organisation policy down to personal preference. See permission modes and permissions.

Working with it well

Ask it how to use itself

Claude Code can explain its own features. Questions like "how do I write a hook that runs Prettier after edits?" get a sensible answer. Two built-in commands help with setup:

• /init drafts a starter CLAUDE.md for the project.
• /doctor checks your installation and configuration, diagnoses problems and can fix many of them.

Treat it as a conversation

You do not need a perfect prompt. Start with the goal, look at what it does, and refine:

the invoice PDF is missing the VAT line

close, but VAT should come from the customer's country, not ours. look at tax/rates.ts

Iterating is faster than trying to specify everything up front.

Interrupt and redirect

• Press Esc to stop immediately. The running tool call is cancelled and Claude waits. Any queued messages are sent next.
• Type a correction and press Enter while it works. The message is queued; Claude reads it as soon as the current tool calls finish and adjusts within the same turn.

Interactive mode covers queueing in more detail.

Delegate rather than dictate

Brief it as you would a capable teammate: the problem, where to look, what done means. Leave the choice of files and commands to it.

customers on annual plans are being charged twice when they upgrade mid-cycle.
the billing logic lives in services/billing. find the cause, fix it and add a regression test.

Related

• Features overview
• Context window
• Sessions
• Permission modes
• Best practices