1# How Claude Code works
2
3> Understand the agentic loop, built-in tools, and how Claude Code interacts with your project.
4
5Claude 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.
6
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](/en/common-workflows). For extensibility features like skills, MCP, and hooks, see [Extend Claude Code](/en/features-overview).
8
9## The agentic loop
10
11When you give Claude a task, it works through three phases: **gather context**, **take action**, and **verify results**. These phases blend together. Claude uses tools throughout, whether searching files to understand your code, editing to make changes, or running tests to check its work.
12
13<img src="https://mintcdn.com/claude-code/ELkJZG54dIaeldDC/images/agentic-loop.svg?fit=max&auto=format&n=ELkJZG54dIaeldDC&q=85&s=e30acfc80d6ff01ec877dd19c7af58b2" alt="The agentic loop: Your prompt leads to Claude gathering context, taking action, verifying results, and repeating until task complete. You can interrupt at any point." data-og-width="720" width="720" data-og-height="280" height="280" data-path="images/agentic-loop.svg" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/claude-code/ELkJZG54dIaeldDC/images/agentic-loop.svg?w=280&fit=max&auto=format&n=ELkJZG54dIaeldDC&q=85&s=8620f6ebce761a1e8bbf7f0a0255cc15 280w, https://mintcdn.com/claude-code/ELkJZG54dIaeldDC/images/agentic-loop.svg?w=560&fit=max&auto=format&n=ELkJZG54dIaeldDC&q=85&s=7b46b5ff4454aa4a03725eee625b39a0 560w, https://mintcdn.com/claude-code/ELkJZG54dIaeldDC/images/agentic-loop.svg?w=840&fit=max&auto=format&n=ELkJZG54dIaeldDC&q=85&s=7fa0397bc37d147e3bf3bb6296c6477f 840w, https://mintcdn.com/claude-code/ELkJZG54dIaeldDC/images/agentic-loop.svg?w=1100&fit=max&auto=format&n=ELkJZG54dIaeldDC&q=85&s=73b2a7040c4c93821c4d5bbee9f4a2d4 1100w, https://mintcdn.com/claude-code/ELkJZG54dIaeldDC/images/agentic-loop.svg?w=1650&fit=max&auto=format&n=ELkJZG54dIaeldDC&q=85&s=17703cbeb6f59b40a00ab24f56d5f8f9 1650w, https://mintcdn.com/claude-code/ELkJZG54dIaeldDC/images/agentic-loop.svg?w=2500&fit=max&auto=format&n=ELkJZG54dIaeldDC&q=85&s=20dedb60b95d45a1bd60a0cccaf3e1ff 2500w" />
14
15The loop adapts to what you ask. A question about your codebase might only need context gathering. A bug fix cycles through all three phases repeatedly. A refactor might involve extensive verification. Claude decides what each step requires based on what it learned from the previous step, chaining dozens of actions together and course-correcting along the way.
16
17You're part of this loop too. You can interrupt at any point to steer Claude in a different direction, provide additional context, or ask it to try a different approach. Claude works autonomously but stays responsive to your input.
18
19The agentic loop is powered by two components: [models](#models) that reason and [tools](#tools) that act. Claude Code serves as the **agentic harness** around Claude: it provides the tools, context management, and execution environment that turn a language model into a capable coding agent.
20
21### Models
22
23Claude 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.
24
25[Multiple models](/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>`.
26
27When this guide says "Claude chooses" or "Claude decides," it's the model doing the reasoning.
28
29### Tools
30
31Tools are what make Claude Code agentic. Without tools, Claude can only respond with text. With tools, Claude can act: read your code, edit files, run commands, search the web, and interact with external services. Each tool use returns information that feeds back into the loop, informing Claude's next decision.
32
33The built-in tools generally fall into four categories, each representing a different kind of agency.
34
35| Category | What Claude can do |
36| ------------------- | ------------------------------------------------------------------- |
37| **File operations** | Read files, edit code, create new files, rename and reorganize |
38| **Search** | Find files by pattern, search content with regex, explore codebases |
39| **Execution** | Run shell commands, start servers, run tests, use git |
40| **Web** | Search the web, fetch documentation, look up error messages |
41
42These are the primary capabilities. Claude also has tools for spawning subagents, asking you questions, and other orchestration tasks. See [Tools available to Claude](/en/settings#tools-available-to-claude) for the complete list.
43
44Claude 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:
45
461. Run the test suite to see what's failing
472. Read the error output
483. Search for the relevant source files
494. Read those files to understand the code
505. Edit the files to fix the issue
516. Run the tests again to verify
52
53Each tool use gives Claude new information that informs the next step. This is the agentic loop in action.
54
55**Extending the base capabilities:** The built-in tools are the foundation. You can extend what Claude knows with [skills](/en/skills), connect to external services with [MCP](/en/mcp), automate workflows with [hooks](/en/hooks), and offload tasks to [subagents](/en/sub-agents). These extensions form a layer on top of the core agentic loop. See [Extend Claude Code](/en/features-overview) for guidance on choosing the right extension for your needs.
56
57## What Claude can access
58
59This guide focuses on the terminal. Claude Code also runs in [VS Code, JetBrains IDEs, and other environments](/en/ide-integrations).
60
61When you run `claude` in a directory, Claude Code gains access to:
62
63* **Your project.** Files in your directory and subdirectories, plus files elsewhere with your permission.
64* **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.
65* **Your git state.** Current branch, uncommitted changes, and recent commit history.
66* **Your [CLAUDE.md](/en/memory).** A markdown file where you store project-specific instructions, conventions, and context that Claude should know every session.
67* **Extensions you configure.** [MCP servers](/en/mcp) for external services, [skills](/en/skills) for workflows, [subagents](/en/sub-agents) for delegated work, and [Claude in Chrome](/en/chrome) for browser interaction.
68
69Because 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.
70
71## Work with sessions
72
73Claude Code saves your conversation locally as you work. Each message, tool use, and result is stored, 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.
74
75**Sessions are ephemeral.** Unlike claude.ai, Claude Code has no persistent memory between sessions. Each new session starts fresh. Claude doesn't "learn" your preferences over time or remember what you worked on last week. If you want Claude to know something across sessions, put it in your [CLAUDE.md](/en/memory).
76
77### Work across branches
78
79Each Claude Code conversation is a session tied to your current directory. When you resume, you only see sessions from that directory.
80
81Claude 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.
82
83Since sessions are tied to directories, you can run parallel Claude sessions by using [git worktrees](/en/common-workflows#run-parallel-claude-code-sessions-with-git-worktrees), which create separate directories for individual branches.
84
85### Resume or fork sessions
86
87When you resume a session with `claude --continue` or `claude --resume`, you pick up where you left off using the same session ID. New messages append to the existing conversation. Your full conversation history is restored, but session-scoped permissions are not. You'll need to re-approve those.
88
89<img src="https://mintcdn.com/claude-code/ELkJZG54dIaeldDC/images/session-continuity.svg?fit=max&auto=format&n=ELkJZG54dIaeldDC&q=85&s=f671b603cc856119c95475b9084ebfef" alt="Session continuity: resume continues the same session, fork creates a new branch with a new ID." data-og-width="560" width="560" data-og-height="280" height="280" data-path="images/session-continuity.svg" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/claude-code/ELkJZG54dIaeldDC/images/session-continuity.svg?w=280&fit=max&auto=format&n=ELkJZG54dIaeldDC&q=85&s=bddf1f33d419a27d7427acdf06058804 280w, https://mintcdn.com/claude-code/ELkJZG54dIaeldDC/images/session-continuity.svg?w=560&fit=max&auto=format&n=ELkJZG54dIaeldDC&q=85&s=417478eb9b86003b8eebaac058a8618a 560w, https://mintcdn.com/claude-code/ELkJZG54dIaeldDC/images/session-continuity.svg?w=840&fit=max&auto=format&n=ELkJZG54dIaeldDC&q=85&s=1d89d26e2c0487f067d187c3fa5f7170 840w, https://mintcdn.com/claude-code/ELkJZG54dIaeldDC/images/session-continuity.svg?w=1100&fit=max&auto=format&n=ELkJZG54dIaeldDC&q=85&s=8ea739a1f7860e4edbbcf74d444e37b2 1100w, https://mintcdn.com/claude-code/ELkJZG54dIaeldDC/images/session-continuity.svg?w=1650&fit=max&auto=format&n=ELkJZG54dIaeldDC&q=85&s=9cb5095d6a8920f04c3b78d31a69c809 1650w, https://mintcdn.com/claude-code/ELkJZG54dIaeldDC/images/session-continuity.svg?w=2500&fit=max&auto=format&n=ELkJZG54dIaeldDC&q=85&s=d67e1744e4878813d20c6c3f39d9459d 2500w" />
90
91To branch off and try a different approach without affecting the original session, use the `--fork-session` flag:
92
93```bash theme={null}
94claude --continue --fork-session
95```
96
97This creates a new session ID while preserving the conversation history up to that point. The original session remains unchanged. Like resume, forked sessions don't inherit session-scoped permissions.
98
99**Same session in multiple terminals**: If you resume the same session in multiple terminals, both terminals write to the same session file. Messages from both get interleaved, like two people writing in the same notebook. Nothing corrupts, but the conversation becomes jumbled. Each terminal only sees its own messages during the session, but if you resume that session later, you'll see everything interleaved. For parallel work from the same starting point, use `--fork-session` to give each terminal its own clean session.
100
101### The context window
102
103Claude's context window holds your conversation history, file contents, command outputs, [CLAUDE.md](/en/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.
104
105#### When context fills up
106
107Claude Code manages context automatically as you approach the limit. It clears older tool outputs first, then summarizes the conversation if needed. Your requests and key code snippets are preserved; detailed instructions from early in the conversation may be lost. Put persistent rules in CLAUDE.md rather than relying on conversation history.
108
109To 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`).
110
111Run `/context` to see what's using space. MCP servers add tool definitions to every request, so a few servers can consume significant context before you start working. Run `/mcp` to check per-server costs.
112
113#### Manage context with skills and subagents
114
115Beyond compaction, you can use other features to control what loads into context.
116
117[Skills](/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.
118
119[Subagents](/en/sub-agents) get their own fresh context, completely separate from your main conversation. Their work doesn't bloat your context. When done, they return a summary. This isolation is why subagents help with long sessions.
120
121See [context costs](/en/features-overview#understand-context-costs) for what each feature costs, and [reduce token usage](/en/costs#reduce-token-usage) for tips on managing context.
122
123## Stay safe with checkpoints and permissions
124
125Claude has two safety mechanisms: checkpoints let you undo file changes, and permissions control what Claude can do without asking.
126
127### Undo changes with checkpoints
128
129**Every file edit is reversible.** Before Claude edits any file, it snapshots the current contents. If something goes wrong, press `Esc` twice to rewind to a previous state, or ask Claude to undo.
130
131Checkpoints are local to your session, separate from git. They only cover file changes. Actions that affect remote systems (databases, APIs, deployments) can't be checkpointed, which is why Claude asks before running commands with external side effects.
132
133### Control what Claude can do
134
135Press `Shift+Tab` to cycle through permission modes:
136
137* **Default**: Claude asks before file edits and shell commands
138* **Auto-accept edits**: Claude edits files without asking, still asks for commands
139* **Plan mode**: Claude uses read-only tools only, creating a plan you can approve before execution
140
141You 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](/en/iam) for details.
142
143***
144
145## Work effectively with Claude Code
146
147These tips help you get better results from Claude Code.
148
149### Ask Claude Code for help
150
151Claude Code can teach you how to use it. Ask questions like "how do I set up hooks?" or "what's the best way to structure my CLAUDE.md?" and Claude will explain.
152
153Built-in commands also guide you through setup:
154
155* `/init` walks you through creating a CLAUDE.md for your project
156* `/agents` helps you configure custom subagents
157* `/doctor` diagnoses common issues with your installation
158
159### It's a conversation
160
161Claude Code is conversational. You don't need perfect prompts. Start with what you want, then refine:
162
163```
164> Fix the login bug
165
166[Claude investigates, tries something]
167
168> That's not quite right. The issue is in the session handling.
169
170[Claude adjusts approach]
171```
172
173When the first attempt isn't right, you don't start over. You iterate.
174
175#### Interrupt and steer
176
177You can interrupt Claude at any point. If it's going down the wrong path, just type your correction and press Enter. Claude will stop what it's doing and adjust its approach based on your input. You don't have to wait for it to finish or start over.
178
179### Be specific upfront
180
181The more precise your initial prompt, the fewer corrections you'll need. Reference specific files, mention constraints, and point to example patterns.
182
183```
184> The checkout flow is broken for users with expired cards.
185> Check src/payments/ for the issue, especially token refresh.
186> Write a failing test first, then fix it.
187```
188
189Vague prompts like "fix the login bug" work, but you'll spend more time steering. Specific prompts like the above often succeed on the first attempt.
190
191### Give Claude something to verify against
192
193Claude performs better when it can check its own work. Include test cases, paste screenshots of expected UI, or define the output you want.
194
195```
196> Implement validateEmail. Test cases: 'user@example.com' → true,
197> 'invalid' → false, 'user@.com' → false. Run the tests after.
198```
199
200For visual work, paste a screenshot of the design and ask Claude to compare its implementation against it.
201
202### Explore before implementing
203
204For complex problems, separate research from coding. Use plan mode (`Shift+Tab` twice) to analyze the codebase first:
205
206```
207> Read src/auth/ and understand how we handle sessions.
208> Then create a plan for adding OAuth support.
209```
210
211Review the plan, refine it through conversation, then let Claude implement. This two-phase approach produces better results than jumping straight to code.
212
213### Delegate, don't dictate
214
215Think of delegating to a capable colleague. Give context and direction, then trust Claude to figure out the details:
216
217```
218> The checkout flow is broken for users with expired cards.
219> The relevant code is in src/payments/. Can you investigate and fix it?
220```
221
222You don't need to specify which files to read or what commands to run. Claude figures that out.
223
224## What's next
225
226<CardGroup cols={2}>
227 <Card title="Extend with features" icon="puzzle-piece" href="/en/features-overview">
228 Add Skills, MCP connections, and custom commands
229 </Card>
230
231 <Card title="Common workflows" icon="graduation-cap" href="/en/common-workflows">
232 Step-by-step guides for typical tasks
233 </Card>
234</CardGroup>
235
236
237---
238
239> To find navigation and other pages in this documentation, fetch the llms.txt file at: https://code.claude.com/docs/llms.txt
