How Claude Code works changedhow-claude-code-works
Nearest release: v2.1.293, published 9 hours after upstream edited the page. Shown because the two are within 24 hours of each other. Nothing here says the release caused the edit.
Upstream edited this page at 7 Oct 2026 07:30 UTC, give or take a minute or two: the time comes from Anthropic’s own sitemap rather than from a commit. This site recorded the change at 22 Oct 2026 18:07 UTC.
Upstream edited
Recorded here
Lines+36added
Lines−36removed
From line
4
where the diff opens
First seen
14 Aug 2026
this site's first read of the page
Recorded edits19to this page, all time
The whole hunk
from line 4, old and new numbered
/
from line 4
44
55Claude Code is an agentic assistant that runs in your terminal. While it excels at coding, it can help with anything you can do from the command line: writing docs, running builds, searching files, researching topics, and more.
66
7This guide covers the core architecture, built-in capabilities, and [tips for working effectively](#work-effectively-with-claude-code). For step-by-step walkthroughs, see [Common workflows](/docs/en/common-workflows). For extensibility features like skills, MCP, and hooks, see [Extend Claude Code](/docs/en/features-overview).
7This guide covers the core architecture, built-in capabilities, and [tips for working effectively](#work-effectively-with-claude-code). For step-by-step walkthroughs, see [Common workflows](/docs/en/common-workflows.md). For extensibility features like skills, MCP, and hooks, see [Extend Claude Code](/docs/en/features-overview.md).
88
99## The agentic loop
1010
from line 22
2222
2323Claude Code uses Claude models to understand your code and reason about tasks. Claude can read code in any language, understand how components connect, and figure out what needs to change to accomplish your goal. For complex tasks, it breaks work into steps, executes them, and adjusts based on what it learns.
2424
25[Multiple models](/docs/en/model-config) are available with different tradeoffs. Sonnet handles most coding tasks well. Opus provides stronger reasoning for complex architectural decisions. Switch with `/model` during a session or start with `claude --model <name>`.
25[Multiple models](/docs/en/model-config.md) are available with different tradeoffs. Sonnet handles most coding tasks well. Opus provides stronger reasoning for complex architectural decisions. Switch with `/model` during a session or start with `claude --model <name>`.
2626
2727When this guide says "Claude chooses" or "Claude decides," it's the model doing the reasoning.
2828
from line 38
3838| **Search** | Find files by pattern, search content with regex, explore codebases |
3939| **Execution** | Run shell commands, start servers, run tests, use git |
4040| **Web** | Search the web, fetch documentation, look up error messages |
41| **Code intelligence** | See type errors and warnings after edits, jump to definitions, find references (requires [code intelligence plugins](/docs/en/plugins/code-intelligence)) |
41| **Code intelligence** | See type errors and warnings after edits, jump to definitions, find references (requires [code intelligence plugins](/docs/en/plugins/code-intelligence.md)) |
4242
43These are the primary capabilities. Claude also has tools for spawning subagents, asking you questions, and other orchestration tasks. See [Tools available to Claude](/docs/en/tools-reference) for the complete list.
43These are the primary capabilities. Claude also has tools for spawning subagents, asking you questions, and other orchestration tasks. See [Tools available to Claude](/docs/en/tools-reference.md) for the complete list.
4444
4545Claude chooses which tools to use based on your prompt and what it learns along the way. When you say "fix the failing tests," Claude might:
4646
from line 53
5353
5454Each tool use gives Claude new information that informs the next step. This is the agentic loop in action.
5555
56**Extending the base capabilities:** The built-in tools are the foundation. You can extend what Claude knows with [skills](/docs/en/skills), connect to external services with [MCP](/docs/en/mcp), automate workflows with [hooks](/docs/en/hooks), and offload tasks to [subagents](/docs/en/sub-agents). These extensions form a layer on top of the core agentic loop. See [Extend Claude Code](/docs/en/features-overview) for guidance on choosing the right extension for your needs.
56**Extending the base capabilities:** The built-in tools are the foundation. You can extend what Claude knows with [skills](/docs/en/skills.md), connect to external services with [MCP](/docs/en/mcp.md), automate workflows with [hooks](/docs/en/hooks.md), and offload tasks to [subagents](/docs/en/sub-agents.md). These extensions form a layer on top of the core agentic loop. See [Extend Claude Code](/docs/en/features-overview.md) for guidance on choosing the right extension for your needs.
5757
5858## What Claude can access
5959
from line 62
6262* **Your project.** Files in your directory and subdirectories, plus files elsewhere with your permission.
6363* **Your terminal.** Any command you could run: build tools, git, package managers, system utilities, scripts. If you can do it from the command line, Claude can too.
6464* **Your git state.** Current branch, uncommitted changes, and recent commit history.
65* **Your [CLAUDE.md](/docs/en/memory).** A markdown file where you store project-specific instructions, conventions, and context that Claude should know every session. If your repository has an AGENTS.md for other coding agents, Claude [can read that](/docs/en/memory#agents-md) in place of a CLAUDE.md.
66* **[Auto memory](/docs/en/memory#auto-memory).** Learnings Claude saves automatically as you work, like your preferences. The first 200 lines or 25KB of MEMORY.md, whichever comes first, load at the start of each session.
67* **Extensions you configure.** [MCP servers](/docs/en/mcp) for external services, [skills](/docs/en/skills) for workflows, [subagents](/docs/en/sub-agents) for delegated work, and [Claude in Chrome](/docs/en/chrome) for browser interaction.
65* **Your [CLAUDE.md](/docs/en/memory.md).** A markdown file where you store project-specific instructions, conventions, and context that Claude should know every session. If your repository has an AGENTS.md for other coding agents, Claude [can read that](/docs/en/memory.md#agents-md) in place of a CLAUDE.md.
66* **[Auto memory](/docs/en/memory.md#auto-memory).** Learnings Claude saves automatically as you work, like your preferences. The first 200 lines or 25KB of MEMORY.md, whichever comes first, load at the start of each session.
67* **Extensions you configure.** [MCP servers](/docs/en/mcp.md) for external services, [skills](/docs/en/skills.md) for workflows, [subagents](/docs/en/sub-agents.md) for delegated work, and [Claude in Chrome](/docs/en/chrome.md) for browser interaction.
6868
6969Because Claude sees your whole project, it can work across it. When you ask Claude to "fix the authentication bug," it searches for relevant files, reads multiple files to understand context, makes coordinated edits across them, runs tests to verify the fix, and commits the changes if you ask. This is different from inline code assistants that only see the current file.
7070
from line 84
8484
8585### Interfaces
8686
87You can access Claude Code through the terminal, the [desktop app](/docs/en/desktop), [IDE extensions](/docs/en/vs-code), [claude.ai/code](https://claude.ai/code), [Remote Control](/docs/en/remote-control), [Slack](/docs/en/slack), and [CI/CD pipelines](/docs/en/github-actions). The interface determines how you see and interact with Claude, but the underlying agentic loop is identical. See [Use Claude Code everywhere](/docs/en/overview#use-claude-code-everywhere) for the full list.
87You can access Claude Code through the terminal, the [desktop app](/docs/en/desktop.md), [IDE extensions](/docs/en/vs-code.md), [claude.ai/code](https://claude.ai/code), [Remote Control](/docs/en/remote-control.md), [Slack](/docs/en/slack.md), and [CI/CD pipelines](/docs/en/github-actions.md). The interface determines how you see and interact with Claude, but the underlying agentic loop is identical. See [Use Claude Code everywhere](/docs/en/overview.md#use-claude-code-everywhere) for the full list.
8888
8989## Work with sessions
9090
9191Claude Code saves your conversation locally as you work. Each message, tool use, and result is written to a plaintext JSONL file under `~/.claude/projects/`, which enables [rewinding](#undo-changes-with-checkpoints), [resuming, and forking](#resume-or-fork-sessions) sessions. Before Claude makes code changes, it also snapshots the affected files so you can revert if needed. For paths, retention, and how to clear this data, see [application data in `~/.claude`](/docs/en/claude-directory#application-data).
9292
93**Sessions are independent.** Each new session starts with a fresh context window, without the conversation history from previous sessions. Claude can persist learnings across sessions using [auto memory](/docs/en/memory#auto-memory), and you can add your own persistent instructions in [CLAUDE.md](/docs/en/memory).
93**Sessions are independent.** Each new session starts with a fresh context window, without the conversation history from previous sessions. Claude can persist learnings across sessions using [auto memory](/docs/en/memory.md#auto-memory), and you can add your own persistent instructions in [CLAUDE.md](/docs/en/memory.md).
9494
9595### Work across branches
9696
97Each Claude Code conversation is a session tied to your current directory. The `/resume` picker shows sessions from the current worktree by default, with keyboard shortcuts to widen the list to other worktrees or projects. See [Manage sessions](/docs/en/sessions#use-the-session-picker) for the full list of picker shortcuts and how name resolution works.
97Each Claude Code conversation is a session tied to your current directory. The `/resume` picker shows sessions from the current worktree by default, with keyboard shortcuts to widen the list to other worktrees or projects. See [Manage sessions](/docs/en/sessions.md#use-the-session-picker) for the full list of picker shortcuts and how name resolution works.
9898
9999Claude sees your current branch's files. When you switch branches, Claude sees the new branch's files, but your conversation history stays the same. Claude remembers what you discussed even after switching.
100100
101Since sessions are tied to directories, you can run parallel Claude sessions by using [git worktrees](/docs/en/worktrees), which create separate directories for individual branches.
101Since sessions are tied to directories, you can run parallel Claude sessions by using [git worktrees](/docs/en/worktrees.md), which create separate directories for individual branches.
102102
103103### Resume or fork sessions
104104
from line 106
106106
107107
108108
109For the resume flags, the `/resume` picker, naming, and what happens when the same session is open in two terminals, see [Manage sessions](/docs/en/sessions).
109For the resume flags, the `/resume` picker, naming, and what happens when the same session is open in two terminals, see [Manage sessions](/docs/en/sessions.md).
110110
111111### The context window
112112
113Claude's context window holds your conversation history, file contents, command outputs, [CLAUDE.md](/docs/en/memory), [auto memory](/docs/en/memory#auto-memory), loaded skills, and system instructions. As you work, context fills up. Claude compacts automatically, but instructions from early in the conversation can get lost. Put persistent rules in CLAUDE.md, and run `/context` to see what's using space.
113Claude's context window holds your conversation history, file contents, command outputs, [CLAUDE.md](/docs/en/memory.md), [auto memory](/docs/en/memory.md#auto-memory), loaded skills, and system instructions. As you work, context fills up. Claude compacts automatically, but instructions from early in the conversation can get lost. Put persistent rules in CLAUDE.md, and run `/context` to see what's using space.
114114
115For an interactive walkthrough of what loads and when, see [Explore the context window](/docs/en/context-window).
115For an interactive walkthrough of what loads and when, see [Explore the context window](/docs/en/context-window.md).
116116
117117#### Context Claude Code adds on its own
118118
119If Claude follows a rule you didn't write, such as adding a `Co-Authored-By` trailer to a commit, the rule may have come from a [system reminder](/docs/en/glossary#system-reminder). As you work, Claude Code adds its own context to the conversation alongside your messages:
119If Claude follows a rule you didn't write, such as adding a `Co-Authored-By` trailer to a commit, the rule may have come from a [system reminder](/docs/en/glossary.md#system-reminder). As you work, Claude Code adds its own context to the conversation alongside your messages:
120120
121121* Your CLAUDE.md files
122* The instructions of your [output style](/docs/en/output-styles)
122* The instructions of your [output style](/docs/en/output-styles.md)
123123* A note when a file Claude read earlier changes on disk
124124* The commit and pull request attribution lines
125125
126To change or remove the attribution lines, set [`attribution`](/docs/en/settings-reference#attribution). To remove Claude Code's built-in commit and pull request instructions, set [`includeGitInstructions`](/docs/en/settings-reference#includegitinstructions) to `false`. For the other switches, see [Turn off the context your agent replaces](/docs/en/agent-sdk/modifying-system-prompts#turn-off-the-context-your-agent-replaces).
126To change or remove the attribution lines, set [`attribution`](/docs/en/settings-reference#attribution). To remove Claude Code's built-in commit and pull request instructions, set [`includeGitInstructions`](/docs/en/settings-reference#includegitinstructions) to `false`. For the other switches, see [Turn off the context your agent replaces](/docs/en/agent-sdk/modifying-system-prompts.md#turn-off-the-context-your-agent-replaces).
127127
128128#### When context fills up
129129
from line 131
131131
132132To control what's preserved during compaction, add a "Compact Instructions" section to CLAUDE.md or run `/compact` with a focus (like `/compact focus on the API changes`).
133133
134If a single file or tool output is so large that context refills immediately after each summary, Claude Code stops auto-compacting after a few attempts and shows an error instead of looping. See [Auto-compaction stops with a thrashing error](/docs/en/troubleshooting#auto-compaction-stops-with-a-thrashing-error) for recovery steps.
134If a single file or tool output is so large that context refills immediately after each summary, Claude Code stops auto-compacting after a few attempts and shows an error instead of looping. See [Auto-compaction stops with a thrashing error](/docs/en/troubleshooting.md#auto-compaction-stops-with-a-thrashing-error) for recovery steps.
135135
136Run `/context` to see what's using space. MCP tool definitions are deferred by default and loaded on demand via [tool search](/docs/en/mcp#scale-with-mcp-tool-search), so only tool names and server instructions consume context until Claude uses a specific tool.
136Run `/context` to see what's using space. MCP tool definitions are deferred by default and loaded on demand via [tool search](/docs/en/mcp.md#scale-with-mcp-tool-search), so only tool names and server instructions consume context until Claude uses a specific tool.
137137
138138#### Manage context with skills and subagents
139139
140140Beyond compaction, you can use other features to control what loads into context.
141141
142[Skills](/docs/en/skills) load on demand. Claude sees skill descriptions at session start, but the full content only loads when a skill is used. For skills you invoke manually, set `disable-model-invocation: true` to keep descriptions out of context until you need them. For skills you didn't write, use [`skillOverrides`](/docs/en/skills#override-skill-visibility-from-settings) to do the same from settings.
142[Skills](/docs/en/skills.md) load on demand. Claude sees skill descriptions at session start, but the full content only loads when a skill is used. For skills you invoke manually, set `disable-model-invocation: true` to keep descriptions out of context until you need them. For skills you didn't write, use [`skillOverrides`](/docs/en/skills#override-skill-visibility-from-settings) to do the same from settings.
143143
144[Subagents](/docs/en/sub-agents) work in their own context window. A subagent starts fresh unless it's a [fork](/docs/en/sub-agents#fork-the-current-conversation), which starts with a copy of your conversation so far. Either way, the subagent's tool calls stay out of your context, and Claude gets back a summary when the subagent finishes.
144[Subagents](/docs/en/sub-agents.md) work in their own context window. A subagent starts fresh unless it's a [fork](/docs/en/sub-agents.md#fork-the-current-conversation), which starts with a copy of your conversation so far. Either way, the subagent's tool calls stay out of your context, and Claude gets back a summary when the subagent finishes.
145145
146See [context costs](/docs/en/features-overview#understand-context-costs) for what each feature costs, and [reduce token usage](/docs/en/costs#reduce-token-usage) for tips on managing context.
146See [context costs](/docs/en/features-overview.md#understand-context-costs) for what each feature costs, and [reduce token usage](/docs/en/costs.md#reduce-token-usage) for tips on managing context.
147147
148148## Stay safe with checkpoints and permissions
149149
from line 153
153153
154154**File edits are reversible.** Before Claude edits a file, it snapshots the current contents. If something goes wrong, press `Esc` twice to rewind to a previous state, or ask Claude to undo.
155155
156Checkpoints are separate from git and remain available when you resume a conversation. They only cover file changes, and a restore [skips symlinked and hard-linked files](/docs/en/checkpointing#symlinked-and-hard-linked-paths-not-restored). Actions that affect remote systems (databases, APIs, deployments) can't be checkpointed. You control those with your permission mode and permission rules.
156Checkpoints are separate from git and remain available when you resume a conversation. They only cover file changes, and a restore [skips symlinked and hard-linked files](/docs/en/checkpointing.md#symlinked-and-hard-linked-paths-not-restored). Actions that affect remote systems (databases, APIs, deployments) can't be checkpointed. You control those with your permission mode and permission rules.
157157
158158### Control what Claude can do
159159
160160Choose a permission mode to set what Claude can do without asking you. Press `Shift+Tab` to cycle through the permission modes:
161161
162* **Auto**: a classifier reviews most actions in the background and blocks the risky ones instead of asking you. With Claude Code v2.1.283 or later, it's the [built-in starting permission mode](/docs/en/permission-modes#which-mode-a-session-starts-in) for interactive terminal and VS Code sessions, and on earlier versions only on Pro, Max, and Team plans
162* **Auto**: a classifier reviews most actions in the background and blocks the risky ones instead of asking you. With Claude Code v2.1.283 or later, it's the [built-in starting permission mode](/docs/en/permission-modes.md#which-mode-a-session-starts-in) for interactive terminal and VS Code sessions, and on earlier versions only on Pro, Max, and Team plans
163163* **Manual**: Claude asks before file edits and shell commands
164164* **Accept edits**: Claude edits files and runs common filesystem commands like `mkdir` and `mv` without asking, still asks for other commands
165165* **Plan**: Claude explores and proposes a plan without editing your source files
166166
167You can also allow specific commands in `.claude/settings.json` so Claude doesn't ask each time. This is useful for trusted commands like `npm test` or `git status`. Settings can be scoped from organization-wide policies down to personal preferences. See [Permissions](/docs/en/permissions) for details.
167You can also allow specific commands in `.claude/settings.json` so Claude doesn't ask each time. This is useful for trusted commands like `npm test` or `git status`. Settings can be scoped from organization-wide policies down to personal preferences. See [Permissions](/docs/en/permissions.md) for details.
168168
169169***
170170
171171## Work effectively with Claude Code
172172
173These tips help you get better results from Claude Code. For more on specific prompts, verification, and planning, see [Best practices](/docs/en/best-practices).
173These tips help you get better results from Claude Code. For more on specific prompts, verification, and planning, see [Best practices](/docs/en/best-practices.md).
174174
175175### Ask Claude Code for help
176176
from line 203
203203
204204You can redirect Claude at any point without starting over. Do either of these:
205205
206* **Press `Esc`** to stop Claude immediately. The running tool call is canceled and Claude waits for your next instruction. If you have messages queued, Claude Code [sends them next](/docs/en/interactive-mode#queue-messages-while-claude-works).
207* **Type a correction and press `Enter`** without stopping Claude. The message shows as queued in the conversation. If Claude is running tool calls, it reads the message as soon as those calls finish, within the same turn, and adjusts before its next step. [Queue messages while Claude works](/docs/en/interactive-mode#queue-messages-while-claude-works) covers when other queued entries are sent.
206* **Press `Esc`** to stop Claude immediately. The running tool call is canceled and Claude waits for your next instruction. If you have messages queued, Claude Code [sends them next](/docs/en/interactive-mode.md#queue-messages-while-claude-works).
207* **Type a correction and press `Enter`** without stopping Claude. The message shows as queued in the conversation. If Claude is running tool calls, it reads the message as soon as those calls finish, within the same turn, and adjusts before its next step. [Queue messages while Claude works](/docs/en/interactive-mode.md#queue-messages-while-claude-works) covers when other queued entries are sent.
208208
209209### Delegate, don't dictate
210210
from line 219
219219
220220## What's next
221221
222> **[Extend with features](/docs/en/features-overview)**
222> **[Extend with features](/docs/en/features-overview.md)**
223223>
224224> Add skills and MCP connections
225225
226> **[Common workflows](/docs/en/common-workflows)**
226> **[Common workflows](/docs/en/common-workflows.md)**
227227>
228228> Step-by-step guides for typical tasks
229229
No line in this hunk matches that.