contextburn

contextburn は、Claude Code がすでにお使いのマシンに書き込んでいるトランスクリプトを読み取り、支払ったトークンのうち、どれだけがモデルの出力になったか、またエージェントがすでに送信したコンテキストをどれだけ再読み込みしていたかを示します。

トークンカウンターが答えるのは、「いくら使ったか？」 です。これは、「そのうちどれだけが作業だったか？」 に答えます。正規化された割合なので、セッション、モデル、作業方法をまたいで比較できます。

試してみる

cp bin/contextburn ~/bin/contextburn && chmod +x ~/bin/contextburn   # python3 only, no dependencies
contextburn detail 24

デモ

U 字曲線レポートの基になった 36 回の実行のセッションログから得た実際の出力です。マシン上のほかのデータは使用していません。DOI 付きの動画：10.5281/zenodo.22713920。実行データ自体も公開されています：Hugging Face（DOI 10.57967/hf/10366） · Kaggle · OSF（DOI 10.17605/OSF.IO/5QTWY）。

2 つの数値の理由

• トークン基準では、割合はほとんど変わりません。エージェントはステップごとに蓄積したコンテキストを再送するため、何をしても再読み込みが大部分を占めます。これはエージェントの特性を表します。
• コスト加重では、割合が変わります。キャッシュされた読み取りは、新しい入力や出力よりも大幅に安価だからです。これはセッションの実行方法によって変わり、利用者の特性を表します。

上記の比較は、データセットと分析スクリプトを伴う管理実験に基づいています：3 タスクごとにクリア：コーディングエージェントのコンテキスト経済における測定された U 字曲線。

カウント方法

• ローカルの Claude Code トランスクリプト（~/.claude/projects/**/*.jsonl）を読み取ります。データがマシンの外に出ることはありません。ネットワーク呼び出しも一切ありません。
• 使用状況レコードをメッセージ ID で重複排除し、要素ごとの最大値を保持します。ストリーミングランタイムは、同じ呼び出しについて初期スナップショットと最終レコードを書き込みます。両方を数えると二重計上になり、最初のレコードだけを保持すると出力が半分になります。
• コスト比率の重み付けには、bin/contextburn の先頭にあるモデルごとの価格を使います。価格が変更されたら、そこで更新してください。

コマンド

コマンド	表示内容
contextburn	現在トークンを消費しているもの
contextburn detail [hours]	実行効率、セッション、コンテキストを具体的に膨らませた要因
contextburn window	現在の 5 時間のサブスクリプションウィンドウ
contextburn --json	機械可読な状態（メニューバーアプリで使用）
contextburn --probe <hours>	解析済みセッションの生 JSON ダンプ
contextburn --efficiency [hours]	実行効率を JSON 形式で表示
contextburn mcp	MCP サーバーを起動

設定

設定	デフォルト	意味
CONTEXTBURN_LANG or ~/.config/contextburn/lang	en	インターフェース言語：en または ru
CONTEXTBURN_DAY_START	6	1日の開始時刻 — ここで1日の合計がリセットされます
CONTEXTBURN_WARN	30000000	メニューバーのカウンターが黄色になるトークン数／時間
CONTEXTBURN_ALARM	90000000	メニューバーのカウンターが赤色になるトークン数／時間

メニューバーアプリは Finder から起動され、環境変数が届かないため、言語ファイルが用意されています。echo ru > ~/.config/contextburn/lang を実行すると、アプリと CLI の両方が切り替わります。

MCP サーバー

エージェントがセッション中に自身の実行効率を確認できるようにします。このパッケージには、依存関係不要の MCP サーバー（stdio）が付属しており、2 つのツールを提供します。run_efficiency は割合を構造化データとして返し、spend_breakdown は詳細なレポートを返します。

claude mcp add contextburn -- uvx contextburn mcp

Claude Code プラグインとしてインストールすると、同じサーバーが登録されます。

/plugin marketplace add arsentev-ai/contextburn
/plugin install contextburn@contextburn

エディター拡張機能

• VS Code 互換エディター（VSCodium、Cursor、Windsurf、Gitpod…） — Open VSX：arsentev-ai.contextburn。ローカル CLI の使用状況をステータスバーに表示します。ソースコードは editors/vscode にあります。
• Raycast — ソースコードは editors/raycast にあります。ストアへの申請は保留中です。

メニューバーアプリ（macOS）

app/main.swift は小型のステータスバーアプリです。1 分ごとに contextburn --json をポーリングし、現在の燃焼率と時間ごとのグラフを表示します。バーをクリックすると、その時間の内訳を確認できます。

swiftc -O -o ContextBurn app/main.swift

CLI が ~/bin または通常の Homebrew パスにない場合は、CONTEXTBURN_BIN=/path/to/contextburn を設定してください。

制限事項

• 現時点では Claude Code のトランスクリプトのみが対象です。
• コスト加重の割合は、bin/contextburn の価格表が最新である範囲でのみ最新です。

引用

ソフトウェア DOI（全バージョン）：10.5281/zenodo.22712985。GitHub の 「このリポジトリを引用」 ボタンから引用情報を取得できます。メタデータは CITATION.cff にあります。

作者

Evgenii Arsentev — arsentev.ai · ORCID 0000-0002-9120-7298

このプロジェクトは初日に tokmon として公開されましたが、同名の無関係なツールとの混同を避けるため、名前を変更しました。TOKMON_* 環境変数は引き続き使用できます。

ライセンス

MIT — LICENSE を参照してください。