Anthropic · Claude Code

Claude Code — terminal-native coding agent

Anthropic's official CLI. A Claude model (Opus 4.7 by default) running in your terminal with Read/Write/Edit/Bash tools, MCP integrations, a hook system, and project-scoped skills + memory. Ships on macOS, Linux, Windows (WSL2). Integrates with VS Code + JetBrains.

Opus 4.7 default

MCP-native

Hook system

Skills + plugins

Background agents

Worktree isolation

The request loop

per-turn lifecycle user prompt ──▶ UserPromptSubmit hook ──▶ model (Opus 4.7 / Sonnet 4.6 / Haiku 4.5) │ PreToolUse hook ◀──┐ │ parallel when independent │ ▼ tool call(s) Read · Write · Edit · Bash │ Glob · Grep · Agent · TaskCreate PostToolUse hook ◀──┘ WebFetch · MCP tool calls │ ▼ model reasons over results │ ▼ more tool calls OR stream response │ ▼ Stop hook · memory updated · turn ends

At a glance

Key	Value
Default model	claude-opus-4-7 (1M context)
Fast mode	claude-opus-4-6 (same class, faster streaming)
Install	`npm install -g @anthropic-ai/claude-code`
Project config	`.claude/settings.json`
User config	`~/.claude/settings.json`
Session store	`~/.claude/projects/<encoded-path>/*.jsonl`
Docs	docs.claude.com
Source	anthropics/claude-code

Mental model

In plain terms

Claude Code is a stateful REPL wrapping a Claude model. Every turn the model reads your project's CLAUDE.md, the visible conversation, and the results of any tool calls it makes. You steer by talking; it executes via tools. Hooks let you intercept the loop (block a prompt, format after an edit, notify on stop). Skills are reusable procedures the model can invoke. MCP servers extend the tool surface. Subagents are scoped spawns with their own tool surface + optional worktree isolation.

Phase 01 · Setup

Install & first run

Two minutes from blank machine to a running session.

Install

# npm (recommended) npm install -g @anthropic-ai/claude-code # or curl installer curl -fsSL https://claude.ai/install.sh | bash

First launch

claude # start an interactive session in the current dir claude --print "ls this repo and summarise" claude --model sonnet # switch model at launch claude --continue # resume the most recent session claude --resume <id> # resume a specific session

Platforms

Platform	Notes
macOS	First-class. Apple Silicon preferred for local-model interop.
Linux	First-class. Any distro with Node 20+.
Windows	Via WSL2. Native Windows is experimental.
Docker	Official image for sandboxed runs. Good with `--dangerously-skip-permissions`.

IDE integration

VS Code — official extension. Keybinding launches Claude Code in a side pane or terminal. Sees the active file + selection.
JetBrains — plugin with the same shape. IntelliJ / PyCharm / WebStorm / GoLand.
Any editor — Claude Code runs fine standalone in a terminal. The IDE extensions are a UX polish, not a requirement.

Authentication

Anthropic API key — set ANTHROPIC_API_KEY in the environment or via claude login.
Amazon Bedrock — set CLAUDE_CODE_USE_BEDROCK=1 + your AWS credentials.
Google Vertex AI — set CLAUDE_CODE_USE_VERTEX=1 + ADC credentials.
ChatGPT-style OAuth — not supported today; Claude Code is API-keyed only.

Phase 02 · CLI

CLI & flags

Every flag worth knowing, grouped by what they do.

Invocation modes

Flag	Effect
--print	One-shot mode. Read prompt from args or stdin, write response to stdout, exit. Ideal for scripting.
--continue	Resume the most recent session in the current directory.
--resume <id>	Resume a specific session by id.
--model <name>	Pin the session's model. Aliases: `opus`, `sonnet`, `haiku`.
--dangerously-skip-permissions	Bypass the runtime permission prompt entirely. For sandboxed or CI runs.
--mcp-config <path>	Load MCP servers from a file instead of settings.json.
--cwd <path>	Run with a specific working directory (overrides auto-detection).

Common recipes

# quick one-shot echo "explain this repo" | claude --print # scripted pipeline claude --print "list open TODOs in src/**/*.ts" > todos.md # sandboxed build on a branch claude --dangerously-skip-permissions "run the build and fix any lint errors" # resume where you left off claude --continue

Keyboard

Esc — interrupt the current turn. Model treats it as a user stop; steers mid-reply.
Ctrl+C — quit the CLI entirely. Ctrl+D works too.
↑ / ↓ — cycle through prior prompts.
Tab — autocomplete slash commands + file paths.
! prefix — run a shell command in-band (output lands in the conversation).
Custom via ~/.claude/keybindings.json.

