The Claude Code Handbook

Most people use Claude Code the way they’d use autocomplete: type a request, take what comes back, move on. That works, and it leaves most of the tool on the table.

This handbook is the other path. Twenty-three chapters, worked end to end, on how Claude Code actually behaves — what it’s allowed to do and why, what it remembers and what it forgets, how to hand it new abilities, how to make it obey rules it cannot ignore, and how to run several of it at once without the whole thing collapsing into noise.

Every chapter stands alone. Read top to bottom and you’ll finish an expert.

Part 1 — Foundations

What the thing is, how you talk to it, and how to stop it doing something you’ll regret.

  1. What Claude Code Actually Is — the execution model: a text-to-text model with no I/O, the harness that supplies tools, the gather/act/verify loop, the full tool table, and session state on disk.
  2. Three Ways to Talk to Claude Code — the three input channels and what separates them, print mode as a shell filter, @ and !, shell mode’s cost change in v2.1.186, and queueing.
  3. Permission Modes — the six modes and what each auto-approves, how auto mode’s classifier decides, its 3-in-a-row circuit breaker, and the paths no mode will approve.
  4. Permissions & Sandboxing — the three rule tiers and deny-first evaluation, Tool(specifier) syntax and where the * goes, path anchoring, working directories, and the Bash sandbox’s OS-level boundary.

Part 2 — Context Engineering

The context window is the budget everything else spends. This part is about spending it well.

  1. Settings: the Control Panel — the four settings files and what each reaches, the precedence stack, the keys that merge or run backwards through it, and how to find out which file is beating yours.
  2. CLAUDE.md — every location it can live and how several files concatenate rather than override, @path imports and their limits, why it is context rather than configuration, and the test for whether an instruction belongs in it at all.
  3. Rules & Auto Memory — why splitting CLAUDE.md only helps if the rules are scoped, paths: frontmatter and the glob edges that silently match nothing, and the notes Claude keeps for itself between sessions.
  4. The Context Window — what is already in the window before you type, what compaction re-injects and what it drops, and why the prompt cache makes a mid-task model switch cost more than the switch itself.
  5. Sessions, Checkpoints & Rewind — where a session lives on disk, what a resumed one quietly forgets, and the four categories of change /rewind cannot undo.

Part 3 — Teaching Claude New Tricks

Turning your preferences into capabilities, and your hopes into guarantees.

  1. Output Styles — the one extension point that edits the system prompt itself, the five built-ins, and why keep-coding-instructions defaulting to false is the field that matters.
  2. Skills — progressive disclosure and what each tier costs, the two booleans that decide who can invoke a skill, single-turn tool grants, and the checkpoint guarantee context: fork takes away.
  3. Hooks — where each event fires and which can block, the exit-code contract, and the asymmetry that lets a hook tighten your permissions but never loosen them.
  4. Plugins & Marketplaces — the layout and the one directory mistake that silently breaks a first plugin, what enabling one costs your cache, and how marketplaces distribute them.

Part 4 — Connecting Claude to the World

Claude knows your code. This part is about everything else it needs to know.

  1. MCP Fundamentals — four transports and three scopes, the deferral that stops ten servers filling your window, and the trust boundary around a committed .mcp.json.
  2. MCP in Practice — the three questions that decide whether a task needs a server, the native Chrome integration and its safety model, and the documented prompt shapes.
  3. GitHub, GitLab & CI — three levels of integration, the input that decides whether a workflow waits for @claude, and what a headless run does with permissions when nobody is there to answer.

Part 5 — Agents & Autonomy

One agent is a pair programmer. Several are a team.

  1. Sub-Agents — delegation as context management: what a subagent starts with, the four things it deliberately does not inherit, and the difference between a subagent and a fork.
  2. Agent Teams & Parallel Work — four ways to run sessions at once and the three questions that choose between them, agent teams and their experimental sharp edges, and when parallelism costs more than it saves.
  3. Automation & Scheduling — four schedulers and the constraints that pick between them, /loop and its seven-day fuse, and the payload wrapper that keeps a leaked token from becoming an instruction.
  4. Claude Code Everywhere — the one question that sorts every surface, five ways to work away from your terminal, and what your configuration does and does not follow you onto.

Part 6 — Running It for Real

What it costs, how it’s secured, and what to do at 2am when it won’t behave.

  1. Cost, Monitoring & Security — what a seat actually costs, the six reasons an idle session keeps spending, the levers that move it, and the sentence in the docs that says what the injection defences do not cover.
  2. When It Goes Wrong — the question that routes a symptom to the right page, the commands that show what actually loaded, narrowing by subtraction, and the location mistakes behind most “my hook never fires”.

Closing

  1. Becoming an Expert — one repository configured end to end in the order that makes each layer cheap, the guidance-or-guarantee question underneath every decision here, the habits that matter more than the files, and where the road goes after the CLI.

How to read this handbook

Read the first section of a chapter, then stop and try the thing on your own project before continuing. Every chapter has something you can run in under a minute.

Every diagram opens full screen — click it, then scroll or pinch to zoom. Every chapter with an interactive piece is meant to be played with rather than read past; that’s usually where the idea actually lands.

Chapters are verified against the official documentation as they’re written. Where the docs and this handbook disagree, the docs win — and I’d like to know, so tell me.