How Does Claude Code Work? The Agent Loop Explained
How does Claude Code work? The agent loop, its tools, what it can access, how the context window and compaction work, and where permissions and CLAUDE.md fit.
Josh Pocock8 min read
AI Coding
How Claude Code works
Stride AI Academy
Claude Code works by running a loop. You give it a task, and a Claude model gathers context, takes action, checks the result and repeats until the task is done, using tools to read files, edit code and run commands in your terminal. Claude Code itself is the layer around the model: it supplies the tools, manages what the model sees, and asks your permission before risky actions.
This guide explains each part in plain terms: the loop, the tools, what Claude can access, how the context window fills and gets compacted, and where checkpoints, permissions and CLAUDE.md fit. Everything here was checked against Anthropic's docs on how Claude Code works, memory and permission modes, and the Anthropic engineering posts on context engineering and sandboxing, on November 22, 2026.
The agentic loop
Anthropic's docs describe three phases: gather context, take action and verify results. They blend together. A question about your code might only need the first phase. A bug fix cycles through all three many times.
The docs give this example. When you say "fix the failing tests," Claude might:
- Run the test suite to see what's failing
- Read the error output
- Search for the relevant source files
- Read those files
- Edit them to fix the issue
- Run the tests again to check
Each step returns information that decides the next one. That's why Claude Code can chain dozens of actions without you spelling them out. You stay in the loop too: you can interrupt, add context or change direction at any point.
The docs call the layer around the model the "agentic harness." The model does the reasoning. The harness gives it tools and decides what goes into its context.
The two parts: models and tools
Models. Claude Code runs on Claude models. The docs say Sonnet handles most coding tasks well and Opus gives stronger reasoning for complex architecture decisions. You switch with /model in a session or start with claude --model <name>.
Tools. Without tools, a model can only reply with text. The docs group Claude Code's built-in tools into five kinds:
| Tool category | What Claude can do |
|---|---|
| File operations | Read, edit, create and rename files |
| Search | Find files by pattern and search contents with regex |
| Execution | Run shell commands, start servers, run tests, use git |
| Web | Search the web and fetch documentation |
| Code intelligence | See type errors and jump to definitions, with code intelligence plugins |
There are also tools for spawning subagents and asking you questions. On top of these, you can add skills, MCP servers, hooks and subagents. The docs describe those as a layer on top of the core loop, not a different engine.
What Claude Code can access
When you run claude in a folder, the docs list what it can reach:
- Your project: files in that folder and below, plus others with your permission
- Your terminal: any command you could run yourself
- Your git state: branch, uncommitted changes and recent commits
- Your CLAUDE.md: project instructions loaded every session, or an AGENTS.md in its place
- Auto memory: notes Claude saves as it works, with the first 200 lines or 25KB of
MEMORY.mdloaded at start - Extensions you set up: MCP servers, skills, subagents and Claude in Chrome
Because it sees the whole project, Claude can make coordinated edits across many files. That's the main difference from an inline assistant that only sees the file you have open.
How Claude finds the right files
Claude Code doesn't build an index of your codebase up front. Anthropic's context engineering post says it uses a hybrid approach: some context loads at the start, such as CLAUDE.md files, and the rest is fetched when needed with tools like glob and grep. It keeps lightweight references, like file paths, and pulls in full contents only when a step needs them.
The post's point is that this avoids a stale index. Claude searches the code as it is right now, the same way you would.
The context window and compaction
Everything the model sees in a session sits in its context window. The docs list what fills it: your conversation, file contents, command output, CLAUDE.md, auto memory, loaded skills and system instructions.
As it fills, Claude Code compacts automatically. It summarizes the conversation, keeping your requests and key code. The docs warn that detailed instructions from early in a session can be lost in that summary, so persistent rules belong in CLAUDE.md. You can also steer it:
/compact focus on the API changesRun /context to see what's using space. A few features help keep it lean:
- Skills load on demand. Claude sees their descriptions at start, and the full text only when one is used.
- MCP tools are deferred by default, so only tool names load until Claude uses one.
- Subagents work in their own context window and send back a summary, so their tool calls stay out of yours.
Our guide to Claude Code context management covers the habits that keep sessions efficient, and the subagents tutorial shows how to set one up.
Where CLAUDE.md fits
Each session starts with a fresh context window. Nothing from yesterday's conversation carries over on its own. CLAUDE.md and auto memory are how knowledge survives between sessions:
- CLAUDE.md is a file you write. Claude Code loads it from your project folder and every folder above it, plus your personal
~/.claude/CLAUDE.md, at the start of every session. - Auto memory is written by Claude, from your corrections and preferences.
The memory docs recommend keeping each CLAUDE.md under 200 lines, because longer files use more context and get followed less closely. Run /init to generate a starter file. For real examples, see CLAUDE.md file examples.
Sessions, checkpoints and undo
Claude Code saves each conversation as a local file under ~/.claude/projects/. That's what lets you resume with claude --continue or claude --resume, or fork a session into a new one with --fork-session.
Before Claude edits a file, it snapshots the current contents. Press Esc twice, or run /rewind, to roll back the code, the conversation or both. The docs note two limits: checkpoints only cover file changes, and anything that touches a remote system, such as a database, an API or a deployment, can't be undone this way.
Sessions are tied to the folder you started in. To run several at once without their edits colliding, the docs suggest git worktrees, covered in our Claude Code worktrees guide.
Permissions: what Claude can do without asking
The second safety layer is the permission mode. Press Shift+Tab to cycle through them:
| Mode | What happens |
|---|---|
| Auto | A classifier reviews actions in the background and blocks risky ones |
| Manual | Claude asks before file edits and shell commands |
| Accept edits | Claude edits files and runs common filesystem commands without asking |
| Plan | Claude explores and proposes a plan without editing your source |
The docs say auto mode is the starting mode for interactive terminal and VS Code sessions on Claude Code v2.1.283 or later. You can also allow specific trusted commands, like npm test, in .claude/settings.json. Our Claude Code permissions guide walks through the rules.
Sandboxing is an extra boundary. Anthropic's sandboxing post describes two parts: filesystem isolation, which limits Claude to set folders, and network isolation, which limits it to approved servers. It says sandboxing cut permission prompts by 84% in Anthropic's internal use. The post says it's built on Linux bubblewrap and macOS seatbelt, and the setup docs note it isn't supported on native Windows, only in WSL 2.
Same loop, different places
The loop, tools and features are the same wherever you use Claude Code. The docs list three places code can run: your own machine, cloud machines run by Anthropic or your organization, and Remote Control, where you drive a local session from a browser. You can reach it from the terminal, the desktop app, IDE extensions, claude.ai/code, Slack and CI pipelines. Only the interface changes.
What this means for how you use it
Once you see the loop, a few habits make sense:
- Give it a way to check its work. A test, a build or a linter lets the verify phase close on its own.
- Describe the goal, not the steps. The docs suggest delegating like you would to a capable colleague, and letting Claude choose which files to read.
- Put lasting rules in CLAUDE.md. Conversation details can be compacted away.
- Interrupt early. Press
Escwhen it drifts, rather than letting a wrong approach run.
Our Claude Code guide covers setup and the features built on this loop.
Learn to build with Claude Code
The Stride AI Coding course teaches Claude Code and Codex for building client tools, written for non-programmers, with weekly live calls to review your builds. Many of the free guides cover Claude Code setups, and the Claude Code community is where members compare theirs.
FAQ
How does Claude Code work?
It runs an agentic loop. A Claude model gathers context, takes action and checks results, using tools to read files, edit code and run commands, and repeats until the task is done. Claude Code supplies the tools and manages what the model sees.
Does Claude Code index my whole codebase?
No. Anthropic's context engineering post says Claude Code loads some context at the start, like CLAUDE.md, and finds the rest on demand with search tools such as glob and grep.
Does Claude Code remember past sessions?
Each session starts with a fresh context window. Knowledge carries over through CLAUDE.md files you write and auto memory that Claude writes, and you can reopen an old conversation with claude --resume.
What happens when the context window fills up?
Claude Code compacts automatically by summarizing the conversation. Early detailed instructions can be lost, so keep lasting rules in CLAUDE.md and run /context to see what's using space.
Can I undo what Claude Code changed?
Yes, for file edits. Press Esc twice or run /rewind to roll back to an earlier checkpoint. Changes to remote systems, such as databases or deployments, can't be undone this way.
What model does Claude Code use?
It uses Claude models. The docs say Sonnet handles most coding tasks and Opus suits complex reasoning. Switch with /model during a session.