Claude Code cost: a hard dollar cap on every session

Claude Code cost is token spend. Every request re-sends the conversation — mostly as cheap cache reads — plus whatever the model writes back, priced per model. You can watch it with /usage, and a scripted run can be stopped with --max-budget-usd. But the CLI reference marks that flag “print mode only”: an interactive session has no per-session dollar ceiling. Bulkhead adds one. Before every tool call its hook re-prices the session transcript, and once spend reaches your cap it refuses every further tool call until a human raises the number in bulkhead.yaml.

• $5default cap per session — yours to change
• $20default cap per day, per checkout
• -pthe only mode Claude Code’s own cap covers

npx @bulkheadtools/cli init

What Claude Code costs, and where you see it

Anthropic’s cost guide puts the average at about $13 per developer per active day and $150–250 per developer per month across enterprise deployments, with 90% of users under $30 an active day. The spread comes from model choice, context size and how long sessions stay open. These tools report or limit that spend, and they do different jobs:

How Bulkhead prices a session

Claude Code writes each session to a JSONL transcript, and its subagents get their own transcripts alongside it; every assistant message in any of them carries its model and token usage. On each PreToolUse and PostToolUse hook, Bulkhead reads the session transcript and its subagents’ and sums them — no estimate model, the same answer for the same files:

• Streamed messages are counted once: of the lines that share a message id, only the last — which carries the final count — is priced.
• Input and output tokens at the model’s list rate.
• Cache writes at 1.25× input for the five-minute cache and 2× for the one-hour cache (1.25× when the transcript doesn’t say which).
• Cache reads at 0.1× input, or the model’s own rate where it differs — an Opus 5.5 cache read costs $0.20 per million tokens, not $0.40 — except Mythos 5.1, priced at the default 0.1× (over-counts).
• A model id missing from the table is priced at Opus-tier rates, $5 in and $25 out per million, so an unknown model over-counts instead of slipping under the cap.

Bulkhead ships list prices for 14 model ids, matched exactly or by the longest prefix so date-suffixed ids resolve. Per million tokens:

Anthropic’s pricing page is the authority; the Mythos ids (limited availability) are in the file too. The table has one rate per model: fast mode’s premium and the 1.1× US data-residency multiplier aren’t applied, so sessions using either are under-counted. Override any model under budget.pricing.

Session and day caps

# Hard dollar caps. When crossed, every subsequent tool call is denied — the
# agent is effectively paused until a human raises the cap. Cost is a
# deterministic sum over the session transcript; no estimation model is used.
# Set to 0 to disable a cap.
budget:
  session_usd: 5      # per Claude Code session
  daily_usd: 20       # across all sessions today
  # pricing:          # optional per-model overrides (per 1M tokens)
  #   my-model: { inputPerMTok: 3, outputPerMTok: 15 }

session_usd caps one Claude Code session. daily_usd caps the sum of every session run in this checkout on this machine on today’s local date (each clone and git worktree counts on its own); the running totals live in .bulkhead/spend/. When spend reaches a cap, the budget guard denies that tool call and every one after it. That is the pause: the agent can still answer in text, but it can’t act.

What the agent reads when it tries its next tool call, and the one line you see, both from the demo:

⛔ Bulkhead blocked this action.
Guard: budget
Rule: session_usd=5
Why: Session spend $5.09 has reached the per-session cap of $5.00. Agent paused. Raise budget.session_usd in bulkhead.yaml to continue.
This is a deterministic policy check that runs outside the model and cannot be overridden by reasoning.
To proceed, a human must change bulkhead.yaml or perform this action manually.

🛡 Bulkhead paused the agent: session spend $5.09 hit the $5.00 session cap — raise budget.session_usd in bulkhead.yaml to continue (ledger #55)

The overshoot caveat

The cap is checked on every tool call, so one long model turn can overshoot before the next call is refused. In the demo the cap is $5.00 and the pause lands at $5.09: the last turn ran $0.09 past the cap before any tool call could be refused. A turn that ends in a text reply is added to the total when the agent stops, but nothing is refused until the next tool call. Set the cap a turn or two below the number you can’t exceed.

The agent can’t raise it with file tools or sed

bulkhead.yaml is on Bulkhead’s immutable protected-path list. The Edit/Write tools and the obvious shell edits (sed -i, redirects) are denied on it; a script or interpreter that writes the file isn’t — that gap is a job for a sandbox’s write rules, set up in Sandbox vs guardrails.

Per-prompt cost with bulkhead report

Every ledger entry records the session’s running total. bulkhead report takes the difference between consecutive entries and charges it to the prompt active at the later one — Claude Code sends hooks a prompt_id from v2.1.196 — then lists prompts most expensive first, with their tool calls and denials. On the session the home page’s receipt comes from:

$ bulkhead report 1
Session 7f2c1e…f3b91  2026-09-24T02:14 → 02:19
  Cost: $1.01 across 1 prompt(s)
    p-fix-…nding   $  1.01  8 tool call(s), 2 denied
  Denied: 2
    ⛔ #6 Write · protected path (.env) (protected-paths)
    ⛔ #7 Bash · force-push to a protected branch (blocked-commands)
  Evidence: file_modified×2, test_failed×1, test_passed×1, commit_created×1
  Completion checks: (1 stop(s) blocked)
    ⛔ [tests-pass] contradicted: "All tests pass"
    ✅ [tests-pass] supported: "All tests pass"
    ✅ [committed] supported: "committed"

bulkhead status shows today’s spend against the day cap, and bulkhead receipt prints spend against the cap on the receipt you paste into the PR.

ccusage and Bulkhead

ccusage is an MIT-licensed CLI that reads Claude Code’s local usage data and reports it by day, month, session and five-hour block — the quickest answer to “what did last month cost?”. Run npx ccusage@latest. It reports and doesn’t stop anything, by design. Bulkhead is the brake: a cap that pauses the agent mid-session, and a per-prompt breakdown kept in a ledger in your repo. They answer different questions and run fine side by side.

What the cap doesn’t do

• It isn’t your bill. It is a list-price sum of the token counts in the transcript; the Claude Console or your plan’s usage page is the authority.
• It only prices what reaches a transcript. Subagent spend is counted — Bulkhead sums their transcripts alongside the main session’s — but spend never written to one, such as the auto-mode classifier’s, isn’t in the sum.
• It stops tool calls, not tokens — see the overshoot caveat above.
• It works only while the hooks run. --bare skips hooks, and bypass mode isn’t supported; for unattended runs read --dangerously-skip-permissions, honestly and auto mode vs deterministic rules.
• For print-mode runs, keep --max-budget-usd as well. It is the native cap there; the two run together.

Everything else Bulkhead enforces — blocked commands, protected paths, the claim check — is in the corpus you can run yourself, and Claude Code hooks for safety explains the hook events the cap rides on.

Claude Code cost: questions