/t · guide · runtime token cost

A Claude Code background worker is cheap to start and expensive to watch

Matthew Diakonov, Written with AI

Published May 18, 20266 min read

If you searched for what a background worker costs, you probably found the reassuring number first. Anthropic's cost docs have a short section called "Background token usage" that says background functionality, the jobs that summarize old conversations for claude --resume and the requests behind commands like /usage, consumes "a small amount of tokens (typically under $0.04 per session)". That is true. It is also not the background worker that shows up on your weekly limit on a Wednesday.

The background worker that costs you is the one you started on purpose: a dev server you keep running, a test suite you launched with run_in_background so you would not have to wait, a subagent doing slow research. The rest of this page is about that worker, and the one number that actually prices it.

Two numbers, three orders of magnitude apart

The official idle figure and the cost of a worker you watch are not the same kind of number. One is a fixed, tiny per-session constant. The other is a rate: it multiplies by how long you keep the worker visible.

$0Anthropic's idle background jobs, per session

0tokens in a typical mid-size CLAUDE.md

$0per-turn floor for that file, Opus 4.7 input rate

0xthat floor, for a worker alive 14 turns

Per-turn floor uses the same math ccmd's analyzer uses: file token count multiplied by $15 per million (Opus 4.7 input). It is a cold-read upper bound; prompt caching pulls the realized number down, but the turn count is the lever either way.

The mechanic: every turn the worker is alive is a turn you pay for

Here is what most cost guides skip. A background worker does not bill you for running. It bills you for being visible. The moment you launch a Bash command with run_in_background=true, Claude Code starts attaching a status reminder to your context. While the shell is alive, every single turn carries a Background shell N is still running note. And that note rides alongside everything else in your context that fires every turn, including your full CLAUDE.md.

what a live background worker adds to every turn

Drawn out as a sequence, the shape is obvious: the worker runs once, but the model is re-invoked on every turn that overlaps with it, and each of those re-invocations replays your config.

a background test run, turns 7 through 9

Three turns, three full reads of your CLAUDE.md. The worker did its job exactly once. If you keep working while it runs, which is the whole reason you backgrounded it, every turn of that work inherits the per-turn floor plus the reminder. A worker alive across 14 turns means 14 reads of the file. That is the 0x in the metrics above.

The number that prices the turn lives in ccmd's analyzer

ccmd's analyzer is a set of pure functions in src/lib/analyzer.ts. When you paste a CLAUDE.md, AGENTS.md, .cursorrules, or .grokrules file into the box on ccmd.dev, it computes one value that is the entire point of this page:

src/lib/analyzer.ts

Line 264 is the assumption that matters: estimatedTokensFireEveryTurn is set to the file's entire token count. The analyzer assumes your whole CLAUDE.md is in context on every turn, because for most files it is. That is your per-turn floor. A background worker does not touch that number. It multiplies the turns over which you pay it. The analyzer's session estimate assumes 30 turns; a long session babysitting a background worker can run far past that, and the cost climbs in lockstep.

11.6x

“Each system-reminder costs ~2,500-4,000 tokens, reminders accumulate linearly, and by exchange 10 a session burned ~581K tokens instead of a normal ~50K. Closed bug anthropics/claude-code#11716, 'Background Bash Processes Cause Infinite System-Reminders and Token Exhaustion'.”

GitHub issue anthropics/claude-code#11716

That 11.6x is the documented worst case, not the normal one. It came from a specific bug, now closed as not planned, where the "still running" reminders kept multiplying even after the process was killed. The everyday version is calmer: one reminder per turn, not three, six, nine. But it shows the failure mode in sharp relief. When a background worker costs you, it always costs you the same way, in extra context replayed on every turn, never in the worker itself.

Not all background workers cost the same

"Background worker" covers four different things in Claude Code, and they sit on a cost ladder. The cheapest is Anthropic's own idle plumbing. The most expensive is a fan-out of agent teammates, each carrying its own copy of your config.

