Measure Claude Code agent_summary spend on background-agent status labels
Upgrade past the cache-miss fix, turn on OpenTelemetry, group api_request events by query_source, then shrink or re-route Agent-tool subagents so status-label calls stop eating your quota.
Tools used
- Claude CodeRuns background / Agent-tool subagents that trigger agent_summary
- OpenTelemetry (Claude Code monitoring)Exports claude_code.api_request events so you can group by query_source
- Claude Code costs docsOfficial cost and background-usage notes to contrast with agent labels
Step navigator
A measured agent_summary share from your own OTel export, Claude Code ≥ 2.1.311, and a smaller bill of active Agent-tool subagents (or work moved into workflows that do not get summarized).
Developers who run Claude Code background / Agent-tool subagents and see usage limits or unexplained spend.
Before you start
On 29–30 October 2026, Flamerix AI's gist about Claude Code's agent_summary timer hit Hacker News. A Claude Code engineer (edwinarbus) confirmed the mechanism: only actively working background agents get a ~30-second summary call used for the agents-panel status label. Fleet average is about 2–6% of cost; heavy Agent-tool users measured 8–18% (and higher). Josh Builds walked through how he would check his own Mac. This guide sticks to those human sources plus the official monitoring docs. There is still no supported off switch; unofficial Bun preloads and FORK_SUBAGENT=0 trade-offs are noted as gaps, not recommended steps.
Step-by-step instructions
Upgrade Claude Code to 2.1.311 or newer
edwinarbus (Claude Code engineer on HN): a fix for the most expensive case — summaries that miss the prompt cache — shipped in 2.1.311+, and a cheaper short-notes mode is in progress. Josh Builds: "Update first. Run claude --version and move to 2.1.311 or later." His Mac was already on 2.1.312 when he wrote the piece.
claude --version
Why this works
Cache-miss summaries were the costliest slice; staying below 2.1.311 leaves that hole open.
Turn on OpenTelemetry logs for a day of real work
Josh Builds: set CLAUDE_CODE_ENABLE_TELEMETRY to 1 and send the logs exporter to your collector, or to the console for a quick look. Official docs use the same gate and show OTEL_LOGS_EXPORTER=console (or otlp) before running claude. rflcrz's August measurement instead captured raw bodies with OTEL_LOG_RAW_API_BODIES over a 4-hour, 27-subagent session — use whichever exporter you already trust; the point is to see requests that never appear in on-disk transcripts.
export CLAUDE_CODE_ENABLE_TELEMETRY=1 export OTEL_LOGS_EXPORTER=console claude
Why this works
Transcript-based cost tools miss agent_summary because those calls use skipTranscript.
Group claude_code.api_request events by query_source and find agent_summary
Josh Builds: "Group requests by query_source. Each API request event names the part of Claude Code that made it. Compare agent_summary with your main thread and subagents." edwinarbus uses the same agent_summary name in Anthropic's telemetry. rflcrz and sylvain-artois both published personal tables that isolate that source. Official docs document query_source on claude_code.api_request events. Sum cost_usd (or tokens) for agent_summary vs the rest of your session.
Why this works
Without the split you will keep blaming prompts for spend that never entered the chat.
Prefer workflows over free-form Agent-tool subagents when the work fits
jakozaur on HN: impact is "just for subagents; workflows do not seem affected," and many users on Ultracode-style workflows see less pain (~8% in his sessions). chrisvaillancourt on #86879 after reading the 2.1.312 bundle: "Workflow agents aren't summarized. Only Agent-tool subagents get the timer… Moving big scripted fan-outs into workflows avoids the cost and keeps forks."
Why this works
Same useful work without arming the 30-second status timer.
Shrink active Agent-tool fan-out and transcript size
edwinarbus: summaries apply only to actively working background agents; idle ones do not. Josh Builds: "Shrink what each agent holds. The cost tracks context size, so smaller, shorter-lived background agents are cheaper to label." sylvain-artois measured a ~380k-context generator agent paying roughly 45M cache-read tokens an hour through summary ticks alone. simon83's heavy research-subagent week landed near 16%; jakozaur's shorter-context sessions nearer 8%.
Why this works
Label cost scales with concurrent active agents and how fat each transcript is.
Put routine background agents on a cheaper model; leave the official off-switch as a gap
Josh Builds: "Pick agent models on purpose. The label runs on the agent's own model, so an Opus agent gets Opus labels. Routine background work can go to a smaller model." He also refuses the community Bun preload for teams. edwinarbus says a cheaper short-notes mode is coming; #86879 (open since August) still asks for a supported disable. Gap: there is no documented setting that turns only agent_summary off while keeping Agent-tool subagents. CLAUDE_CODE_FORK_SUBAGENT=0 stops summaries for some users by disabling fork subagents entirely — a blunt trade-off, not a surgical switch. Do not invent an off flag that does not exist.
Why this works
Cheaper agent model halves label spend without waiting on Anthropic; a real toggle is still missing.
End of guide · Reviewed Oct 30, 2026
Pro tips2
- Idle background agents do not get summaries; cost tracks active agents and transcript size.
- Workflow agents are not summarized on 2.1.312; only Agent-tool subagents arm the timer.
Common mistakes2
- Assuming the configurable status-line docs mean agent labels are free; that page is about your local statusline script.
- Installing a community Bun preload without reading it; Josh Builds would not put that on a team machine, and updates can silently undo it.
FAQ2
Is Anthropic's 2% wrong if I measured 16%?
Will CLAUDE_CODE_AGENT_PROGRESS_SUMMARIES=0 turn it off?
Related field guides.
Automate unstructured repo work with GitHub Agentic Workflows
Install gh aw, initialise the repo, have a coding agent write a Markdown workflow, compile it to lock.yml, commit both, and put a drift check in CI so you never ship Markdown without its compiled Actions file.
Grow a shared CLAUDE.md from every PR mistake
Check one CLAUDE.md into git, add a rule whenever Claude repeats a mistake, tag @claude on review to capture learnings, start in Plan mode, and give Claude a way to verify its own work.
Reduce attack surface with Claude before you chase individual CVEs
Have Claude inventory what code is reachable by default, before authentication, and under conflicting config options, then gate or feature-flag what you do not need, and prove the change with the project tests.
Ship AI-written code you can still explain: own the design, make the agent show its assumptions
Decide the abstractions yourself, pin them in a sketch or diagram, have the agent describe every change and flag what it assumed, then ask it to explain the diff before you commit.
Keep a Claude Code session running on a remote box and steer it from your phone
Run Claude Code inside tmux on a server, use mosh for flaky links, connect Remote Control so you can steer and approve from your phone, and keep your SSH keys out of the agent's reach.
Make a coding agent write the failing tests first, then implement
Split the work into separate prompts: tests only, confirm they fail for the right reason, commit, then implement without touching the tests.
Set up Claude Code hooks for formatting, tests and protected files
Add PostToolUse hooks that format and test after edits, a PreToolUse hook that blocks protected files, and a notification for long runs.
Turn a checklist you keep forgetting into a Claude Code skill
When you catch yourself re-typing the same multi-step instructions, put them in .claude/skills/<name>/SKILL.md and run them with a slash command.