How Claude Code works as a coding agent

Claude Code is Anthropic’s agentic coding tool. Instead of just completing the line you are typing, it takes a task, decides which files to read, edits code, runs commands in the terminal and checks whether the result worked.

This article explains its architecture and how it works based exclusively on Anthropic’s official documentation, consulted on October 8, 2026. The product is updated frequently, so mode names, versions and figures cited here may change. Where a detail depends on the version, we say so.

If the concept of an agent is still new to you, it is worth reading what AI agents are first.

What Claude Code is

The documentation overview defines Claude Code as an agentic coding tool that reads your codebase, edits files, runs commands and integrates with your development tools.

It runs on several surfaces, as the documentation calls them: the terminal (the command-line interface, or CLI), extensions for VS Code and JetBrains IDEs, a desktop app and the web version at claude.ai/code. According to the same page, they all connect to the same engine, so the repository’s instruction files, settings and MCP servers apply in any of them.

To use it, most surfaces require a Claude subscription or an Anthropic Console account. The CLI, VS Code and JetBrains also accept third-party cloud providers, according to the documentation.

The architecture: model, tools and the “harness”

The How Claude Code works page describes two pieces. The first is the model, a Claude model that reasons about the task. The second is the tools, which let it act.

Claude Code itself is the layer around the model. It provides the tools and manages the context the model sees. The documentation calls this layer the agentic harness: the structure that connects the model to your computer.

The context, or context window, is everything the model has in front of it at any moment: the conversation, the contents of files it has read, command output and project instructions. To understand why that space is limited, see context and memory in AI.

The documentation groups the built-in tools into five categories:

• File operations: read, edit, create and rename files.
• Search: find files by pattern and search content with regular expressions.
• Execution: run shell commands, start servers, run tests and use git.
• Web: search the internet and fetch documentation.
• Code intelligence: see type errors after edits and jump to definitions, which requires specific plugins.

The agent’s work loop

When you hand it a task, Claude Code works in three phases that blend together, according to the documentation: gather context, take action and verify results. Each tool use returns information that guides the next step.

The documentation itself gives an example for the request “fix the failing tests.” The agent may run the test suite, read the error, search for the relevant files, read them, edit the code and run the tests again to confirm.

The loop adapts to the request. A question about the code may only need the reading phase. A bug fix may go through all three phases several times. You can interrupt at any moment with the Esc key or type a correction while the agent is working.

What the agent can see

When you run the claude command in a folder, the agent gains access, according to the documentation, to:

• files in the folder and its subfolders (and elsewhere, with your permission);
• any command you could run yourself in the terminal;
• git state, such as the current branch and uncommitted changes;
• the CLAUDE.md file, a Markdown text with project rules and conventions that the agent reads at the start of each session;
• an automatic memory, in which the agent stores learnings across sessions;
• configured extensions, such as MCP servers and subagents.

Each new session starts with an empty context window. When it nears the limit, Claude Code clears old tool output and summarizes the conversation. The documentation warns that instructions given early in the conversation may be lost in that summary and recommends putting permanent rules in CLAUDE.md.

Extensions: MCP, hooks and subagents

The built-in tools are the foundation. On top of them, the documentation describes extension layers.

MCP (Model Context Protocol) is an open standard for connecting AI tools to external data sources and services. According to the MCP page, MCP servers give Claude Code access to tools, databases and APIs. Configuration can be local, project-level (in a .mcp.json file versioned with the code) or user-level. The same page warns: make sure you trust each server, because servers that fetch external content expose you to prompt injection risk.

Hooks are shell commands you define that run at fixed points in the agent’s operation. The hooks guide explains the core difference: CLAUDE.md instructions are guidance the model may or may not follow, while a hook always runs. Examples from the documentation: formatting a file after every edit, notifying you when the agent is waiting for your input and blocking edits to sensitive files such as .env. A PreToolUse hook runs before a tool and can block the action.

Subagents are specialized assistants to which the main agent delegates tasks. According to the subagents page, each runs in its own context window, with its own instructions, restricted tool access and independent permissions. Only a summary returns to the main conversation. The documentation lists built-in subagents such as Explore, aimed at read-only search, and Plan, used in plan mode.

There are also skills, packages of reusable instructions and workflows that only enter the context when they are used.

Permissions and security

The security documentation states that the product has a permission-based architecture. The permission mode defines what the agent does without asking. The modes page, consulted on October 8, 2026, lists six:

