Reduce token usage in Claude Code by disabling unnecessary background status updates.
As users increasingly delve into the mechanics behind AI tools like Claude Code, understanding token management becomes crucial. Recent evaluations have revealed a repetitive activity occurring within Claude Code that consumes between 15–20% of user tokens due to frequent status line updates. This article explores how to disable this function effectively.
For every background agent in Claude Code, a status update occurs every 30 seconds. This process prompts Claude Code to send the agent's entire transcript to its corresponding model, typically Opus, inquiring about the agent's latest action. The result, conveyed in a concise 3-to-5 word description, updates the agent's panel status but does not enrich the main conversation stream.
Detecting this issue required careful scrutiny of OpenTelemetry data. The analysis showed disproportionately high costs associated with agent summaries compared to typical conversational requests. This led to an extensive investigation yielding critical findings: disabling these status updates can markedly conserve valuable tokens.
To quell this unnecessary token drain, users can leverage a script named no-agent-summary.js, designed to intercept and suppress the status update calls. Installation is straightforward; however, there are essential nuances to remember to ensure its effectiveness.
The script functions by observing the setTimeout and setInterval functions, returning a neutral handle when encounters a callback associated with agent summaries. It ensures that only non-essential timer callbacks are affected, allowing the rest of the timeline to operate normally. This selective suppression is integral to maintaining system performance while cutting back on token usage.
After obtaining the no-agent-summary.js script—a compact file with approximately 80 lines of code—users should place it in a stable, accessible directory. To enact this, the script's absolute path needs to be specified, and then global environment options should be set for all Claude Code processes.
Users can achieve this execution through the following commands:
BUN_OPTIONS="--preload path/to/no-agent-summary.js" CC_AGENT_SUMMARY_LOG=/tmp/summary_log claude --version
Initially, it’s essential to halt the Claude Code daemon to apply the changes correctly:
claude daemon stop --any
Subsequently, users can validate their setup's efficacy by examining the log file generated by the preload script.
Each time Claude Code receives an update, it could inadvertently undo previously established changes, making verification a continual necessity. Users should check that their designated log file showcases evidence of the status updates being suppressed.
One effective method to confirm operational success is to initiate a background agent for a duration of one to two minutes, confirming that the log reflects the absence of any agent summary updates. A successful suppression will ensure that the query_source for agent summaries remains at zero.
Failure to maintain the script may result in reactivating the summary requests, consequently leading to undesired token usage. Hence, adopting a systematic approach to monitoring changes and evaluating system performance is paramount.
Claude Code recipients should familiarize themselves with potential implications stemming from running the no-agent-summary.js script, especially in relation to updates and daemon instances. If the environment settings are not properly configured before the daemon initiates, new processes might inherit prior, unchanged parameters.
This is particularly relevant for headless runs, where environments must be aligned with the code alterations. Various instances, including cron jobs and continuous integration (CI) configurations, necessitate awareness of their inherited environment to avoid inadvertent processes that could negate the script’s impact.
One pressing question persists within the Claude Code community: why isn't there a built-in setting to disable the agent summary feature? Since its introduction with version 2.1.232, the summary feature has been defaulted to "on" for interactive background agents. Inquiries reveal that while some settings can be manipulated, the summary request is intrinsically tied to the server's operational parameters.
With evolving implementations, the complexity surrounding background requests and their inherent use of tokens has grown. Official documentation has not comprehensively addressed this issue, leaving many users to rely upon third-party scripts and community-led innovations.
As AI tools like Claude Code evolve, greater attention must be paid to the token economy surrounding them. Currently, an emerging cost structure has been observed as users transitioned from version 2.1.32 to 2.1.310, where weekly token consumption from summary requests increased significantly, correlating with the implementation of the new updates.
Moving forward, it will be essential for users to remain vigilant regarding updates and community discussions. Engaging actively with community-approved scripts and tools may provide the leverage necessary to optimize interactions.
The status update in Claude Code uses around 15–20% of user tokens for each background agent request.
While there isn't a built-in feature to turn off agent summaries, you can utilize the no-agent-summary.js script to suppress these updates effectively.
After each update, it’s crucial to verify that your preload script is still functioning by checking the specified log file for any suppressed agent summary requests.