Claude Code Operator's Library

Claude Code users routinely spend more on tokens than they expect, and cannot see where the money goes.

This guide diagnoses specific token-waste patterns with real cost data from the author's own production Claude Code operation, then gives measured fixes: why costs spike overnight and the first settings to check; the hidden costs of sub-agents, thinking tokens, and context-window bloat; and a chapter-by-chapter diagnostic workflow with real dollar figures.

Chapter 8 alone is a catalogue of 48 diagnosable symptoms, each with what it looks like, what causes it, and what to change.

Chapter 10 adds the April 2026 incidents — the cache TTL silent change, the v2.1.100 cache_creation inflation, and a $1,446 unauthorized transfer traced to its cause. Chapter 11 adds May 2026, the month single failures became clusters: silent skips, silent model swaps, sub-agent boundary gaps, and a $6,000 overnight quota burn.

Revised edition of 2026-08-21: 11 chapters, 89 pages. Updates are free to buyers.

Not theory and not prompt packs: symptoms you can match against your own session, copy-paste templates, and measurements rather than reasoning. Written against Claude Code as it stood through mid-2026 — what carries over is the diagnostic method and the numbers behind it.

Also sold in two bundles. The four-book Claude Code Operator's Library — this guide plus Safety Mastery, the Migration Playbook, and the AGENTS.md interop handbook — is from $29: https://leanpub.com/b/cc-operators-library . The seven-book Complete Edition adds Claude Code Safety, CLAUDE.md Under Test and the free Field Manual, and through September 24, 2026 a Leanpub promotion prices it at $19.50, against $74.94 at their suggested prices bought separately (Leanpub set that promotional price, not the author): https://leanpub.com/b/cc-operators-complete/c/LeanpubAuthorUpdate20260917

Written by an independent operator who runs Claude Code autonomously and maintains cc-safe-setup, a free MIT-licensed collection of more than 900 example safety hooks: https://github.com/yurukusa/cc-safe-setup

Claude Code is powerful, and that is exactly the risk. But once the five essential hooks are in place, the incidents that keep happening are no longer Claude deleting your files. They are the guards themselves failing, usually with no error at all: a stashing hook that swallowed 3,071 entries of uncommitted work, a cost circuit breaker wired to the wrong event that read zero for months, seventeen of nineteen hooks blocking nothing on a machine without jq, and a subagent limiter that stopped the parent and never the child.

Nine chapters take you from the five essential hooks every user should install first, through Git protection, credential guards, token-spike alerts, autonomous-operation safeguards, multi-agent safety, and troubleshooting hooks that do not fire, closing with eight dated incidents and a 50-point safety audit checklist. Every hook is tested and explained.

The incidents come from one autonomous Claude Code operation running since 2026-02-15: a single operator, personal repositories, no team and no production service. For Claude Code users who want to run it safely, especially autonomously, and for teams who need consistent safety policies across contributors.

Also sold in two bundles. The four-book Claude Code Operator's Library — this book plus the Migration Playbook, the token-cost guide, and the AGENTS.md interop handbook — is from $29: https://leanpub.com/b/cc-operators-library . The seven-book Complete Edition adds Claude Code Safety, CLAUDE.md Under Test and the free Field Manual, and through September 24, 2026 a Leanpub promotion prices it at $19.50, against $74.94 at their suggested prices bought separately (Leanpub set that promotional price, not the author): https://leanpub.com/b/cc-operators-complete/c/LeanpubAuthorUpdate20260917

Written by an independent operator who runs Claude Code autonomously and maintains cc-safe-setup, a free MIT-licensed collection of more than 900 example safety hooks: https://github.com/yurukusa/cc-safe-setup

Between March and April 2026, Claude Code subscribers on the Max ($200/mo) and Pro ($20/mo) plans lived through six weeks of stacked regressions: cache TTL shortened from sixty minutes to five, a tokenizer that charged 1.35 to 1.46 times more for the same prompts, Pro access that briefly disappeared and returned forty-eight hours later with no public explanation, and a third-party tool ban.

This playbook turns that window into a decision instead of a guess. Five measurable triggers tell you which situation you are actually in.

Three paths — stay and fortify, switch, or build your own stack — are laid out with a 30-day cost projection for each. A decision tree returns one specific recommendation rather than a menu, and Chapter 9 makes that decision reversible within forty-eight hours if the output turns out to be wrong.

Edition 2 is 251 pages: ten decision-framework chapters, six path supplements, a decision tree expanded from three paths to six, and four appendices — source citations, a competitor grid, further reading, and an updates log.

