Text of code.claude.com › docs › en › how-claude-code-works as Styx crawled it on Nov 20, 2026. The page may have changed since. Only its words are kept, without pictures or layout, and only the first part of a long page.

Open the live page

How Claude Code works - Claude Code Docs

Documentation Index Fetch the complete documentation index at: /docs/llms.txt Use this file to discover all available pages before exploring further. Skip to main content Assistant Responses are generated using AI and may contain mistakes. 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.

This guide covers the core architecture, built-in capabilities, and tips for working effectively . For step-by-step walkthroughs, see Common workflows . For extensibility features like skills, MCP, and hooks, see Extend Claude Code . 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 is the layer around the model that provides the tools and manages the context the model sees. This surrounding layer is what the term agentic harness refers to. 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, each representing a different kind of agency.

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 ) These are the primary capabilities.

Claude also has tools for spawning subagents, asking you questions, and other orchestration tasks. See Tools available to Claude for the complete list. 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 to see what’s failing Read the error output Search for the relevant source files Read those files to understand the code Edit the files to fix the issue Run the tests again to verify Each tool use gives Claude new information that informs the next step.

This is the agentic loop in action. Extending the base capabilities: The built-in tools are the foundation. You can extend what Claude knows with skills , connect to external services with MCP , automate workflows with hooks , and offload tasks to subagents . These extensions form a layer on top of the core agentic loop. See Extend Claude Code for guidance on choosing the right extension for your needs. 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. If you can do it from the command line, Claude can too. Your git state. Current branch, uncommitted changes, and recent commit history. Your CLAUDE.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 in place of a CLAUDE.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. Extensions you configure. MCP servers for external services, skills for workflows, subagents for delegated work, and Claude in Chrome for browser interaction.

Because 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. Environments and interfaces The agentic loop , tools , and capabilities are the same everywhere you use Claude Code.

What changes is where the code executes and how you interact with it. Execution environments Claude Code runs in three environments, each with different tradeoffs for where your code executes. Environment Where code runs Use case Local Your machine Default. Full access to your files, tools, and environment Cloud Anthropic-managed VMs, or self-hosted environments your organization operates Offload tasks, work on repos you don’t have locally Remote Control Your machine, controlled from a browser Use the web UI while execution and your files stay local Interfaces You can access Claude Code through the terminal, the desktop app , IDE extensions , claude.ai/code , Remote Control , Slack , and CI/CD pipelines .

The interface determines how you see and interact with Claude, but the underlying agentic loop is identical. See Use Claude Code everywhere for the full list. Work with sessions Claude 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 , resuming, and forking 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 . 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 , and you can add your own persistent instructions in CLAUDE.md . Work across branches Each 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 for the full list of picker shortcuts and how name resolution works. Claude 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 discuss

The rest of this page is on the live site.