CodeBurn 详细部署教程

CodeBurn 是一款免费、开源、本地优先的工具，用于跟踪您在 41 种 AI 编程工具和代理（如 Claude Code、Cursor、Codex、Gemini 等）上的 token 使用量和费用。它能按模型、项目和任务进行详细分解，帮助您理解并优化 AI 开发成本。

本教程将指导您完成 CodeBurn 的安装、配置和核心功能使用。

1. 准备工作

1.1 系统要求

  • Node.js：版本 22.13 或更高。
  • 支持的 AI 工具：您需要至少使用一种 CodeBurn 支持的 AI 编程工具，并且该工具已将会话数据保存在本地磁盘上（例如 Claude Code 的 ~/.claude/projects/ 目录）。
  • 可选依赖：对于 Cursor 和 OpenCode，better-sqlite3 会在首次运行时自动安装。

1.2 快速体验（无需安装）

您可以使用以下命令立即运行 CodeBurn，无需任何安装：

1
npx codeburn

该命令会打开交互式仪表板，显示您今日（或最近 7 天）的 AI 使用情况。

2. 安装 CodeBurn

2.1 全局安装（推荐）

执行以下命令进行全局安装，以便在任意目录下使用 codeburn 命令：

1
npm install -g codeburn

安装完成后，您就可以使用 codeburn 命令了。

2.2 其他包管理器

CodeBurn 也可以通过以下方式运行：

1
2
bunx codeburn
pnpm dlx codeburn

在 macOS 上，您还可以通过 Homebrew 安装：

1
brew install codeburn

3. 核心命令与基本使用

3.1 查看使用概览

运行以下命令查看当前月份的费用和 token 使用摘要：

1
codeburn overview

该命令会生成一个清晰的表格，包含总费用、token 数、按工具和模型的分解、最高消费日等。您可以通过 --from 和 --to 参数指定日期范围，或使用 -p 参数指定周期（如 week, month）。

3.2 启动交互式仪表板

直接运行 codeburn 命令即可启动功能丰富的终端交互式仪表板：

1
codeburn

您可以使用键盘方向键进行导航，按 q 键退出。仪表板会显示每日活动、项目、模型、工具和任务的详细 breakdown。

3.3 查看特定周期数据

1
2
3
codeburn today          # 查看今日数据
codeburn month          # 查看本月数据
codeburn report -p 30days  # 查看过去30天数据

4. 核心功能：优化与预算控制

4.1 分析并优化浪费 (optimize)

optimize 命令会扫描您的会话和配置，找出常见的 token 浪费模式，并给出可操作的修复建议。

1
2
3
4
5
6
7
8
# 扫描过去30天的数据
codeburn optimize

# 仅扫描今日数据
codeburn optimize -p today

# 应用修复建议（交互式）
codeburn optimize --apply

发现的浪费模式包括：重复读取文件、低读/写比、未使用的 MCP 服务器、臃肿的 CLAUDE.md 文件等。每个建议都附有预估可节省的 token 和费用。

4.2 应用与回退更改 (act)

--apply 会实际修改您的配置文件（如 CLAUDE.md、环境变量等），但所有更改都会被备份和记录。

1
2
3
codeburn act list        # 查看所有已应用的更改
codeburn act undo --last # 撤销最近一次更改
codeburn act report      # 查看预估节省与实际节省的对比

4.3 设置预算守卫 (guard)

为 Claude Code 会话设置费用上限，防止意外超支。

1
2
3
4
5
6
7
8
# 在当前项目中安装守卫
codeburn guard install

# 全局安装守卫
codeburn guard install --global

# 查看守卫状态
codeburn guard status

默认软上限为 $5（会话内警告），硬上限为 $15（自动停止会话）。

5. 桌面应用与菜单栏

5.1 菜单栏应用 (macOS / Windows / Linux)

在 macOS 和 Windows 上，您可以将 CodeBurn 固定在菜单栏或系统托盘中，随时查看费用。

