Claude Code's Hidden Background Agent Token Costs Explained

A background agent in Claude Code can keep working while you focus on something else. The terminal also displays short progress updates, such as Writing tool data in tools.ts, so you can tell what an agent is doing without opening its full conversation. Those updates look inexpensive, but the investigation described here found that generating them accounted for 8.2% to 12.2% of total session cost in two tests.

The surprising part is where those tokens come from. In the observed Claude Code implementation, a progress summary was generated by sending a background agent's conversation history to a model at roughly 30-second intervals. As the conversation grew, the input required to produce a few words grew with it. The resulting usage did not appear in the local conversation transcripts used by some cost-reporting tools.

This article explains how background-agent summaries work, what the tests revealed, why different users may see very different overhead, and the trade-offs of the reported workarounds.

Why a short agent summary can consume so many tokens

Claude Code can run subagents in the background using the run_in_background=true option. For a long-running task, the interface may display an automatically generated summary of the agent's current activity. This is separate from the ordinary foreground status line.

In the implementation examined in the source investigation, the summary mechanism followed a repeating pattern:

1. An active background agent accumulated messages, tool calls, and tool results.
2. Approximately every 30 seconds, Claude Code made a model request with the agent's conversation context and a prompt for a short status summary.
3. The model returned a brief description, often just three to five words.
4. The same process repeated as long as the background agent remained active.

The important difference is between the length of the answer and the amount of context used to generate it. A five-word status label may require processing thousands of input tokens. When multiple agents are running, each can create its own stream of summary requests.

This does not mean that every background task necessarily incurs the same overhead. The percentage depends on how long agents run, how their conversations grow, which model processes their summaries, and how much useful work the main task performs. Anthropic may also change the implementation between Claude Code releases.

Background-agent summaries versus the normal status line

Claude Code's main status line is a locally generated interface feature, according to the documentation referenced by the original investigation. It is not the same as the model-generated summaries attached to active background agents.

That distinction matters when interpreting usage measurements. A cost attributed to agent_summary does not imply that every piece of status information in Claude Code uses a model request.

Observing summary requests with OpenTelemetry

The investigation relied on Claude Code's OpenTelemetry support to identify model requests associated with summary generation. OpenTelemetry is a standard framework for exporting operational data, including logs and metrics, to an observability platform.

In this case, the events were exported to Better Stack, where they could be inspected by request type and compared with the cost of the wider session. The following environment-file example illustrates the telemetry configuration shown in the source material. The endpoint and token are placeholders, not working credentials.

export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_LOGS_EXPORTER=otlp
export OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
export OTEL_EXPORTER_OTLP_ENDPOINT="https://<your-otel-endpoint>.betterstack.com"
export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer <your-api-token>"

The CLAUDE_CODE_ENABLE_TELEMETRY variable enables telemetry, and the OTEL_* variables specify the exporter, protocol, destination, and authorization header. Exact export behavior and supported settings depend on the Claude Code version and the receiving service.

An environment file like this can be loaded by a shell using the following command. It is included to explain the tested environment, not as a required setup step for reading the rest of the article.

source betterstack.env

With telemetry available, the key field in the investigation was query_source. Requests marked agent_summary could be distinguished from the agent's ordinary work and measured separately.

What the two tests found

The source investigation examined a deliberately repetitive background task and a more realistic web-development task. They were not a broad benchmark across Claude Code versions or workloads, but they provide concrete examples of how summary costs can accumulate.

Test 1: A background agent running repeated sleep commands

The first experiment kept one general-purpose subagent active by giving it eight separate sleep 20 operations. Each operation generated another tool interaction, allowing the conversation history to grow during an otherwise simple task.

The prompt specified run_in_background=true and required the sleeps to execute as separate tool calls. The screenshot below preserves the exact prompt used in the original test.

The exported events showed agent_summary requests occurring approximately every 30 to 32 seconds. The debug information also indicated that the message count included in the context increased from 18 to 42 during the run. In the reported measurements, each summary request processed around 40,800 input tokens while returning only a small amount of text.

The cost attributed to summary requests was $0.0030 out of $0.0245, or 12.2% of the observed session total. The dollar amount is small because the test was small, but the fraction is meaningful: more than one-tenth of the measured cost was associated with status updates rather than the assigned task.

Test 2: A web application built with parallel agents

A second test used three background agents during a TanStack Start website-development task. Unlike the sleep experiment, the agents were carrying out a substantive development workload.

