# Claude Code

Claude Code is Anthropic's agentic coding tool that reads a codebase, edits files, runs commands and tests. Learn how it works, memory files, sub-agents, hooks and safe use.

## Overview

Claude Code is Anthropic's agentic coding tool. It does not just suggest the next line of code. It takes a whole task, reads the parts of the codebase that matter, makes a plan, edits files, runs commands and tests, reads the output and keeps going until the change works or it needs a decision from a person. It started as a command-line tool and now also runs inside IDEs, on the web and in Anthropic's desktop and mobile apps.

The difference from autocomplete is the difference between a spell checker and a colleague who can take a ticket. A spell checker fixes one word at a time. The colleague reads the relevant code, changes several files, runs the tests, fixes what broke and comes back with a working result and a short summary. You still review the work, but you are no longer typing every line.

This page explains what Claude Code is made of, how its agent loop works, how memory files, permissions, hooks, sub-agents, skills and MCP fit together, and how to use it safely on real projects.

## What it is

Claude Code is an agent harness: a program that gives a Claude model a set of tools, a working directory and rules, then runs the model in a loop. The model decides what to do; the harness carries out the actions and enforces the rules.

| Part | What it does |
|---|---|
| Agent loop | Repeats: think, call a tool, read the result, decide the next step |
| Built-in tools | Read and search files, edit and write files, run shell commands, fetch web pages |
| `CLAUDE.md` memory files | Project and personal instructions loaded at the start of each session |
| Permissions | Allow, ask and deny rules, plus permission modes, that decide which actions need approval |
| Hooks | Your own scripts that run at fixed events, such as before or after a tool call |
| Sub-agents | Named helper agents with their own context, prompt and tool set |
| Skills and plugins | Packaged instructions, scripts and commands that load when relevant |
| MCP servers | Connections to external tools such as issue trackers, databases and browsers |
| Surfaces | Terminal, IDE extensions, web, desktop and mobile apps, and CI jobs |

The model does the reasoning. Everything else on the list is there to give it good context, useful abilities and firm limits.

## Where it came from

Anthropic introduced Claude Code as a research preview on 24 February 2025, alongside Claude 3.7 Sonnet. It was a terminal tool from the start, built around the idea that a capable model with plain tools such as file reads, search and a shell could do real engineering work.

Claude Code became generally available on 22 May 2025, with integrations for popular IDEs and GitHub Actions. Hooks followed at the end of June 2025, giving users a way to run their own code at lifecycle events. Custom sub-agents, defined through an `/agents` command and Markdown files, arrived in July 2025. In September 2025 the SDK that powers Claude Code was renamed the [Claude Agent SDK](/tools/claude-agent-sdk), so developers could build their own agents on the same harness.

October 2025 brought Agent Skills, Claude Code on the web as a research preview for cloud sessions, and a plugin system for sharing commands, agents, skills, hooks and MCP servers through marketplaces. Through 2026 the desktop app gained review and preview tools and a multi-session workspace, and the permission system gained further modes and controls.

## How it works

### The agent loop

You describe a task in plain language. The model reads the request, the memory files and the list of available tools. It usually starts by exploring: listing directories, searching for symbols, reading files. It may write a short plan. Then it makes edits and runs commands, such as the build or the test suite. Each tool result goes back into the model's context, and the model decides the next step. The loop ends when the model reports that the task is done, when it needs your input, or when you stop it.

### Context and memory

A session's context holds the conversation, the files read and the tool outputs. `CLAUDE.md` files give every session the same starting knowledge: how to build and test, coding conventions, directories to avoid, and team rules. They can live in your home directory, in the project root and in subfolders. When a session grows long, Claude Code compacts older parts of the conversation into a summary so work can continue. See [context engineering](/tools/context-engineering) for the wider idea.

### Permissions