1
2
3
4
5
# 启动菜单栏应用 (macOS)
codeburn menubar

# 在 Windows 上，同样的命令会安装并启动托盘应用
codeburn menubar

首次运行会下载并安装对应的桌面应用。之后，您可以在菜单栏/托盘处快速查看今日费用，并访问完整的仪表板。

Linux (GNOME)：Linux 用户可以通过 GNOME Shell 扩展获得类似体验。请参考项目 gnome/ 目录下的 README.md 进行安装。

5.2 浏览器仪表板

您也可以启动一个本地 Web 服务器，在浏览器中查看仪表板：

1
codeburn web

该命令会在 http://localhost:4747 启动一个带有图表的 Web 界面。

6. 高级功能

6.1 与 AI 代理集成 (MCP)

CodeBurn 提供了一个 MCP (Model Context Protocol) 服务器，允许 Claude Code 等代理在对话中直接查询您的使用情况。

1
claude mcp add codeburn -- npx -y codeburn mcp

之后，您可以在与代理的对话中询问“我这周 token 花在哪了？”等问题。

6.2 对比模型表现 (compare)

1
codeburn compare

该命令会交互式地对比不同模型（如 Claude Opus vs Sonnet）在您的工作负载下的一次性成功率、重试率、每次编辑成本等关键指标，帮助您选择性价比最高的模型。

6.3 追踪有效产出 (yield)

1
codeburn yield

此命令会将您的 AI 会话与 git 提交记录相关联，区分出哪些 AI 工作最终被合并到了主分支（Productive），哪些被废弃或回退（Abandoned/Reverted），帮助您评估 AI 工作的实际价值。

6.4 多设备合并

如果您在多台电脑上使用 AI 工具，可以通过 share 和 devices 命令将它们的数据合并查看。

1
2
3
4
5
# 在第二台设备上分享数据
codeburn share --pair

# 在主设备上添加
codeburn devices add

7. 配置与数据位置

7.1 配置文件

CodeBurn 的配置文件位于 ~/.config/codeburn/ 目录下。您可以手动编辑 config.json 来设置货币、模型别名等。

7.2 环境变量

您可以通过设置环境变量来覆盖某些工具的数据目录，例如：

变量 说明
CLAUDE_CONFIG_DIR 覆盖 Claude Code 数据目录
CODEX_HOME 覆盖 Codex 数据目录
OPENCODE_DATA_DIR 覆盖 OpenCode 数据目录

8. 故障排查与支持

  • 数据未显示或显示为 $0：
    • 运行 codeburn doctor 命令检查各工具的检测状态。它会明确告知您路径是否存在、会话文件是否被成功解析。
    • 检查您使用的 AI 工具是否在支持的列表中。
  • 模型名显示为 $0.00 (未定价)：
    • 如果您的模型名未被 LiteLLM 识别，可以使用 codeburn model-alias 命令为其设置别名，指向一个已知价格的模型。
    • 或者使用 codeburn price-override 手动为其设置价格。
  • 权限问题：确保 CodeBurn 有权限读取 AI 工具的本地数据目录（通常位于用户主目录下）。
  • 获取帮助：
    • 查看内置帮助：codeburn --help 或 codeburn <命令> --help。
    • 查阅项目文档：项目根目录下的 docs/ 文件夹包含更深入的指南。
    • 提交 Issue：如果遇到 bug，请在 GitHub 仓库的 Issues 中提交。

总结

通过以上步骤，您已经成功部署并可以开始使用 CodeBurn。它的核心价值在于将分散在各处的 AI 使用数据集中起来，转化为可操作的成本洞察，帮助您做出更明智的模型选择、优化工作流程，并最终控制 AI 开发成本。

建议您首先运行 codeburn overview 和 codeburn 仪表板，了解自己的费用构成。然后尝试运行 codeburn optimize，看看是否有可以立即应用的优化建议。对于团队用户，多设备合并和 MCP 集成功能将非常有价值。