burnmeter

burnmeter

burnmeter は、すでにお使いのマシンにあるセッションログから Claude Code のトークン使用量を分析します。JSONL セッションファイルを読み込み、すべての使用量レコードのトークン数を合計して、2 種類のレポートを出力します。合計を出力、入力、キャッシュ作成、キャッシュ読み取りに分けた内訳（効率レポート）と、モデルごとの内訳を含む全合計（内訳レポート）です。1 つのバイナリで、コマンドラインインターフェースと stdio MCP サーバーの両方を提供します。

すべての処理はローカルで行われます。ネットワークアクセスも API キーもアカウントも必要ありません。ログディレクトリは、設定されている場合は CONTEXTBURN_LOG_DIR から取得し、設定されていない場合は ~/.claude/projects が使われます。その配下にあるすべての *.jsonl ファイルを再帰的に読み込みます。

インストール

npx @reneturcios/burnmeter breakdown

または、コンテナイメージを実行します。

docker run -i ghcr.io/cloudcorprecords/burnmeter

コンテナはデフォルトで MCP サーバーとして起動します（下記参照）。CLI として使うには、CLI 引数を渡してください。コンテナはコンテナ内のログを読み込むため、実際のログに使用する場合はログディレクトリをマウントし、CONTEXTBURN_LOG_DIR をマウント先に設定してください。

CLI

burnmeter efficiency
burnmeter breakdown
burnmeter breakdown --log-dir ~/somewhere/else

burnmeter --version

どちらのレポートも JSON を出力します。--log-dir は CONTEXTBURN_LOG_DIR より優先され、CONTEXTBURN_LOG_DIR は ~/.claude/projects のデフォルト値より優先されます。終了コードは、成功時が 0、レポートの生成に失敗した場合が 1、使い方に誤りがある場合が 2 です。

内訳レポートには、logDir、filesScanned、entriesWithUsage、malformedLines、totals（4 種類のトークン数と total_tokens）、および byModel（モデルごとの同じトークン数とエントリー数。合計トークン数の降順）が含まれます。効率レポートには、同じスキャン情報と合計に加えて、shares が含まれます。各カテゴリの合計トークン数に対する割合が、小数点以下 2 桁に丸められて表示されます。

エントリーのカウント方法：有効な JSON ではない（または JSON オブジェクトではない）ログ行はスキップされ、malformedLines にカウントされます。使用量オブジェクトがトップレベル、または message の下に含まれるエントリーがカウント対象です。input_tokens、output_tokens、cache_creation_input_tokens、cache_read_input_tokens の 4 種類を合計します。フィールドが存在しない場合や数値でない場合は、0 としてカウントされます。モデルは message.model を使用し、なければトップレベルの model、それもなければ unknown を使用します。使用量オブジェクトがないエントリーは無視されます。

ディレクトリが見つからない場合や、使用量エントリーが見つからない場合も、レポートはエラーになりません。また、数値を推測して補うこともありません。合計と割合はゼロになり、使用量エントリーが見つからなかったことと、検索した場所を示す note フィールドがレポートに含まれます。

MCP サーバー

1 つのバイナリで両方の機能を提供します。mcp サブコマンドを実行すると、stdio MCP サーバーが起動します。

npx -y @reneturcios/burnmeter mcp

MCP クライアントの設定：

{
  "mcpServers": {
    "burnmeter": {
      "command": "npx",
      "args": ["-y", "@reneturcios/burnmeter", "mcp"]
    }
  }
}

デフォルト以外のディレクトリからログを読み込むには、このサーバーのクライアント設定の env に CONTEXTBURN_LOG_DIR を追加してください。

ツール

元のツールの公開仕様に記載されているとおり、どちらのツールもパラメーターを取りません。

ツール	入力	返される内容
run_efficiency	(なし)	効率レポート：合計と、各カテゴリの合計トークン数に対する割合です。
spend_breakdown	(なし)	詳細な内訳レポート：合計と、モデルごとの内訳です。

開発

npm install
npm run build   # tsc -> dist/
npm test        # node test runner over test/*.test.ts, no network (temporary fixture logs only)
npm run dev     # run the CLI from source via tsx

ライセンス

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