CodeLedger: オープンソースのClaude Codeプラグインは、トークン使用量とバックグラウンドエージェントを追跡します

CodeLedgerの機能

CodeLedgerは、トークン使用量、プロジェクトコスト、バックグラウンドエージェントの活動を自動的に追跡するオープンソースのClaude Codeプラグイン（MCPサーバー）です。Max 20xプランで8つのプロジェクトにわたる77のClaude Codeセッションを分析した結果、バックグラウンドエージェントによる大幅なトークン消費が明らかになったことを受けて作成されました。

解決する問題

Claude Codeの組み込み/costコマンドは現在のセッションデータのみを表示します。以下の情報を確認するネイティブな方法はありません：

• プロジェクトごとの履歴
• エージェントごとの内訳
• バックグラウンドエージェントが消費しているもの
• どのタスクにどのモデルが使用されているか

ターミナルを閉じると、そのコンテキストは永久に失われます。

分析から得られた主な発見

• APIコスト相当額$2,061（77セッション、8プロジェクト）
• 最も高額なプロジェクト： サイドプロジェクトで$955相当のトークン
• 233のバックグラウンドエージェントがエージェントトークン支出の23%を消費
• 計算の57%がOpusで、ファイル検索などSonnetで十分対応可能なタスクも含む
• 1つのセッションで100以上のバックグラウンドエージェントが生成され、$80以上のトークン価値を消費

発見されたバックグラウンドエージェントのパターン

• acompact-*エージェントは、会話が長くなるとコンテキストを圧縮するために自動的に実行され、セッションで使用されているモデル（Opusを含む）を使用
• aprompt_suggestion-*エージェントはプロンプトの提案を生成し、長いセッションで頻繁に生成される
• JSONLのagentIdプレフィックスを解析しない限り、「ユーザーが要求したエージェント」と「システムのバックグラウンドエージェント」を区別するネイティブな方法はない

CodeLedgerの特徴

• すべてのセッションにわたるプロジェクトごとのコスト追跡
• どのエージェントが最も多くのトークンを消費したかを示すエージェントごとの内訳
• コーディングエージェントとバックグラウンドのacompact-*およびaprompt_suggestion-*エージェントを分離するオーバーヘッド検出
• モデル最適化の推奨事項
• 会話型クエリ — 「今週プロジェクトXにいくら使った？」と質問可能

仕組み

• SessionEndイベントにフックし、ローカルのJSONLファイルを解析
• フックがアクティブでなかったセッションをバックグラウンドスキャナーが捕捉
• すべてをローカルのSQLiteデータベース（~/.codeledger/codeledger.db）に保存 — クラウド不使用、テレメトリなし
• MCPツールを公開：usage_summary、project_usage、agent_usage、model_stats、cost_optimize

インストール方法

npm install -g codeledger

このツールはAnthropic Marketplaceの承認待ちですが、npmインストールは直接機能します。