codeburn

CodeBurn — AI コーディングの費用の内訳を確認

CodeBurn は、AI コーディングのトークン使用量と費用を、40 種類のツールとエージェント（Claude Code、Cursor、Codex、Gemini、Grok、OpenCode など）にわたって追跡する、無料のオープンソースかつローカル優先のツールです。モデル、プロジェクト、タスクごとに内訳を表示します。これらのツールがすでにディスクに書き込んでいるセッションファイルを読み取るため、ラッパーもプロキシも API キーも不要です。LiteLLM の毎日更新される料金データに基づいて、すべての呼び出しの料金を算出します。ターミナル TUI、ブラウザダッシュボード、macOS メニューバー／GNOME パネル、MCP サーバーという 4 つのインターフェースが、同一のローカルデータを参照します。

このスキルを使う場面

• 「今週／今月、AI の予算はどこに消えたのか？」という質問への回答をすぐに確認する場合 （codeburn、codeburn overview、codeburn report）
• Claude Code の設定における具体的なトークンや費用の無駄（ファイルの再読み込み、肥大化した CLAUDE.md、未使用の MCP サーバー、使われていないエージェント／スキルなど）を見つけて、修正する場合（codeburn optimize、codeburn optimize --apply）
• セッション開始前に、際限のないセッション費用に上限を設けたり、無駄が確認されているプロジェクトに警告を出したりする場合（codeburn guard install）
• 特定の種類の作業で、実際に価格に見合うモデルを判断する場合（codeburn compare）
• AI を使った作業が実際に成果として反映されたのか、それとも取り消された／放棄されたのかを確認する場合（codeburn yield）
• 会話中にエージェントがリアルタイムの使用量／節約データを参照できるようにする場合（codeburn mcp）
• ツールに 0 ドルまたはデータなしと表示される原因を調べる場合（codeburn doctor）

このスキルを使わない場面

• ユーザーがモデルの呼び出しあたりの料金を変更したい場合（料金ポリシー、レート制限など）。CodeBurn は費用を測定して報告するだけで、料金の設定や API 呼び出しの制限は行いません（guard の上限はセッションを停止しますが、請求額を変更するものではありません）
• ユーザーの主な要望が、ホスト型バックエンドを使ったクラウド／チーム全体の費用分析である場合。CodeBurn の sync 機能は、プレビュー版の独自 URL へのテレメトリー送信機能であり、ホスト型 SaaS ダッシュボードではありません
• タスクが費用と無関係な AI ツール自体の動作／設定に関するもので、費用／無駄／トークンについて実際に問題になっていない場合（例：新しい Claude Code スキルの作成、MCP サーバーのロジックのデバッグ）

手順

ステップ 1：インストールせずにすぐ実行

npx codeburn                 # opens the interactive TUI dashboard, last 7 days

コマンドを恒久的に使うには、npm install -g codeburn を実行します（macOS では bunx／pnpm dlx／brew install codeburn も使用できます）。Node.js 22.13 以降が必要です。

ステップ 2：貼り付けて使えるテキストで、今月の概要を確認

codeburn overview                                    # this month, clean tables
codeburn overview --no-color                         # plain text for a PR/Slack/tweet
codeburn overview -p all                              # last 6 months
codeburn overview -p lifetime                         # full history
codeburn overview --provider claude                   # one tool only
codeburn status                                        # compact one-liner: today + month
codeburn report --format json                          # full dashboard data as JSON

ほとんどのコマンドは、--provider、--project／--exclude、期間フラグ（-p today|week|30days|month|all|lifetime）、または --from／--to を指定できます。

ステップ 3：修正を始める前に無駄を見つける

codeburn optimize                       # scan the last 30 days
codeburn optimize -p week               # scope to the last 7 days
codeburn optimize --format json         # setup health + findings as JSON

セッションと ~/.claude/ の設定をスキャンし、ファイルの再読み込み、低い Read:Edit 比率、出力に上限のない bash、未使用の MCP サーバー、使われていないエージェント／スキル、肥大化した CLAUDE.md、価値の低い高コストのセッションを検出します。検出結果にはそれぞれ、推定トークン／費用の節約額、すぐに貼り付けて使える修正案、緊急度の順位が含まれ、それらを総合して設定の健全性を A～F で評価します。

ステップ 4：安全に修正を適用し、元に戻せるようにする

