Claude Code 2.1.232-2.1.312 トークン使用量とエージェントサマリーの最適化

Claude Codeのトークンオーバーヘッド問題

AnthropicのAIコーディングエージェント用コマンドラインインターフェースであるClaude Codeにおいて、ユーザーのトークン予算の約15〜20%が、ほとんど有用性のないバックグラウンドタスクに消費されていることが判明しました。具体的には、このツールはエージェントのUIパネル用に3〜5単語のステータス更新を生成するため、定期的にセッションのトランスクリプト全体をモデルに送信しています。この動作はバージョン2.1.232以降デフォルトで有効になっており、レート制限の余裕やトークンクォータを大幅に、かつ多くの場合目に見えない形で消費しています。

技術的な根本原因

30秒ごとに、バックグラウンドエージェントが agent_summary クエリを開始します。OpenTelemetryのエクスポートを分析したところ、これらのサマリーリクエストがツールによって行われる全APIコールの20%近くを占めていることがわかりました。これらのリクエストの多くはプロンプトキャッシングの恩恵を受けていますが、その頻度（リクエストの約5回に1回）が累積的に大きなコストを生んでいます。バイナリはコンパイル済みのBunバイトコードとして配布されているため、標準の設定ファイルでは、サブエージェントやフォークといったエージェントの必須機能を無効にすることなく、これらの特定のバックグラウンド呼び出しを無効にするトグルは提供されていません。

回避策の実装

これらのトークンを節約するために、サマリータイマーを担当する特定の setTimeout または setInterval 呼び出しをインターセプトするBunプリロードスクリプトが開発されました。ソーステキストのアンカーを通じてタイマーのコールバックを特定することで、このスクリプトは他のエージェント操作には影響を与えずにサマリーリクエストを効果的に抑制します。

ユーザーは、BUN_OPTIONS 環境変数をグローバルに設定して抑制スクリプトをプリロードすることで、この修正を適用できます：

export BUN_OPTIONS="--preload /path/to/no-agent-summary.js"

プリロードを適用した後、すべての有効なセッションが新しい環境を継承するように、Claude Codeデーモンを再起動（claude daemon stop --any）する必要があります。この抑制の効果は、OpenTelemetryエクスポート内の query_source を監視することで確認でき、agent_summary リクエストがゼロに減少しているはずです。

コミュニティの洞察とニュアンス

この発見をめぐる議論では、AIエージェントの設計とベンダーのインセンティブに関するいくつかの重要な視点が強調されています：

• インセンティブの不一致: コメント投稿者は、モデルプロバイダーがエージェントのハーネスも構築する場合、トークンの効率化を優先するインセンティブはほとんどないと指摘しました。あるユーザーは「モデル作成者には、効率的なトークン使用を優先するインセンティブが皆無である」と述べています。
• 検証の課題: プロンプトキャッシングがコストを軽減するかどうかを疑問視するユーザーもいましたが、独立した測定により、総トークン支出に対する15〜20%の影響が確認されています。ユーザーからは、キャッシュヒットがあっても、長時間実行されるセッションではオーバーヘッドが依然として大きいという報告が寄せられています。
• アップデートのリスク: この回避策はバイナリ内のコールバック関数にある特定の内部文字列の一致に依存しているため、Claude Codeの将来のアップデートによってフックが機能しなくなる可能性があります。ユーザーは、抑制が有効であることを確認するために、アップデートのたびにテレメトリを再検証することをお勧めします。
• 代替的な視点: 一部のユーザーは、影響は使用パターンによって異なり、「ultracode」のようなワークフローはサブエージェントを多用するタスクよりも影響を受けにくい可能性があると指摘しました。また、ツールの肥大化に対する不満を表明し、ミニマリズムが代替のコーディングアシスタントにとって重要な差別化要因であり続けるべきだと示唆する声もありました。

この回避策は現状のまま提供されており、Anthropicとは提携していません。ユーザーは、自身のワークフローにおいてこの最適化が必要かどうかを判断するために、OpenTelemetryを通じて自身のAPI使用量を監視することをお勧めします。