Here, agent_summary accounted for 8.2% of the total reported session cost. The investigation also observed that summary requests used the same model as the associated agent, described in the source as Opus 5.5. That made each summary potentially more expensive than one generated by a smaller model.

These figures describe the specific test sessions, not a fixed surcharge for background agents. A shorter transcript, a different model, or changes in caching and product behavior could yield different results.

Why transcript-based cost tools can miss the overhead

Claude Code stores local project conversations as .jsonl transcripts under ~/.claude/projects/. Tools that calculate usage by parsing those files can provide useful estimates of visible session activity, but they can only count the requests represented in the files they read.

The original investigation found that the agent_summary requests were present in exported telemetry but absent from those local transcripts. Its example compared 12 responses visible in the transcript with 28 requests visible in telemetry for the same session. This is a difference in which events each data source recorded, not proof that every missing request had the same token cost.

This explains why a transcript-based utility such as ccusage might report a lower number than telemetry or provider-side accounting in that version of Claude Code. Differences can also arise from token caching, pricing assumptions, billing presentation, and other API activity, so a mismatch should not automatically be assigned entirely to agent summaries.

Why published percentages differ

The source also describes higher figures reported by individual users and lower aggregate estimates attributed to Anthropic staff. These are not directly comparable without knowing their workloads and denominators.

Someone who runs background agents for much of the day is likely to see a larger percentage than someone who mostly uses short foreground prompts. The right question is not whether every user loses 8% to 20%, but how much summary generation contributes to a particular workflow.

The trade-offs of reducing summary activity

At the time of the reported investigation, the source described no dedicated official setting for disabling background-agent summaries alone. It presented two unofficial approaches, both with meaningful limitations.

Disabling forked subagents

The first approach used the environment setting CLAUDE_CODE_FORK_SUBAGENT=0 in ~/.claude/settings.json. The following snippet illustrates that configuration.

{
  "env": {
    "CLAUDE_CODE_FORK_SUBAGENT": "0"
  }
}

The reported trade-off is the loss of forked subagents, which inherit context from the parent conversation. Standard subagents begin with a more limited context supplied for their particular task. These are different collaboration patterns, not simply two names for the same feature.

The original investigation reported that disabling forked subagents also stopped the summary requests it was measuring. That behavior should be understood as version-specific and unofficial, not a documented guarantee that the setting will remain supported or preserve all other agent behavior.

Intercepting the summary timer with a preload script

A more targeted community workaround, attributed in the source to Flamerix, used Bun's preload mechanism to modify the running JavaScript environment and suppress the timer associated with summaries. In principle, this leaves forked subagent functionality available while interfering with summary generation.

There is a more serious downside: preload code executes inside the tool's runtime. A third-party script can inspect or alter process behavior, and a change in Claude Code internals can break the interception. For that reason, this approach is best understood as an unsupported experiment with security and maintenance risks, rather than a standard configuration method. The original source included an incomplete download URL, so it is not reproduced as an executable command.

What this means for Claude Code usage monitoring

The investigation raises a broader point about agent observability. A coding session can generate model traffic beyond the prompts and answers you see in a terminal transcript. Background progress generation, supporting requests, and other internal functions may matter when you are measuring actual resource use.

For usage analysis, the useful distinction is between visible transcript activity and the wider set of recorded model requests. OpenTelemetry can expose request classifications such as agent_summary in an environment that supports them, while provider-side usage remains important for understanding the final amount billed or deducted from an allowance.

The tests also illustrate a product-design trade-off. Automatically generated progress labels make long-running agents easier to supervise, but their value depends on how efficiently they are produced. Repeatedly processing a large conversation to produce a few words can be disproportionately expensive, especially when the summary uses a high-cost model.

Final thoughts

Claude Code's background-agent summaries were a measurable source of overhead in the two sessions examined, accounting for 12.2% of the small repeated-command test and 8.2% of the parallel web-development test. The most important finding is not a universal percentage. It is that a short status label can require a much larger model request than its appearance suggests.

The other lesson is about measurement. Local .jsonl transcripts did not capture the summary requests observed in the source investigation, so transcript-only cost reports could miss part of the activity. Telemetry provided the missing context, including how often the requests occurred and which model operations they represented.

The reported workarounds carry feature, compatibility, or security trade-offs, and Claude Code's behavior may change in newer releases. For teams using background agents heavily, understanding the full request stream is more valuable than assuming every visible or invisible agent action has negligible cost.

Got an article suggestion? Let us know

This work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License.