Feature	Cost shape	What it adds per turn
Idle background jobs (summarization, /usage checks)	Under $0.04 per session, per Anthropic's cost docs	Not your problem. Leave it.
Background Bash task (run_in_background dev server, tests, build)	One "still running" reminder per turn it stays alive	Every alive-turn re-bills your full CLAUDE.md
Background subagent (Agent tool, run_in_background)	Loads CLAUDE.md once on spawn, then runs its own turns	Its turns + the parent's wake-up turns, both at the floor
Agent team teammates	Roughly 7x a standard session, per Anthropic's cost docs	Each teammate carries its own CLAUDE.md, every turn
Misfiring reminder loop (closed bug #11716)	~581K tokens in 10 exchanges, 11.6x normal	Pathological. Avoid run_in_background until patched.

Per-turn floor and 7x agent-team figure are cold-read upper bounds; prompt caching reduces realized cost. Turn count, which caching does not change, is the lever you control.

The background subagent line is the one to watch. A background Bash task is a dumb process: it cannot read your CLAUDE.md, it just runs. A background subagent is a second Claude instance. Per Anthropic's cost docs, a spawned agent loads CLAUDE.md, MCP servers, and skills automatically at the start, then runs its own turns. You pay the per-turn floor inside the subagent and again in the parent every time it reports back. If your config is fat, a background subagent pays that tax twice.

Four ways to make the watching cheap

You do not fix this by avoiding background workers. You fix it by making the turns they add cost less, and by adding fewer of them.

cut the background-worker tax

Trim the CLAUDE.md first. The per-turn floor is the file. Cut 6,000 tokens to 2,500 and every wake-up turn gets 58% cheaper, background worker or not.
Prefer foreground with a high timeout for short jobs. Bash(timeout=300000) blocks but never auto-backgrounds, so it never injects a per-turn reminder.
Batch your background checks. Do not poll a worker every turn. Start it, do unrelated work, read its output once near the end. Fewer alive-turns, fewer re-bills.
Kill workers you stopped caring about. A finished-but-unread background shell can keep its reminder alive. KillShell ends the per-turn tax.

The first one does the most work. The per-turn floor is your CLAUDE.md. Background workers, parallel subagents, long sessions, every one of them multiplies that floor by some turn count you do not fully control. The token count of the file is the one variable you do control. A 6,000-token file trimmed to 2,500 makes every wake-up turn 58% cheaper, and it does that for free, today, without changing how you use background workers at all.

Watching a background worker eat your weekly limit?

Bring your CLAUDE.md and a session that ran long. We will find the lines firing on every turn and the ones safe to cut.

Background worker token cost, answered

Frequently asked questions

How much does a Claude Code background worker cost in tokens?

Two very different numbers. Anthropic's built-in idle background jobs (conversation summarization for claude --resume, and status checks like /usage) cost under $0.04 per session, per Anthropic's own cost docs. That is the number people quote and it is genuinely small. A background worker you start and watch, a detached dev server, test run, or build launched with run_in_background, costs more, and the cost is not the worker. It is the turns. Every turn the worker stays alive, Claude Code carries a 'still running' system-reminder and re-processes your entire CLAUDE.md. A 6,000-token CLAUDE.md prices a turn at roughly $0.09 at Opus 4.7 input rates. A worker alive across 14 turns means you paid that floor 14 times, about $1.26, before counting the actual work in those turns.

Does run_in_background save tokens compared to a foreground command?

No. It saves wall-clock time, not tokens, and it can cost more. A foreground Bash command blocks: Claude waits, the command finishes, you get the output once, in one turn. A background command returns control instantly, which is the point, but it then stays visible. While the shell is alive, Claude Code injects a 'Background shell N is still running' reminder into every turn. If you do ten turns of other work while a background test runs, all ten turns carry that reminder and re-bill your CLAUDE.md. The foreground version paid for the file once. Background trades latency for turn count.

Why does my token usage climb while a background task just sits there running?

Because a background task that 'just sits there' is not idle from the model's point of view. Every message you send while it runs is a fresh turn, and Claude Code rebuilds the context for that turn: the system prompt, your CLAUDE.md, installed skill descriptions, MCP tool names, plus the 'still running' reminder for the live shell. The worker's own CPU time is free to the token meter. The context you replay around it is not. ccmd's analyzer prints exactly that replayed number: in src/lib/analyzer.ts, estimatedTokensFireEveryTurn is set to your file's full token count, on the assumption the whole file fires every turn. A background worker does not lower that floor. It just adds turns over which you pay it.

What is the worst-case cost of a background worker?

A documented failure mode, not the normal case. GitHub issue anthropics/claude-code#11716, titled 'Background Bash Processes Cause Infinite System-Reminders and Token Exhaustion' and closed as not planned, reports that run_in_background could trigger system-reminders that kept appearing even after the process was killed. The reporter measured stray reminders at 2,500 to 4,000 tokens each, accumulating linearly, so a 10-exchange session burned roughly 581K tokens instead of a normal 50K, an 11.6x blowup. That is pathological and tied to a specific bug. But it shows the shape of the risk: when a background worker misbehaves, the cost is paid in extra context on every turn, not in the worker.

Does a background subagent cost the same as a background Bash task?

No, it is worse, because a subagent runs its own turns. A background Bash task is a dumb process: it produces output, Claude reads it. A background subagent (the Agent tool with run_in_background) is a second Claude instance. Per Anthropic's cost docs, a spawned agent loads CLAUDE.md, MCP servers, and skills automatically at the start, then runs many turns of its own, each re-billing that context. Meanwhile the parent session keeps getting wake-up turns when the subagent reports progress or completes. You pay the floor inside the subagent and again in the parent. Agent teams are the extreme of this: the docs put teammates at roughly 7x a standard session.

How do I find my own per-turn CLAUDE.md cost?

Paste the file into the analyzer on ccmd.dev. It runs in the browser, no signup, and reports totalTokens at the chars / 4 heuristic every CLI uses, then prints estimatedTokensFireEveryTurn, which is the number a background worker multiplies. Multiply that token count by $15 per million (Opus 4.7 input) to get your per-turn floor in dollars, then by the number of turns a typical background worker stays alive in your sessions. After the fact, ccusage (the open-source CLI) shows input tokens per turn so you can confirm the climb while a worker runs. The analyzer tells you the price before you pay it; ccusage confirms it after.

Should I stop using background workers?

No. Background workers are the right tool for genuinely long jobs: a dev server you keep alive for an hour, a multi-minute build, a test suite you do not want to block on. The fix is not to avoid them, it is to make the turns they add cheap. Trim your CLAUDE.md so the per-turn floor is small, prefer foreground with a high timeout for jobs under a few minutes, and do not poll a live worker every single turn. A lean CLAUDE.md plus disciplined polling turns the background-worker tax from real money into rounding error.

Measure your per-turn floor before the next long session

You cannot control how many turns a background worker stays alive. You can control what each of those turns costs. Paste your CLAUDE.md, AGENTS.md, .cursorrules, or .grokrules into the box on ccmd.dev. It runs in your browser, no signup, and reports the token count a background worker multiplies, the lines bloating it, and the installable skills that would replace them. The number it prints is the price of one turn. Background workers just tell you how many turns you bought.