codeburn optimize --apply --dry-run   # print the plan, change nothing — do this first
codeburn optimize --apply --yes       # apply every appliable fix without prompting
codeburn act list                     # every change CodeBurn has made
codeburn act undo --last              # roll the most recent change back
codeburn act report                   # realized vs estimated savings, 3+ days later

適用する変更はすべて、反映前にバックアップされ、ジャーナルに記録されます。自動処理では、--apply --yes の前に必ず --dry-run でプレビューしてください。

ステップ 5：今後の予算を管理

codeburn guard install            # hooks into this project's .claude/settings.json
codeburn guard install --global   # or into ~/.claude/settings.json
codeburn guard status             # caps, install locations, flagged projects
codeburn guard allow              # lift the hard cap for the current session only

ソフト上限（デフォルトは $5）に達すると 1 回警告し、ハード上限（デフォルトは $15）に達するとセッションを停止します。チェックポイントの通知は、一定のしきい値を超えても編集やコミットがないまま終了したセッションで表示されます。上限は ~/.config/codeburn/guard.json に保存されます。フックはフェイルオープンで動作し、フック自体のエラーによってセッションをブロックすることはありません。

ステップ 6：モデルを比較し、費用に見合う成果が出たか確認

codeburn compare --provider claude      # one-shot rate, retries, cost/edit, cache hit
codeburn yield -p 30days --format json  # productive vs reverted/abandoned spend

yield は、タイムスタンプに基づいてセッションと git コミットを照合します。実行するには、git リポジトリ内にいる必要があります。

ステップ 7：エージェントに使用量／節約データを連携（MCP）

claude mcp add codeburn -- npx -y codeburn mcp

stdio 経由で get_usage（ツール／モデル／プロジェクト／タスクごとの高速な内訳）と get_savings（無駄の検出結果、再試行コスト、ルーティングの無駄）を提供します。CLI と同じローカルデータを読み取ります。呼び出し元が include_project_names: true を指定しない限り、プロジェクト名は仮名化されます。

ステップ 8：$0 またはデータなしと表示されるツールを診断する

codeburn doctor                     # every provider, human-readable
codeburn doctor --provider opencode # diagnose one provider
codeburn doctor --json              # machine-readable

完全にオフラインで読み取り専用です。プローブした正確なパス（CLAUDE_CONFIG_DIR／CODEX_HOME などの環境変数による上書きを含む）、解析したセッション数、プロバイダーごとの1行の判定を表示します。

ベストプラクティス

1. 必ず --apply --yes の前に --dry-run を実行してください — codeburn optimize --apply は実際の設定ファイルに書き込みます。特に非対話型／自動化されたフローでは、先に計画をプレビューしてください。
2. ゼロを信用する前に codeburn doctor を実行してください — $0／空のレポートは通常、支出がゼロなのではなく、パス／環境変数の不一致を意味します。doctor は読み取り専用で、いつでも安全に実行できます。
3. 手動編集する前に codeburn act undo を実行してください — 修正適用後に対象ファイルが変更されている場合、--force を指定しない限り undo は拒否します。これは、強制実行するのではなく手動で確認すべき合図です。
4. ガードの上限はデフォルトでソフト上限です — 実際にセッションを停止するのはハード上限（デフォルトは $15）です。厳格な予算上限として頼る前に、guard status の両方の上限を確認してください。
5. yield には git リポジトリが必要です — スクラッチ／一時ディレクトリではなく、プロジェクトディレクトリから実行してください。そうしないと帰属情報が空になります。
6. スクリプトでは --format json を優先してください — report、today、month、status、optimize、export -f json、yield はすべて構造化された JSON 出力に対応しています。色付きの TUI／テーブル出力をスクレイピングしないでください。
7. sync はプレビュー段階です — スクリプトから利用する場合、codeburn sync（チームのテレメトリー送信）は安定した統合インターフェイスではなく、進化中のプロトコルとして扱ってください。

参考資料

• references/commands.md — ワークフローの段階別にまとめたコマンドリファレンス
• CodeBurn GitHub Repository
• 対応プロバイダー — ツールごとのデータ保存場所と注意事項
• プロジェクト標準：.agent-skills/skill-standardization/SKILL.md

例

例 1：今週の Claude Code 環境で無駄を見つけて修正する

codeburn optimize -p week
codeburn optimize --apply --dry-run
codeburn optimize --apply --yes
codeburn act report

例 2：暴走したセッションに上限を設定し、出荷内容を確認する

codeburn guard install --statusline
# ...work happens...
codeburn yield -p 30days