Claude Code

Definition

Claude Code is Anthropic's official agentic coding CLI — a terminal program that embeds a Claude model behind a tool-using agent loop, so the model can read your files, edit them, run shell commands, manage git, query the web, and call out to external services until it has completed (or explicitly failed) the natural-language task you gave it. It is distributed as the npm package @anthropic-ai/claude-code plus a desktop app (macOS and Windows, redesigned in April 2026), can run interactively in a REPL or non-interactively via --print for scripts and CI, and ships with a context window of up to 1 million tokens on Opus-class models. Reach for the concept whenever the question is "how should this codebase change be done?" and the answer might involve dozens of files, several tools, and multiple iteration rounds — that's the surface Claude Code was designed for. The closest alternatives are OpenAI's Codex CLI and Cursor's agent mode; the Anthropic API alone is the level below (raw model output, no tools, no memory, no file access).

Why it matters

Claude Code matters because it is the first widely-adopted reification of a specific bet about AI coding assistants: that the right unit of work is a task, not a completion. Earlier-generation tools — autocomplete in an editor, single-shot Q&A in a chat panel — required the engineer to break a problem into model-sized pieces, paste the relevant context, and stitch the answers back together by hand. Claude Code inverts that: you describe the outcome in one sentence, and the agent does the breaking-down, the file-reading, the editing, the testing, the rollback when the tests fail, and the eventual commit. For routine work — refactor a function across the call sites, add a flag to a CLI tool, port a service from one HTTP library to another, set up a new fixture in a test suite — that translation costs a developer most of their time and very little of their judgment. Pushing it to the agent reclaims hours per week.

The model also matters because of what it forces you to think about. Two things become first-class concerns the moment you let an LLM read and write your codebase: context window economics (the same task that costs $0.20 with a tight CLAUDE.md costs $4 when the agent re-reads every file twice — see the 5-hour billing windows that ccusage tracks) and trust boundaries (the agent has shell access; what is it allowed to delete, push, or invoke without confirmation?). Claude Code is the most useful surface to learn those tradeoffs on because it makes them explicit: settings.json controls the trust boundary, CLAUDE.md controls what context the agent loads, and hooks let you wrap dangerous tool calls with shell-side policy. A developer fluent in Claude Code is fluent in how to deploy any agentic coding tool — the lessons transfer.

The third reason it matters is more pragmatic: Claude Code is now the default. As of mid-2026, Anthropic has shipped (a) parallel agent teams where a lead agent coordinates subagents on independent sub-tasks via Git worktrees, (b) skills as discoverable, user-invocable mini-programs that combine prompts and tools, (c) MCP as the open protocol other vendors use to integrate, (d) IDE extensions for VS Code and JetBrains, and (e) GitHub Actions workflows for CI-driven agent runs. Whatever the next-best alternative is at any moment, Claude Code defines the shape of the surface most teams are settling on, so understanding it well is leverage even when you choose a different tool.

How it works

Claude Code is, at its core, a tool-use loop wrapped around the Anthropic API. Stripping away the IDE niceties and the desktop app, the program does this on every turn:

1. Read CLAUDE.md (project, user, and enterprise scopes) plus any imported files into the system prompt.
2. Append the user's message (or the agent's prior tool result) to the conversation.
3. Call the model with the full tool definitions for Read, Edit, Write, Bash, Grep, Glob, WebFetch, WebSearch, TaskCreate, Agent, plus every tool registered by MCP servers and every skill marked as user-invocable.
4. Parse the model's response. If it contains tool calls, execute each one, capture stdout/stderr/exit code, feed the results back as the next user message, and loop. If it's a final text response, print it and return control to the REPL.

That loop is the entire engine; everything else is configuration, observability, and safety around it. The interesting design decisions are how each layer constrains the loop:

