How Claude Code works, in plain words

Claude Code is an assistant that runs in your terminal and can do anything you could do from the command line: read and edit files, run commands, search, run tests. This page explains the few ideas that make the rest of it easier to understand, with links to the longer guides.

The loop

When you give Claude a task, it works in three overlapping phases: gather context, take action and verify the result. A question about your code may only need the first. A bug fix goes around the loop several times. Claude decides each step from what it learned in the previous one, and you can step in at any point to steer it.

Two parts power the loop: a model that reasons, and tools that act. Claude Code is the layer around the model that provides the tools and manages what the model sees. You can switch models with /model or start with claude --model <name>.

The tools

Without tools, Claude can only answer in text. With them it can act. The built-in tools fall into five groups: file operations (read, edit, create, rename), search (by name or by content), execution (shell commands, tests, git), web (search and fetch), and code intelligence such as type errors and jump to definition, which needs a plugin. Every tool result feeds the next decision. For "fix the failing tests", Claude might run the tests, read the errors, search for the source files, read them, edit, and run the tests again.

On top of the base tools you can add skills, MCP servers, hooks and subagents.

What it can see

When you run claude in a folder, it can reach the files in that folder and below (and elsewhere, with your permission), your terminal, your git state, your CLAUDE.md (or an AGENTS.md, which it can read in its place), its auto memory, and any extensions you configured. See the memory guide.

Where it runs, and how you reach it

By default it runs on your machine. It can also run in cloud environments, or on your machine while you control it from a browser. You can use it from the terminal, the desktop app, IDE extensions, the web, Slack and CI pipelines. The interface changes how you see and talk to it; the loop underneath is the same.

Sessions

Claude Code saves each conversation locally as a plain-text file under ~/.claude/projects/. That is what makes rewinding, resuming and forking possible. Every new session starts with a fresh context window, without the history of earlier ones. What carries over is what is written down: CLAUDE.md and auto memory.

Resume with claude --continue or claude --resume: the same session, new messages appended.
Fork with --fork-session or /branch: the history is copied into a new session and the original is left alone.
Sessions are tied to the folder you started in. To run several in parallel, give each its own folder with git worktrees.

Handing work to a fresh session is its own skill: see handoff notes.

The context window

The context window holds your conversation, file contents, command output, CLAUDE.md, auto memory, loaded skills and system instructions. It fills as you work. Claude compacts it automatically, but detailed instructions from early in the conversation can be lost, so put rules that must last in CLAUDE.md. Run /context to see what is using the space, and /compact focus on the API changes to steer what is kept. Skills load on demand (only their descriptions are there at the start), and a subagent works in its own window and sends back a summary. More in what survives /compact and the quota guide.

The safety nets

Checkpoints. Before Claude edits a file, it snapshots it. Press Esc twice to rewind, or ask Claude to undo. Checkpoints are separate from git, cover file changes only, and cannot undo actions on remote systems such as databases, APIs or deployments. See undoing changes.

Permissions. A permission mode sets what Claude can do without asking. Shift+Tab cycles through modes such as manual (asks before edits and commands), accept edits, plan (explores and proposes without editing your source) and auto (a classifier blocks risky actions instead of asking). Which mode a session starts in depends on your version and plan. You can also allow specific commands, such as npm test, in your settings. See permission modes and a starter permissions file.

Working with it

It is a conversation. You do not need a perfect first prompt. Start with what you want and refine. If the first attempt is off, say what is wrong instead of starting over.
You can interrupt. Press Esc to stop immediately, or type a correction and press Enter while Claude works; it reads the message after its current tool calls and adjusts. See keyboard shortcuts.
Delegate, do not dictate. Give context and a goal ("checkout is broken for users with expired cards, the code is in src/payments/, please investigate and fix") instead of listing files and commands.
Ask it for help. It can explain its own features. /init generates a starter CLAUDE.md, and /doctor checks your setup.

Where to go next

For the files Claude Code reads, see the .claude folder explained and which settings file wins. When something does not behave, try debugging your configuration. To change how it answers, see output styles and the status line. To use it from scripts, see running from a script. All of them are listed in the guides index.

This follows Anthropic's "How Claude Code works" documentation as we read it in October 2026. We are not affiliated with Anthropic. We wrote this from the documentation and have not tested every case. Features and defaults change between versions, and where this page and the documentation disagree, the documentation wins.

The free loop-stop skill gives long tasks a limit and a stop rule. If you want a second pair of eyes on your CLAUDE.md and settings, the Tune-Up Kit is a checklist for exactly that.