Phase 03 · In-chat commands

Slash commands

Built-in slashes + how to author your own.

Built-ins

Command	Purpose
/help	Inline help — built-ins + registered user commands
/clear	Wipe the visible transcript + context; settings + MCP stay loaded
/compact	Summarise + compact the conversation to reclaim tokens
/fast	Toggle Claude Opus 4.6 (faster streaming, same weight class)
/model <name>	Switch model mid-session
/init	Bootstrap a CLAUDE.md for the current repo
/review	Review a pull request or the current diff
/security-review	Scan pending changes for security issues
/loop [interval] <cmd>	Run a command on a recurring interval (or self-paced)
/schedule	Create/manage scheduled remote triggers
/statusline	Configure the status line above the input
/resume	Open the session picker

Authoring a user slash

Any .claude/skills/<name>/SKILL.md registers as /<name>. Minimum shape:

--- name: my-command description: A one-line description shown in /help and used for auto-trigger. --- # my-command Instructions Claude follows when this skill invokes. Plain markdown. Reference supporting files (scripts, templates) by relative path.

Auto-trigger vs user-invoked

Skills with an informative description field can be auto-invoked by the model when it thinks the user's request matches. Skills meant to be explicit (reproducible ops) should say so in the description so they only fire on /<name>.

Phase 04 · Reusable procedures

Skills

Markdown files that teach Claude how to do something specific. Lazy-loaded, versioned with the repo.

Three scopes

Project

./.claude/skills/<name>/SKILL.md — versioned with the repo. Shared across contributors.

User

~/.claude/skills/<name>/SKILL.md — per-user, cross-project. Personal shortcuts + preferences.

Global / marketplace

Installed via the plugin system; pinned in skills-lock.json. Shared across repos; reproducible across machines.

Anatomy

.claude/skills/my-skill/ ├── SKILL.md # the instructions (frontmatter + body) ├── helpers/ # optional scripts the skill calls │ └── do-thing.sh ├── templates/ # optional templates the skill fills in │ └── report.md.hbs └── README.md # optional — doesn't affect behaviour

Frontmatter

--- name: my-skill description: What the skill does. Used for auto-match; write it for the model's benefit. ---

When to write one

Reproducible multi-step procedures — "run the release playbook", "regenerate client reports".
Code conventions — "how to add a new route to this API", "how to write a migration".
Investigation patterns — "how to debug the gateway", "how to read production logs".
Personal ergonomics — "commit + push with the conventional message format".

Anti-patterns

Don't write a skill for something that's in CLAUDE.md. If it's always-relevant for the project, it belongs in the project primer.
Don't embed credentials or secrets. Skills are versioned; point at env vars instead.
Don't make skills that just call one tool. The model can already do that — skills are for procedures.

Phase 05 · Intercept the loop

Hooks

Shell commands that fire at well-defined points inside the agent loop. Gate, rewrite, notify, log.

Six hook types

UserPromptSubmitbefore Claude sees the message — gate, rewrite, inject context

SessionStartonce per session, after CLAUDE.md loads — prime env, print banner

PreToolUsebefore any tool call — enforce allowlists, rewrite arguments

PostToolUseafter a tool call returns — run formatters, log, notify

Stopwhen the main turn ends — cleanup, summary, continuation

SubagentStopwhen a subagent finishes — notify, collect artefacts

Config shape

// .claude/settings.json { "hooks": { "PostToolUse": [ { "matcher": "Edit|Write", "hooks": [ { "type": "command", "command": "biome check --write $CLAUDE_TOOL_PATH" } ] } ], "UserPromptSubmit": [ { "hooks": [ { "type": "command", "command": "./scripts/inject-context.sh" } ] } ] } }

Hook contract

Input — hook receives a JSON payload on stdin describing the event (tool name, arguments, prompt text, cwd).
Output — stdout becomes additional context the model sees. For blocking hooks (PreToolUse, UserPromptSubmit), a non-zero exit code denies the action.
Ordering — multiple hooks on the same event fire in declaration order. Any hook blocking stops the chain.
Timeout — default 30s per hook; configurable per entry.

Patterns that earn their keep

Auto-format — PostToolUse on Edit|Write running Biome / Prettier / ruff.
Allowlist gate — PreToolUse on Bash checking the command against an approved pattern list.
Context injection — UserPromptSubmit that pipes git status into context when a prompt mentions commits.
Session banner — SessionStart that prints branch, last-commit, running services.
Stop notification — Stop hook that pings Slack / says a word via say / flashes the Dock.

Phase 06 · Tool surface

MCP & tools

