Token Budgets

The cost-control layer the CLI is missing

Most CLI operators assume they spend less than a developer running production API calls. Plausible, and frequently wrong. Context accumulates across tool calls within a session, file reads and search results add tokens the model processes again on every turn, and an overnight pipeline on a cron schedule can exhaust a weekly quota in a single run that finishes with clean logs the whole time.

The cost data is already there. Claude Code emits token counts and model identifiers, and the API logs hold everything needed to reconstruct what a session spent. The friction is that checking means opening a separate console and converting tokens to dollars by hand, so most operators delay until the quota spikes. This book moves cost visibility into the workflow itself and bounds it.

Seven pieces of a cost-control stack

• cli-vs-api-cost — Why CLI cost differs from API cost, and a comparison table that makes the distinction concrete. Context window size and model tier are the two primary levers a CLI operator actually controls; pipeline design shapes how both get used.
• session-cost-log — session_cost_log.jsonl and log_session_cost.py, the script that populates it from completed sessions. Once it exists, “what did that session cost?” takes seconds instead of a console filter.
• precompact-cost-gate — The PreCompact hook that fires as context approaches the window limit, repurposed as the decision point for whether a session continues or stops. Ships a baton schema with a cost-gate field and cost_gate_check.py.
• model-routing — A router that selects by task type and context size. Haiku handles lookups, Sonnet covers most analysis and writing, and Opus comes in when context exceeds a threshold or the task calls for deep architectural reasoning. The router kills the silent Opus-for-everything premium.
• budget-gates — budget_gate.py with a hard stop that halts execution at the cap and a soft warning that fires before it, both set in budget_config.json. The hard stop is what the overnight pipeline needed.
• per-project-budgets — project_budget.json and budget_allocator.py, so one runaway job drains only its own allocation rather than the quota for everything else.
• cost-aware-pipeline — cost_aware_pipeline_template.md, an annotated design checklist that codifies the decisions each chapter introduces into a structure you apply to every pipeline you build.

A preview

A pipeline that fires on a cron schedule and processes a queue past a budget threshold can exhaust a weekly quota in a single run. Morning arrives and the quota is gone. The pipeline finished cleanly — the log shows success on every task — but cost ran freely the entire time.

A pipeline that defaults to Opus for every task because Opus gives better results on complex reasoning will pay that premium on lookups and routine formatting passes as well. The premium accumulates invisibly until the bill arrives.

CLI operators who want spend visible and bounded

Standalone — no prerequisites. Claude Code CLI operators who want real visibility and control over what their sessions spend. If you came here for API-level prompt caching, that lever lives in the SDK and the Anthropic API reference covers it in full; the levers in this book operate at the session and pipeline level, where a CLI operator actually has the controls.

A longer excerpt is available to newsletter subscribers.

Buy Ebook on Amazon  Buy Paperback on Amazon