Claude Code, not the model, enforces permissions. Rules in settings files list tool patterns to `allow`, `ask` about or `deny`; deny rules are checked first, then ask, then allow. Permission modes set the overall behaviour. `default` asks the first time each tool is used. `acceptEdits` accepts file edits automatically. `plan` lets Claude read and explore but not edit source files. `auto` approves calls after background safety checks. `dontAsk` refuses anything that would need a prompt unless it was pre-approved. `bypassPermissions` skips prompts and is meant only for isolated environments such as containers or virtual machines. Organisations can lock settings through managed policies.

### Hooks

Hooks are commands that run at events such as `PreToolUse`, `PostToolUse` or session start. A `PreToolUse` hook can inspect a planned command and block it. A `PostToolUse` hook can run a formatter after every edit. Hooks turn rules that you would otherwise only write in `CLAUDE.md` into rules enforced by code.

### Delegation and extensions

[Sub-agents](/tools/sub-agents) take bounded jobs, such as a code review or a wide search, in their own context and return a short report. [Skills](/tools/skills) load detailed procedures only when a task needs them. [MCP](/tools/mcp) servers add tools from outside systems.

## Key concepts and terms

| Term | Meaning |
|---|---|
| Agentic coding | A model completing coding tasks by acting with tools in a loop |
| Harness | The program around the model that supplies tools and enforces rules |
| `CLAUDE.md` | A Markdown memory file of instructions read at session start |
| Permission rule | A pattern such as `Bash(npm test)` marked allow, ask or deny |
| Permission mode | The session-wide approval behaviour, such as `plan` or `acceptEdits` |
| Plan mode | A mode where Claude explores and proposes but does not edit source files |
| Hook | A user script that runs at a lifecycle event |
| Sub-agent | A helper agent with its own context, prompt and tools |
| Skill | A folder of instructions and scripts loaded on demand |
| Plugin | A bundle of commands, agents, skills, hooks and MCP servers |
| Compaction | Summarising older context so a long session can continue |
| Headless mode | Running Claude Code non-interactively, for example in CI |

## A worked example

This is an illustrative scenario. A developer asks: "Add cursor-based pagination to the `GET /orders` endpoint and update the tests."

1. In plan mode, Claude Code searches for the route handler, the database query and the existing tests. It reads five files and proposes a plan: add `limit` and `cursor` parameters, change the query to order by id, return a `next_cursor` field, and add tests for the first, middle and last pages.
2. The developer approves the plan and switches to `acceptEdits`.
3. Claude Code edits three files. A `PostToolUse` hook runs the formatter after each edit.
4. It runs the test suite. Forty-one tests pass and one fails: the last page returns one duplicate row, an off-by-one error in the cursor comparison.
5. It changes `>=` to `>` in the query and re-runs the tests. All forty-two pass.
6. It asks a read-only reviewer sub-agent to check the diff. The reviewer notes that `limit` has no upper bound. Claude Code caps it at 100 and adds a test.
7. It summarises the change: files touched, the new parameters, test results and one open question about the default page size.

The developer reads the diff, answers the question and commits.

## Strengths and limitations

**Strengths:**

- Completes multi-file tasks end to end, including running and fixing tests.
- Works in many places: terminal, IDE, web, desktop and CI.
- Adapts to each project through memory files, skills and hooks.
- Permission rules and modes give fine control over risk.
- Extends to outside systems through MCP and plugins.

**Limitations:**

- Quality depends on clear instructions and good tests; without tests, "done" is a guess.
- Broad permissions on a real machine can cause damage, from deleted files to leaked secrets.
- Repository files, issues and web pages can carry prompt injection.
- Long sessions can lose detail through compaction.
- Large or architectural changes still need careful human review.

## How it compares with alternatives

| Option | Best at | Trade-off |
|---|---|---|
| Claude Code | Whole tasks with edits, commands and verification | Needs permissions and review discipline |
| IDE autocomplete | Fast inline suggestions while typing | Does not run or verify anything |
| Chat assistants | Explanations and snippets | No direct access to the project |
| [Claude Agent SDK](/tools/claude-agent-sdk) | Building your own agent on the same harness | You write and operate the product |
| Other agent frameworks such as [OpenAI Agents SDK](/tools/openai-agents-sdk) | Custom agents across providers | Coding tools must be assembled yourself |