Built-in tools ship with the CLI. MCP servers extend the surface to anything with an integration.

Built-in tools

File ops

Read · Write · Edit · NotebookEdit · Glob · Grep. The core loop for touching code.

Shell

Bash (with run_in_background) + Monitor for tailing async processes.

Agent

Agent (spawn subagents) · SendMessage (continue a named agent) · TaskCreate/List/Update (progress tracking).

Web

WebFetch (specific URL) · WebSearch (query). Distilled results, not raw HTML.

Schedule

ScheduleWakeup for /loop dynamic pacing. CronCreate/List/Delete for persistent schedules.

Skill

Invoke a user-authored skill by name. Registered automatically from .claude/skills/.

ToolSearch

Fetch schemas for deferred MCP tools so they become callable in the current session.

Misc

AskUserQuestion (structured question) · ExitPlanMode (leave plan mode) · Config (get/set a subset of settings).

MCP config

// .claude/settings.json — project scope { "mcpServers": { "filesystem": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem", "."] }, "github": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-github"], "env": { "GITHUB_PERSONAL_ACCESS_TOKEN": "${env:GH_TOKEN}" } } } }

Three transports

stdioSpawn a subprocess; JSON-RPC over stdin/stdout. Most servers. Ships with Claude Code starting the process on session open.

HTTPHosted endpoint. Server URL in config. Useful for shared corporate MCPs.

OAuth 2.1Hosted + user-authenticated. Claude Code handles the OAuth dance on first use; token cached locally.

Deferred tools

Large MCP tool libraries (100+ tools) use deferred registration — names appear in the system reminder but schemas load on demand via ToolSearch. Keeps the initial prompt small. Call ToolSearch "select:<name>" before invoking a deferred tool.

Phase 07 · Delegation

Subagents

Spawn scoped agents. Isolate risky work in a git worktree. Run in the background with Monitor.

Built-in subagent types

Type	Use
general-purpose	Catch-all. Can use any tool. Default choice for open-ended tasks.
Explore	Codebase search — Glob / Grep / Read with no write tools. Cheap reconnaissance.
Plan	Read-only planning. Produces an implementation plan without touching files.
statusline-setup	Configure the status line.
keybindings-help	Edit `~/.claude/keybindings.json`.
(project-defined)	Drop `.claude/agents/<name>.md` to register a custom persona + tool allowlist.

Agent tool calls

// typical Agent invocation Agent({ subagent_type: "Explore", description: "Survey session logs", prompt: "Find every reference to `callOpenclawDefaultModel` in the repo ..." }) // with worktree isolation — agent runs in a throwaway branch Agent({ subagent_type: "general-purpose", description: "Risky refactor trial", prompt: "Try replacing X with Y; report back whether tests pass.", isolation: "worktree" }) // background — returns immediately, notifies on completion Agent({ subagent_type: "general-purpose", description: "Nightly dep audit", prompt: "Run `npm audit` and summarise ...", run_in_background: true })

Writing the prompt

Self-contained — subagents start with zero context. State goal, give paths, specify the expected output shape.
Length-capped — ask for a brief report ("under 200 words") if that's what you need. Default behaviour is verbose.
Brief like a colleague — "Here's what we know, here's what we've tried, here's what I need you to find" outperforms terse commands.
Don't delegate synthesis — "based on your findings, fix the bug" pushes the hard thinking to the subagent. Gather findings first, reason in the main turn.

Worktree isolation

isolation: "worktree" creates a temporary git worktree on a new branch, runs the subagent there, cleans up if no changes are made, and returns the worktree path + branch name if changes land. Use for any mutation you might need to throw away.

Background + Monitor

Background agents notify on completion automatically — don't poll. The Monitor tool streams stdout line-by-line if you need tail-style visibility. For one-shot waits ("run this, block until done"), use Bash run_in_background=true + Monitor instead of Agent.

Phase 08 · Config

Settings

Three files, a merge order, and the blocks that matter.

File layout

File	Scope	Commits?
~/.claude/settings.json	User · machine-wide	No (outside repo)
.claude/settings.json	Project	Yes — shared with contributors
.claude/settings.local.json	Project-local overrides	No — gitignored

Merge order: local > project > user. Most-specific wins on scalar keys; arrays concatenate.

Key blocks

permissions

allow / deny rules for tools. Glob-pattern match. Most restrictive wins.

hooks

Per-event arrays of {matcher, hooks: [{type:"command", command}]}. See the Hooks tab.

mcpServers

Map of server-name → transport config. See the MCP tab.

env

Environment variables injected into the Claude Code process.

model

Default model for the project. Override with --model or /model.

statusLine

Script or template that produces the line above the input.