• CLAUDE.md is the project-, user-, and enterprise-scope memory file the agent reads on every session start. It's prose, not config — instructions the model should treat as load-bearing context. The convention is to put coding standards, architectural rules, ship/deploy procedures, and gotchas there. Three scopes layer: enterprise (organization-wide policy) → user (~/.claude/CLAUDE.md, personal preferences) → project (./CLAUDE.md, repo-specific rules), with later scopes overriding earlier ones.
• Settings (~/.claude/settings.json, ./.claude/settings.json, plus a .local.json per-machine variant) is JSONC-shaped configuration. It chooses the model, sets the API key source, configures hooks, registers MCP servers, picks the statusline command, and most importantly defines the permission mode and the per-tool allow/deny lists that gate which Bash, Edit, or MCP calls the agent can take without prompting the user.
• Hooks are shell commands the runtime executes around tool calls — PreToolUse, PostToolUse, Notification, UserPromptSubmit, Stop, SubagentStop. They are how you enforce policy that the model can't be trusted to obey on its own: block a commit unless tests pass, deny any rm -rf outside /tmp, post a Slack notification when the agent finishes.
• MCP (Model Context Protocol) is Anthropic's open JSON-RPC protocol for plugging external tools into the agent — databases, ticketing systems, search APIs, IDE state. An MCP server runs as a sidecar process; Claude Code starts it, lists its tools, and exposes them to the model under namespaced names. This is how third-party integrations work without Anthropic shipping bespoke code for each one.
• Subagents (sometimes "agent teams") are spawned sub-Claudes the lead agent dispatches concurrently for independent work, each in its own conversation context. Each subagent can optionally be isolated in a Git worktree so the lead's working tree isn't touched. The lead reads the subagent's final report and decides what to do next — the model coordinates the swarm, the runtime provides the isolation.
• Skills are named bundles of prompts plus tool descriptions that the runtime advertises to the model as "user-invocable" entry points. When a user types /skill-name, the runtime injects the skill's instructions into the conversation and the agent executes against them. Skills are how teams package repeatable workflows ("/ship", "/security-review", "/update-article") as discoverable nouns.
• Statusline is a custom shell command rendered in the REPL chrome on every keystroke (when configured). The de facto pattern is to surface cost-per-block from ccusage statusline --cache, the current model, and the active git branch.

The most important conceptual point: the model itself is stateless — every turn re-sends the entire conversation transcript plus the system prompt. What makes Claude Code feel like a long-lived agent is the runtime keeping that transcript on disk under ~/.claude/projects/<project>/<session-id>.jsonl, replaying it when you --resume, and prompt-caching the unchanging portion (system prompt, CLAUDE.md, prior turns) so subsequent turns within a 5-minute window cost a fraction of an uncached call. Designing CLAUDE.md and your settings well is, in practice, designing for cache hits.

Operating modes

Three modes show up in real use and shape how you should think about a Claude Code task:

