codeburn

CodeBurn — 查看 AI 编码开销花在哪里

CodeBurn 是一款免费、开源、本地优先的工具，可跟踪 40 种工具和 Agent（Claude Code、Cursor、Codex、Gemini、Grok、OpenCode 等）的 AI 编码 Token 用量和成本，并按模型、项目和任务细分。它会读取这些工具本来就会写入磁盘的会话文件——无需包装器、代理或 API 密钥——并根据 LiteLLM 每日刷新的定价数据为每次调用计价。四种界面（终端 TUI、浏览器仪表板、macOS 菜单栏 / GNOME 面板和 MCP 服务）都读取同一份存储在磁盘上的可信数据源。

何时使用此技能

• 快速了解“我的 AI 预算这个星期 / 月花到哪里去了？”（codeburn、codeburn overview、codeburn report）
• 在 Claude Code 配置中查找具体的 Token / 美元浪费——重复读取文件、臃肿的 CLAUDE.md、未使用的 MCP 服务、遗留的 Agent / 技能——并应用修复（codeburn optimize、codeburn optimize --apply）
• 在失控的会话开销发生前设定上限，或在会话开始时标记已知存在浪费的项目（codeburn guard install）
• 判断哪种模型在某类工作中确实物有所值（codeburn compare）
• 检查 AI 辅助完成的工作是否真正交付，还是被撤销 / 放弃（codeburn yield）
• 在对话期间向 Agent 提供实时用量 / 节省数据（codeburn mcp）
• 诊断工具显示 $0 或没有数据的原因（codeburn doctor）

何时不使用此技能

• 用户想要更改模型每次调用的费用（定价政策、速率限制）——CodeBurn 只衡量并报告开销，不会设定价格或自行限制 API 调用（guard 的上限会停止会话，但不会更改账单）
• 用户主要需要基于托管后端的云端 / 团队级开销分析——CodeBurn 的 sync 功能是一个向用户自有 URL 推送数据的遥测预览通道，并非托管式 SaaS 仪表板
• 任务与 AI 工具自身的行为 / 配置有关，与成本无关（例如，编写新的 Claude Code 技能、调试 MCP 服务的逻辑），且实际并未涉及开销 / 浪费 / Token 问题

说明

步骤 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 服务、遗留的 Agent / 技能、臃肿的 CLAUDE.md，以及价值较低但开销较高的会话。每项发现都附带预估的 Token / 美元节省额、可直接粘贴的修复方案，以及汇总为 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）会发出一次警告；硬上限（默认 $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：将用量 / 节省数据接入 Agent（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. 始终先运行 --dry-run，再运行 --apply --yes — codeburn optimize --apply 会写入实际的配置文件；请先预览计划，尤其是在非交互式／自动化流程中。
2. 信任零值前先运行 codeburn doctor — $0／空报告通常意味着路径／环境变量不匹配，而不是支出为零；doctor 为只读操作，可随时安全运行。
3. 手动编辑前先运行 codeburn act undo — 如果目标文件自应用修复后发生了更改，撤销操作会拒绝执行（除非使用 --force）；这意味着应手动检查，而不是强制执行。
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 仓库
• 支持的提供商 — 各工具的数据位置和特殊情况
• 项目规范：.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