disabledTools

Tool names to hide for this scope. Useful to disable WebFetch in offline/secure workflows.

outputStyle

Formatting preset for model output — concise, verbose, etc.

Example

{ "model": "claude-opus-4-7", "permissions": { "allow": ["Bash(git status)", "Bash(git diff:*)", "Read(./**)"], "deny": ["Bash(rm -rf:*)", "Read(./.env:*)"] }, "hooks": { "PostToolUse": [ { "matcher": "Edit|Write", "hooks": [{ "type": "command", "command": "biome check --write $CLAUDE_TOOL_PATH" }] } ] }, "mcpServers": { "filesystem": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem", "."] } } }

Keybindings

Separate file: ~/.claude/keybindings.json. Configurable via the keybindings-help subagent — just ask Claude Code to remap something, and it'll write the JSON.

Phase 09 · Gating

Permissions

Runtime mode + allowlist rules. Two layers that compose.

Six runtime modes

defaultPrompt per tool call. Safest. Good for greenfield or high-risk changes.

acceptEditsAuto-approve Read/Write/Edit. Prompt for everything else.

autoAuto-approve most tools. Prompt only for destructive operations.

planRead-only planning. Write/Edit/Bash-with-side-effects disabled. Exit via ExitPlanMode.

bypassPermissionsNothing prompts. For sandboxed/Docker/CI runs. Pairs with --dangerously-skip-permissions.

dontAskReject anything not explicitly allowed in settings. Most restrictive.

Allowlist syntax

{ "permissions": { "allow": [ "Bash(git status)", // exact "Bash(git diff:*)", // prefix — matches `git diff`, `git diff HEAD`, etc "Read(./src/**)", // glob — any file under src/ "WebFetch(https://github.com/*)" ], "deny": [ "Bash(rm:*)", "Bash(curl:*)", "Read(./.env)", "Read(./secrets/**)" ] } }

Tie-break: deny wins over allow. Most-specific wins when both match.

Plan mode

Great for high-trust planning before touching code. Claude Code can Read, Grep, Glob, WebFetch — it cannot Write, Edit, or run a destructive Bash command. Exit plan mode with the ExitPlanMode tool after user approves the plan.

Skip-permissions gotchas

--dangerously-skip-permissions bypasses the runtime prompt but does not bypass settings.json deny rules. Use both if you really want unfettered access.
Pair skip-permissions with sandboxing — Docker, a worktree, a throwaway directory. It's not a "safe to run anywhere" flag.
CI runs benefit from skip-permissions plus an explicit deny list for anything you never want the model touching.

Phase 10 · State that survives

Memory

CLAUDE.md + auto-memory. What Claude Code remembers between sessions and between projects.

Three layers

Project CLAUDE.md

Repo root. Auto-loaded into every session in that project. Overview · stack · commands · conventions · invariants. /init bootstraps one.

User CLAUDE.md

~/.claude/CLAUDE.md. Loaded into every session across every project. Tone, idioms, global preferences.

Auto-memory

~/.claude/projects/<path>/memory/. Agent-managed notes keyed by type (user / feedback / project / reference). Grows over time.

CLAUDE.md — what to put in it

Project overview — one paragraph. What the thing is, what it's for.
Tech stack — runtime, frameworks, package manager.
Key paths — where things live. Save the model 10 Grep calls.
Key commands — dev, build, test, deploy. Copy-pasteable.
Conventions — formatting, branch names, commit style, forbidden patterns.
Env — what .env keys exist + where to set them.
Invariants / hazards — "don't touch X manually, it's auto-maintained."
Phase runbook — if there's a staged rollout (migrations, phases), link to it.

Auto-memory types

Type	Purpose
user	Your role, responsibilities, knowledge level. Informs how Claude frames answers.
feedback	Corrections + confirmed approaches. Survives across sessions so you don't re-correct.
project	Facts about the current project — who's doing what, deadlines, decisions.
reference	Pointers to external systems — Linear project, Slack channel, Grafana dashboard.

Memory discipline

When to save a memory

User corrects your approach → feedback. User confirms a non-obvious choice worked → feedback. User mentions who's doing what by when → project. User points at an external tool ("check the Linear project X") → reference. User shares a role or preference → user.

When NOT to save a memory

Anything derivable from the current project state (architecture, file paths, git blame). Anything already in CLAUDE.md. Ephemeral task state. Debugging solutions (the fix is in the code; the commit message carries context).

MEMORY.md index

MEMORY.md under the project memory dir is an index — one line per memory file, under ~150 chars: - [Title](file.md) — one-line hook. Always loaded into context. Keep it tight (lines past ~200 get truncated).