Mode	What runs without asking	Documentation’s recommendation
Manual (default)	Reads only	Reviewing each action, sensitive work
acceptEdits	Reads, edits and common file commands	Iterating on code you review
plan	Reads (and commands approved by the classifier, when available)	Exploring before changing
auto	Everything, with background safety checks	Long tasks
dontAsk	Reads and pre-approved tools; everything else is denied	CI and locked-down scripts
bypassPermissions	Everything	Only isolated containers and virtual machines

In auto mode, a second model, called the classifier, reviews actions on your behalf and blocks those it judges risky. According to the documentation, from version 2.1.283 it is the default mode in interactive terminal and VS Code sessions; in earlier versions, only on the Pro, Max and Team plans.

On top of the modes, you can create permission rules that allow or block specific tools and commands. The documentation says deny rules apply in every mode, including bypassPermissions.

Other safeguards described:

• Sandbox: file system and network isolation for terminal commands. In an October 2025 engineering post, Anthropic reported that, internally, sandboxing reduced permission prompts by 84%. That is the company’s own figure, without external audit.
• Checkpoints: before editing, the agent saves a copy of the file, and you can roll back. The documentation cautions that this only covers edits made by the file tools, not actions on remote systems (databases, APIs, deployments) nor, according to the best practices guide, changes made by terminal commands. It does not replace git.
• Folder trust: in interactive sessions, Claude Code asks whether you trust a new folder before working in it.

The documentation is explicit about the limits of these defenses. Prompt injection is the technique in which an attacker inserts malicious text (in a file, a web page, a ticket) to manipulate the agent’s instructions. The security page says the safeguards greatly reduce the risk, but that no system is immune to all attacks. It also places on the user the responsibility for reviewing code and commands before approving them.

Use cases described by Anthropic

The overview and the best practices guide cite uses such as:

• writing tests for uncovered code, fixing lint errors (automatic style checks) and resolving merge conflicts;
• implementing features described in plain language and investigating bugs from an error message;
• creating commits, branches and pull requests;
• reviewing code and triaging issues in CI pipelines such as GitHub Actions;
• answering questions about an unfamiliar codebase, which the documentation presents as a way to onboard new team members;
• running non-interactively with claude -p in scripts, including migrations across many files.

These are the uses the vendor describes, not results measured by our newsroom. For a practical path to using it in a product, see our guide on how to build an MVP with AI agents.

Limits the documentation itself points out

The best practices guide starts from one constraint: the context window fills up fast, and performance degrades as it fills. The agent may “forget” earlier instructions or make more mistakes.

Other limits and warnings from the same guide:

• The agent stops when the work “looks done.” Without a test or check it can run, verification falls to you.
• Plausible implementations can fail on edge cases. The recommendation is blunt: if you can’t verify it, don’t ship it.
• Correcting the agent repeatedly in the same session pollutes the context. After two unsuccessful corrections, the guide suggests starting over with a better prompt.

The guide also suggests separating exploration, planning and implementation, and using a second session or subagent to review the code, since a fresh context is not biased by what it just wrote. On language model errors in general, see AI hallucinations.

How much it costs

The costs page states that Claude Code charges by API token consumption, and refers subscription plan pricing to claude.com/pricing. A token is the unit of text the model processes; see tokens in AI models.

On the date consulted (October 8, 2026), the documentation said that, in enterprise deployments, the average cost is around US$ 13 per developer per active day and US$ 150 to 250 per developer per month, with 90% of users below US$ 30 per active day. These are averages published by Anthropic; the page itself says cost varies widely depending on the model, codebase size and usage pattern, and recommends starting with a pilot group.

What weighs most, according to the documentation: long sessions without clearing (each request resends the history), larger models used as the default, and subagents and agent teams, which consume their own tokens. The /usage command shows an estimate of the session’s consumption; official billing is in the account dashboard.

Key takeaways

• Claude Code is a layer that gives tools to a Claude model and manages context; work follows a loop of reading, acting and verifying.
• MCP connects external services, hooks enforce rules that always run and subagents isolate tasks in separate contexts.
• Permission modes, deny rules, sandboxing and checkpoints reduce risks, but the documentation makes clear they do not eliminate them and that review remains your job.
• Tests and other automated checks are what separate a plausible result from a confirmed one.
• Costs and features change often. Check the official documentation before deciding.