Edition 1 covered the March–April 2026 regression window. Edition 2 carries it forward through the later trigger clusters — Triggers 11 to 16, including silent regression and quota burnout, claim-reality divergence, irreversible operations, and project-scoped settings as an MCP injection vector — and the June 15 billing split, with Chapter 10 on the team performance metrics that hold up under the new economics.

This book is reconstructed from public GitHub Issues, Hacker News threads, Simon Willison's measurement posts, The Register's coverage, and independent reverse-engineering. It is not affiliated with or endorsed by Anthropic.

Also sold in two bundles. The four-book Claude Code Operator's Library — this playbook plus Safety Mastery, the token-cost guide, and the AGENTS.md interop handbook — is from $29: https://leanpub.com/b/cc-operators-library . The seven-book Complete Edition adds Claude Code Safety, CLAUDE.md Under Test and the free Field Manual, and through September 24, 2026 a Leanpub promotion prices it at $19.50, against $74.94 at their suggested prices bought separately (Leanpub set that promotional price, not the author): https://leanpub.com/b/cc-operators-complete/c/LeanpubAuthorUpdate20260917

Written by an independent operator who runs Claude Code autonomously and maintains cc-safe-setup, a free MIT-licensed collection of more than 900 example safety hooks: https://github.com/yurukusa/cc-safe-setup

AGENTS.md became native in Claude Code 2.1.277 — in a project with no CLAUDE.md. That one clause is the whole remaining problem, and it is why this handbook did not become obsolete on the day the feature shipped.

Issue #6235 was the most-reacted feature request in Claude Code's history — more than 6,600 reactions — closed as completed on 2026-08-17. Chapter 9 shows what actually shipped behind that closure on 2.1.246 — not a reader, and not what the closure implies. Chapter 11 then measures the real thing on 2.1.278 across three layers: the changelog (AGENTS.md went from zero mentions to two), the shipped binary, and the running behaviour.

The answer is most of the gap closed, not all of it. The file is read only where there is no CLAUDE.md, and not yet on Bedrock, Vertex or Foundry — so what remains is exactly what bites a repository that already has a CLAUDE.md, which is every repository this handbook was written for.

The rest of your stack never had the gap, and it does not have one shape. Codex, Amp, GitHub Copilot, Cursor, Windsurf and Cline read AGENTS.md with no setup at all. Aider and Gemini CLI read it only after one config line — and a config tool with no config is quietly running on a different rule set from everything else you use.

This handbook removes the duplication tax across all nine. It gives you a verified 9-tool matrix: which file each tool reads, whether it needs setup, and the one thing to watch — checked against every tool's official documentation on 2026-06-02 and re-checked row by row on 2026-09-20.

Chapter 12 records that re-check with the source URL for every row. Five of the eight rows came back different from the June text, and three of them change what you do. Codex does not read “the nearest AGENTS.md up the tree” — it concatenates from the repo root down, and stops adding files once the combined size hits 32 KiB, so the deepest and most specific file is the one that silently never arrives. Amp never dropped AGENT.md, and reads CLAUDE.md as a fallback. Windsurf's rules documentation now lives on another domain, where the URL you had bookmarked lands on a 404.

It ranks six sync paths by trade-off: the official @AGENTS.md import, symlink, pre-commit sync, SessionStart hook, direnv, and a CI drift check. And it hands you the parts: copy-paste templates for all nine tools plus a complete repo layout, a rollback-safe migration runbook to move CLAUDE.md to AGENTS.md without losing Claude-only behaviour, and a team drift guard that makes divergence fail loudly.

49 pages, dense and practical, with free updates as conventions change — the 2.1.277 chapter and the 2026-09-20 re-check were both free updates for everyone who had already bought. Read the free sample before you buy.

Try the free AGENTS.md Setup Generator and the field-guide Gist first; buy this for the full matrix, the runbook, and the templates in one place.

Also sold in two bundles. The four-book Claude Code Operator's Library — this handbook plus Safety Mastery, the Migration Playbook, and the token-cost guide — is from $29: https://leanpub.com/b/cc-operators-library . The seven-book Complete Edition adds Claude Code Safety, CLAUDE.md Under Test and the free Field Manual, and through September 24, 2026 a Leanpub promotion prices it at $19.50, against $74.94 at their suggested prices bought separately (Leanpub set that promotional price, not the author): https://leanpub.com/b/cc-operators-complete/c/LeanpubAuthorUpdate20260917

Written by an independent operator who runs Claude Code unattended and maintains cc-safe-setup, a free MIT-licensed collection of more than 900 example safety hooks: https://github.com/yurukusa/cc-safe-setup . Independent handbook — not affiliated with Anthropic, OpenAI, GitHub, or Google.