How Claude Code works
Understand the agentic loop, built-in tools, and how Claude Code interacts with your project.
Claude 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.
The agentic loop
When 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.
The 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.
You'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.
The agentic loop is powered by two components: models that reason and 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.
Models
Claude 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.
Multiple models 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>.
When this guide says "Claude chooses" or "Claude decides," it's the model doing the reasoning.
Tools
Tools 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.
The built-in tools generally fall into five categories:
| Category | What Claude can do |
|---|---|
| File operations | Read files, edit code, create new files, rename and reorganize |
| Search | Find files by pattern, search content with regex, explore codebases |
| Execution | Run shell commands, start servers, run tests, use git |
| Web | Search the web, fetch documentation, look up error messages |
| Code intelligence | See type errors and warnings after edits, jump to definitions, find references (requires code intelligence plugins) |
Claude 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 run the test suite, read errors, search source files, edit to fix the issue, and run tests again to verify.
You can extend the base capabilities with skills, MCP, hooks, and subagents on top of the core agentic loop.
What Claude can access
When you run claude in a directory, Claude Code gains access to:
- Your project — files in your directory and subdirectories, plus files elsewhere with your permission
- Your terminal — any command you could run: build tools, git, package managers, system utilities, scripts
- Your git state — current branch, uncommitted changes, and recent commit history
- Your CLAUDE.md — project-specific instructions, conventions, and context loaded every session
- Auto memory — learnings Claude saves automatically; the first 200 lines or 25KB of
MEMORY.mdload at session start - Extensions you configure — MCP servers, skills, subagents, and Claude in Chrome for browser interaction
Because Claude sees your whole project, it can work across it: search, read multiple files, make coordinated edits, run tests, and commit when you ask.
Environments and interfaces
Execution environments
| Environment | Where code runs | Use case |
|---|---|---|
| Local | Your machine | Default. Full access to your files, tools, and environment |
| Cloud | Anthropic-managed VMs | Offload tasks, work on repos you don't have locally |
| Remote Control | Your machine, controlled from a browser | Use the web UI while keeping everything local |
The agentic loop, tools, and capabilities are the same everywhere; what changes is where code executes and how you interact.
Work with sessions
Claude Code saves your conversation locally. Each message, tool use, and result is written under ~/.claude/projects/. Before code changes, Claude snapshots affected files so you can revert.
Sessions are independent. Each new session starts with a fresh context window. Claude can persist learnings with auto memory; add your own persistent instructions in CLAUDE.md.
Resume with claude --continue or claude --resume. Fork with --fork-session or /branch to copy history into a new session ID.
The context window
Claude's context window holds conversation history, file contents, command outputs, CLAUDE.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.
When context fills up, Claude clears older tool outputs first, then summarizes if needed. Put persistent rules in CLAUDE.md rather than relying on conversation history. Run /compact with a focus (e.g. /compact focus on the API changes) to control what survives compaction.
Use skills with disable-model-invocation: true for manual skills, and subagents for long investigations so research does not bloat your main thread.
Stay safe with checkpoints and permissions
Undo changes with checkpoints
Every file edit is reversible. Before Claude edits any file, it snapshots the current contents. Press Esc twice to rewind, or ask Claude to undo. Checkpoints are local to your session and only cover file changes.
Control what Claude can do
Press Shift+Tab to cycle permission modes:
- Default — asks before file edits and shell commands
- Auto-accept edits — edits files and common filesystem commands like
mkdirandmvwithout asking - Plan mode — read-only tools only; create a plan before execution
- Auto mode — evaluates actions with background safety checks (research preview)
Allow specific commands in .claude/settings.json so Claude does not ask each time. See Permissions and Permission modes.
Work effectively with Claude Code
Ask Claude Code for help
Ask questions like "how do I set up hooks?" or "what's the best way to structure my CLAUDE.md?" Built-in commands: /init, /agents, /doctor.
It's a conversation
Start with what you want, then refine. When the first attempt is not right, iterate — you do not need to start over.
Interrupt and steer: Press Esc to stop immediately. Type a correction and press Enter to send it without stopping the running tool; Claude reads it when the current action completes.
Be specific upfront
Reference specific files, mention constraints, and point to example patterns:
The checkout flow is broken for users with expired cards.
Check src/payments/ for the issue, especially token refresh.
Write a failing test first, then fix it.Give Claude something to verify against
Include test cases, screenshots of expected UI, or defined output. For visual work, paste a screenshot and ask Claude to compare its implementation.
Explore before implementing
Use plan mode (Shift+Tab twice) to analyze the codebase first, review the plan, then implement.
Delegate, don't dictate
Give context and direction; trust Claude to figure out files and commands:
The checkout flow is broken for users with expired cards.
The relevant code is in src/payments/. Can you investigate and fix it?