## Practical guidance and best practices

1. Keep `CLAUDE.md` short and concrete: build command, test command, style rules and forbidden paths.
2. Use plan mode for anything larger than a small fix, and read the plan before approving it.
3. Make tests the definition of done, and ask Claude Code to run them before it reports success.
4. Start with conservative permissions. Allow read and test commands, ask for network and destructive commands.
5. Enforce hard rules with hooks or deny rules rather than with prose alone.
6. Use sub-agents for wide searches and reviews so the main context stays focused.
7. Run `bypassPermissions` or unattended jobs only in containers or virtual machines; see [sandboxing](/tools/sandboxing).
8. Treat untrusted repositories and fetched pages as data, not instructions; see [prompt injection defence](/tools/prompt-injection-defense).
9. Review every diff before merging, as you would a colleague's pull request.

## Common mistakes

- Writing a long, vague `CLAUDE.md` that the model cannot follow reliably.
- Approving everything with "yes, don't ask again" in the first session.
- Asking for a large refactor in one prompt without a plan or checkpoints.
- Accepting "tests pass" without checking that relevant tests exist.
- Running with real cloud credentials in the environment when they are not needed.
- Letting one session grow for hours instead of starting fresh with a written plan.

## Frequently asked questions

### What is Claude Code?

Claude Code is Anthropic's agentic coding tool. It reads a codebase, edits files, runs commands and tests, and repeats until a task works, showing each action as it goes and asking for approval where your permission settings require it.

### What is CLAUDE.md?

It is a Markdown file of instructions that Claude Code loads at the start of each session. Teams use it for build and test commands, conventions and rules, and can place copies in the home directory, the project root and subfolders for different scopes.

### Is Claude Code only for the terminal?

No. It began as a terminal tool, but it also runs in IDE extensions, on the web for cloud sessions, in the desktop and mobile apps, and non-interactively in CI pipelines such as GitHub Actions.

### What does plan mode do?

In plan mode Claude Code reads files and runs read-only commands to explore, then proposes a plan without editing your source files. It is a safe way to agree the approach before any change is made.

### How do hooks differ from CLAUDE.md instructions?

Instructions in `CLAUDE.md` guide what the model tries to do, but the model can still make mistakes. Hooks are scripts that run at fixed events and can block or modify actions, so they enforce rules regardless of what the model decides.

### Is it safe to let Claude Code run commands?

It can be, with the right setup. Keep approvals on for risky commands, deny access to secrets, run unattended or fully permissive sessions only in isolated environments, and review the results. Permissions are enforced by the tool, not by the model.

### Can I build my own agent the same way?

Yes. The Claude Agent SDK exposes the same agent loop, tools, permissions and context handling, so developers can build agents for other domains on the harness that powers Claude Code.

## Glossary

- Agent loop: the repeated cycle of reasoning, tool use and observation.
- Tool call: a structured request from the model to run an action such as a file edit.
- Permission mode: a setting that changes how tool calls are approved for a session.
- Deny rule: a permission rule that blocks matching actions, checked before ask and allow.
- Hook: a script run by Claude Code at a lifecycle event.
- Sub-agent: a helper agent started for a bounded job in a separate context.
- Skill: a packaged procedure with a `SKILL.md` file, loaded when relevant.
- MCP server: a program exposing external tools through the Model Context Protocol.
- Compaction: replacing older context with a summary to free space.
- Managed settings: organisation-wide settings that users cannot override.

## Summary

Claude Code turns a plain-language coding request into a completed, tested change by running a Claude model in a loop with file, search and shell tools. Memory files give it project knowledge, permissions and hooks set firm limits, sub-agents and skills keep context focused, and MCP connects it to outside systems. It works best with short, concrete instructions, tests as the definition of done, conservative permissions that grow with trust, isolation for unattended runs and a human review of every diff.