• Interactive (REPL). You type a message, the agent works, asks clarifying questions, and pauses for permission on tool calls in your configured permission mode. This is the right surface for exploration, design discussions, and any task where you want to react to intermediate output.
• Headless / non-interactive (--print). A single message in, a single response out, no permission prompts (you've pre-authorized the toolset via settings or a custom permission mode). This is what runs inside CI workflows, slash commands invoked by other agents, and shell pipelines like claude --print "summarize this PR".
• GitHub Actions / scheduled. Claude Code can run as a GitHub Action triggered on PRs, issues, or a cron — the agent reads the repo, takes an action, posts a review or opens a PR, and exits. Same engine, different driver.

Trust boundary

Working with Claude Code productively means making one decision deliberately, not implicitly: what is the agent allowed to do without asking? The permission modes are the dial. Default (interactive prompt for every tool call) is safest but slowest; acceptEdits lets it edit files freely but still prompts for Bash; an explicit allowlist in settings.json whitelists specific commands (gh pr view, git status, rg ...) while keeping the rest gated. Power users converge on permissive allowlists for read-only and idempotent commands plus deny rules for the destructive ones (rm -rf, git push --force, anything matching their secret files), then handle the borderline cases with hooks. The lesson that transfers to every other agentic tool: never grant a permission the agent has not visibly used and that you would not also grant to a junior engineer with a shell on your laptop.

Common pitfalls

1. Empty or generic CLAUDE.md — the agent runs against your project's defaults instead of your actual conventions. Spend an hour writing concrete rules ("never commit without /ship", "use uv not pip", "shell is fish not bash") and it pays back inside one task.
2. Approving permissions one-by-one forever — every "yes" you would obviously give for the rest of the project belongs in settings.json as an allow rule. The interrupt-driven workflow is fine for week one; by week three it's just friction.
3. No hooks on destructive commands — rm, git push --force, git reset --hard, psql -c "DROP TABLE" — the model will eventually try one of these as a shortcut. A two-line PreToolUse hook that pattern-matches and refuses is the cheapest insurance you'll ever buy.
4. Letting context grow unbounded — every Read adds to the running transcript and the cache. Whole-file reads of vendor code, generated SQL dumps, or node_modules/ traversals each cost real money and crowd out the model's attention. Use Glob/Grep first, read narrowly.
5. Treating subagents as parallelism for its own sake — a subagent costs another full conversation context and another set of cache misses. Use them when sub-tasks are independent and the lead would otherwise serialize them, not as a default.
6. Ignoring 5-hour billing windows — every request inside a window counts toward the same block. Long open sessions where you wander between topics can quietly drain the block; check ccusage blocks --active periodically.
7. Pasting credentials into a Claude Code chat — the entire transcript is sent on every turn and cached on Anthropic's side for that session. Use a secret-manager and reference by name (gh secret get, op read), never the raw value.
8. Confusing model and runtime when reading errors — "Claude said X" sometimes means "the model returned X" and sometimes means "the runtime rendered X". Wrong attribution leads to the wrong fix. The CLI's --debug and --verbose flags surface which is which.
9. Not using --resume — the runtime persists every session under ~/.claude/projects/. Re-starting a session from scratch when you could have resumed throws away the warm cache and the prior planning state.
10. Trusting the agent's self-reports without verifying the diff — the model can confidently summarize "I refactored X and ran the tests" when in fact the test command failed silently. The runtime tracks edits and Bash exit codes, but the summary is just another model output. Always look at the working diff before claiming a task is done.

Where to go next

Concrete cheat sheets that document each surface Claude Code exposes:

• /sections/claude-code/overview — install, interactive vs headless, CLAUDE.md scope hierarchy, IDE integration, authentication.
• /sections/claude-code/cli-reference — every flag and subcommand the binary accepts.
• /sections/claude-code/settings — settings.json schema, permission modes, allow/deny rules, model selection.
• /sections/claude-code/slash-commands — user-invocable named workflows; how to author your own.
• /sections/claude-code/hooks — PreToolUse / PostToolUse / Stop / Notification hooks for policy and notifications.
• /sections/claude-code/mcp — Model Context Protocol; configuring and authoring servers.
• /sections/claude-code/subagents — agent teams, Git-worktree isolation, the lead-and-swarm pattern.
• /sections/claude-code/skills — packaging reusable prompts + tools as discoverable skills.
• /sections/claude-code/statusline — the custom statusline hook and the most useful patterns for it.
• /sections/claude-code/tips — power-user shortcuts, keybindings, transcript management.
• /sections/packages-npm/npm-ccusage — the de facto Claude-Code cost tracker; reads the same JSONL transcript files.

Concept neighbours worth reading alongside this one:

• /concepts/agents — the broader category of tool-using LLM loops; Claude Code is one specific implementation.
• /concepts/api — Claude Code is, mechanically, a programmable client of the Anthropic API; understanding API rate limits, streaming, and tool use translates directly.

External:

• /sections/claude-api/tool-use — the lower-level API surface Claude Code uses internally; the right level to read when debugging tool-call shape.
• /sections/codex/overview — OpenAI's Codex CLI; the closest peer to Claude Code, useful comparison surface.

Sources

References consulted while writing this concept page. Links open in a new tab.

• anthropics/claude-code on GitHub — Canonical repository; source for the npm package name (@anthropic-ai/claude-code), the tool-use loop architecture, and the official "agentic coding tool that lives in your terminal" framing.
• Claude Code — Overview docs — Anthropic's documentation; authoritative source for the settings hierarchy, permission modes, hooks lifecycle, and MCP integration model.
• Claude Code product page — Source for the April 2026 desktop-app launch (macOS + Windows) and the 1 M-token context window claim used in Definition.
• Code with Claude 2026 — new agent features — Cross-vendor write-up of the 2026 feature set (Agent Teams, parallel sessions, Git-worktree isolation, skills) referenced in Why it matters.
• Model Context Protocol announcement — Anthropic's MCP launch post; basis for the "MCP is the open JSON-RPC protocol other vendors use to integrate" framing in How it works.
• ryoppippi/ccusage — Third-party cost tracker that reads Claude Code's session JSONL files; cited as the practical surface where context-window economics become observable.