getagentseal--codeburn/README.md

<!-- WEHUB_ZH_README -->
> [!NOTE]
> 本文档由 WeHub 基于上游 README 翻译整理，属于社区翻译，非官方中文文档。  
> [English](./README.en.md) · [原始项目](https://github.com/getagentseal/codeburn) · [上游 README](https://github.com/getagentseal/codeburn/blob/HEAD/README.md)  
> 原作者、版权与许可证归属以原始项目及本仓库 LICENSE 文件为准。

<p align="center">
  <a href="https://claude.com/open-source-max"><img src="https://img.shields.io/badge/Claude_for_Open_Source-Recipient-da7756?style=for-the-badge&labelColor=1a1a1a" alt="Claude for Open Source Recipient" /></a>
</p>

<p align="center">
  <img src="https://raw.githubusercontent.com/getagentseal/codeburn/main/assets/providers.png" alt="CodeBurn" width="420" />
</p>

<p align="center"><strong>看清你的 AI 支出都花在了哪里。</strong></p>

<p align="center">
    <a href="https://www.npmjs.com/package/codeburn"><img src="https://img.shields.io/npm/v/codeburn.svg?color=F97316" alt="npm version" /></a>
    <a href="https://www.npmjs.com/package/codeburn"><img src="https://img.shields.io/npm/dt/codeburn.svg?color=F97316" alt="total downloads" /></a>
    <a href="https://github.com/getagentseal/codeburn/blob/main/LICENSE"><img src="https://img.shields.io/npm/l/codeburn.svg?color=F97316" alt="license" /></a>
    <a href="https://github.com/getagentseal/codeburn"><img src="https://img.shields.io/badge/node-%3E%3D22-F97316.svg" alt="node version" /></a>
    <a href="https://discord.gg/w2sw8mCqep"><img src="https://img.shields.io/badge/discord-join-F97316?logo=discord&logoColor=white" alt="Discord" /></a>
    <a href="https://x.com/_codeburn"><img src="https://img.shields.io/badge/%40__codeburn-F97316?logo=x&logoColor=white" alt="Follow @_codeburn on X" /></a>
    <a href="https://github.com/sponsors/iamtoruk"><img src="https://img.shields.io/badge/sponsor-♥-F97316?logo=github" alt="Sponsor" /></a>
</p>

**CodeBurn 是一款免费、开源、本地优先（local-first）的工具，可追踪 32 款工具与智能体（Claude Code、Cursor、Codex、Gemini、Grok 等）的 AI 编程 token 用量与费用，并按模型、项目和任务细分。**

你为 Claude、Codex、Cursor 以及一整套其他 AI 工具付费。账单只告诉你总额，却从不告诉你其中一半花在了对话而非代码上，也不告诉你某款昂贵模型把预算烧在了更便宜的模型一次就能搞定的工作上。

CodeBurn 可以。它读取你的工具已经写入磁盘的会话文件，按**任务、模型、工具、项目**细分每一笔 token 和美元，覆盖 **32 款 AI 工具**。

一切都在本地运行。无需包装器、无需代理、无需 API 密钥，数据不会离开你的机器。定价来自 [LiteLLM](https://github.com/BerriAI/litellm),)，每日刷新。

<p align="center">
  <img src="https://raw.githubusercontent.com/getagentseal/codeburn/main/assets/dashboard.jpg" alt="CodeBurn TUI dashboard" width="760" />
</p>
<p align="center"><em>你使用的所有工具，一周数据，一屏呈现。</em></p>

<p align="center">
  <a href="#quick-start">快速开始</a> ·
  <a href="#find-and-fix-waste">发现浪费</a> ·
  <a href="#apply-fixes-undo-anytime">应用修复</a> ·
  <a href="#guard-your-budget">预算守护</a> ·
  <a href="#compare-models">对比模型</a> ·
  <a href="#track-what-shipped">追踪交付成果</a> ·
  <a href="#codeburn-in-your-agent-mcp">MCP</a> ·
  <a href="#supported-tools">支持的工具</a> ·
  <a href="#commands">命令</a> ·
  <a href="#features">功能</a> ·
  <a href="#how-it-reads-your-data">数据读取方式</a>
</p>

## 快速开始

**即刻运行**，无需安装：

```bash
npx codeburn
```

这会打开交互式仪表盘（默认显示最近 7 天）。方向键切换时间段，`q` 退出。这就是 30 秒版本。你现在就知道 AI 预算花在了哪里。

**安装**以获得持久的 `codeburn` 命令：

```bash
npm install -g codeburn
```

也可通过 `bunx codeburn`、`dx codeburn` 运行，或在 macOS 上使用 `brew install codeburn`。

**菜单栏应用**（macOS），让你的支出始终显示在菜单栏中：

```bash
codeburn menubar
```

在 Linux 上，GNOME Shell 扩展提供同样的面板视图；参见 [Linux (GNOME)](#linux-gnome)。

需要 **Node.js 22.13+**，且至少有一款支持的工具在磁盘上有会话数据。对于 Cursor 和 OpenCode，`better-sqlite3` 会自动安装。

## 纵览你的月度支出

```bash
codeburn overview                                    # this month, clean tables
codeburn overview --no-color                         # plain text, ready to paste
codeburn overview --from 2026-06-01 --to 2026-06-15  # any date range
codeburn overview -p all                             # all time
codeburn overview --provider claude                  # one tool only
```

`codeburn overview` 会打印一份可复制粘贴的 AI 支出摘要：总计（费用、token、缓存命中）、按工具与热门模型的细分、价值最高的日期、主要项目、按日表格，以及活动与工具使用情况。可管道输出到任意位置（`pbcopy`、PR、Slack 或推文）；当输出目标不是终端时颜色会自动去除，也可传入 `--no-color`。

```text
CodeBurn  June 2026

Totals
  Cost       $2,795.10
  Tokens     3.49B   in 23.9M / out 20.2M / cache-w 72.5M / cache-r 3.38B
  Calls      14,755   sessions 753
  Cache hit  99.3%

By tool
┌──────────┬───────────┬────────┬───────┐
│ Tool     │      Cost │ Tokens │ Share │
├──────────┼───────────┼────────┼───────┤
│ claude   │ $2,662.37 │  3.34B │   95% │
│ codex    │   $119.12 │ 128.1M │    4% │
└──────────┴───────────┴────────┴───────┘

(plus Top models, Highest-value days, Top projects, a per-day table, By activity, and Tools)
```

## 发现并修复浪费

```bash
codeburn optimize                       # scan the last 30 days
codeburn optimize -p today              # today only
codeburn optimize -p week               # last 7 days
codeburn optimize --provider claude     # restrict to one provider
codeburn optimize --format json         # setup health + findings as JSON
```

`codeburn optimize` 会扫描你的会话以及 `~/.claude/` 配置，查找浪费模式：

- Claude 跨会话重复读取的文件（相同内容、相同上下文，一遍又一遍）
- 低 Read:Edit 比率（不读就改会导致重试和 token 浪费）
- 浪费的 bash 输出（未设上限的 `BASH_MAX_OUTPUT_LENGTH`、尾部噪声）
- 未使用的 MCP 服务器仍在每个会话中支付工具 schema 开销
- 在 `~/.claude/` 中定义但从未调用的幽灵智能体、技能（skills）和斜杠命令
- 臃肿的 `CLAUDE.md` 文件（已计入 `@-import` 展开）
- 缓存创建开销和垃圾目录读取
- 上下文繁重的会话，有效输入/缓存 token 淹没输出
- 可能价值偏低的昂贵会话：未观察到编辑轮次或重复重试，且未见 `git`/`gh` 交付命令

<p align="center">
  <img src="https://raw.githubusercontent.com/getagentseal/codeburn/main/assets/optimize.jpg" alt="CodeBurn optimize" width="760" />
</p>

每条发现都会显示预估的 token 与美元节省，以及可直接粘贴的修复方案：一行 `CLAUDE.md`、环境变量，或用于归档未使用项的 `mv` 命令。发现按紧急程度排序（影响与已观察浪费加权），并汇总为 A 到 F 的配置健康评级。重复运行会将每条发现归类为新增、改善或已解决（对照最近 48 小时窗口）。

你也可以从仪表盘内联打开：当状态栏出现发现计数时按 `o`，按 `b` 返回。

## 应用修复，随时撤销

```bash
codeburn optimize --apply             # review and apply fixes interactively
codeburn optimize --apply --dry-run   # print the plan, change nothing
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
```

`codeburn optimize` 发现浪费；`--apply` 为你修复配置类发现：设置值、环境变量、归档未使用的智能体与技能。每次变更在生效前都会备份并记入日志。`codeburn act list` 显示历史，`codeburn act undo <id>` 恢复原始文件（若文件自应用后已变更则拒绝恢复，除非你传入 `--force`）。

闭环讲求诚实：一旦某次应用的修复已满 3 天，`codeburn act report` 会将其预估节省与实际会话表现对比；后续 `codeburn optimize` 运行会在页眉显示已实现数字。预估会与现实核对，而不只是宣称。

## 守护你的预算

```bash
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 uninstall          # removes cleanly, leaves your own hooks alone
```

Guard 会向 Claude Code 安装可选的 hooks，在你工作时监控会话成本：

- **软上限**（Soft cap，默认 $5）：会话超过该值时，在会话内发出一次性警告。
- **硬上限**（Hard cap，默认 $15）：终止会话；`codeburn guard allow` 可仅对该会话解除限制。
- **检查点**（Checkpoint，默认 $3）：若会话结束时已超过该阈值且没有任何编辑或提交，会提示你以明确的交付物重新开始。
- **会话开场提示**（Session openers）：optimize 发现浪费的项目，在会话开始时会显示一行标记。

上限在 `~/.config/codeburn/guard.json` 中编辑（将值设为 `null` 可禁用它）。添加 `--statusline` 可在 Claude Code 状态栏显示会话成本。安装会与其他组件一样写入同一日志，因此 `codeburn act undo` 也会一并移除它们。Hooks 采用 fail open 策略：即使 Guard 损坏，也不会阻断会话。

## 对比模型

```bash
codeburn compare                        # interactive model picker (default: last 6 months)
codeburn compare -p week                # last 7 days
codeburn compare -p today               # today only
codeburn compare --provider claude      # Claude Code sessions only
```

哪种模型更适合*你的*工作？在仪表板中按 `c`，或运行 `codeburn compare`。方向键切换时段，`b` 返回。

<p align="center">
  <img src="https://raw.githubusercontent.com/getagentseal/codeburn/main/assets/compare.jpg" alt="CodeBurn compare" width="760" />
</p>

| 板块 | 指标 | 衡量内容 |
|---------|--------|-----------------|
| 性能 | 一次成功率 | 无需重试即成功的编辑 |
| 性能 | 重试率 | 每次编辑轮次的平均重试次数 |
| 性能 | 自我纠正 | 模型自行纠正错误的轮次 |
| 效率 | 每次调用成本 | 每次 API 调用的平均成本 |
| 效率 | 每次编辑成本 | 每次编辑轮次的平均成本 |
| 效率 | 每次调用输出 token 数 | 每次调用的平均输出 token 数 |
| 效率 | 缓存命中率 | 来自缓存的输入占比 |

还会对比各类别的一次成功率、委派率、规划率、每轮平均工具调用数，以及 fast mode 使用情况。

## 追踪实际交付

```bash
codeburn yield                  # last 7 days (default)
codeburn yield -p today         # today only
codeburn yield -p 30days        # last 30 days
codeburn yield -p month         # this calendar month
codeburn yield --format json    # productive/reverted/abandoned spend as JSON
```

花费是否真正产出了成果？`codeburn yield` 按时间戳将 AI 会话与 git 提交关联：

| 类别 | 含义 |
|----------|---------|
| 有效产出 | 该会话的提交已合入 main |
| 已回滚 | 提交后来被回滚 |
| 已放弃 | 会话附近无提交，或提交从未合并 |

需要 git 仓库。请在你的项目目录中运行。

## 浏览器仪表板

```bash
codeburn web                    # opens http://localhost:4747 in your browser
codeburn web -p 30days          # start on a different period
codeburn web --port 8080        # pick a port (falls back to a free one if taken)
codeburn web --no-open          # start the server without opening a browser
```

本地 Web 仪表板，提供与 TUI 相同的任务、模型、工具和项目细分，并以图表呈现。所有数据均从你的本机磁盘读取，服务器绑定到 localhost；不会上传任何内容。

### 汇总多台设备的使用量

在同一网络上的笔记本、台式机和工作机上查看汇总总量。在每台其他设备上共享其使用量：

```bash
codeburn share --pair           # opens a pairing window and prints a PIN
```

然后在主设备上添加一次（PIN 用于授权配对）：

```bash
codeburn devices add            # find nearby devices and pair, or: add <host> --pin <pin>
codeburn devices                # combined totals by machine
codeburn devices rm <name>      # forget a device
```

配对需 PIN 授权，且仅在本地网络内进行。你也可以直接从浏览器仪表板发现并配对设备。

## 菜单栏

```bash
codeburn menubar
```

一条命令即可：下载最新 `.app`，安装到 `~/Applications` 并启动。使用 `--force` 重新运行可重装。原生 Swift 与 SwiftUI 应用位于 `mac/`（构建细节见 `mac/README.md`）。

<p align="center">
  <img src="https://raw.githubusercontent.com/getagentseal/codeburn/main/assets/menubar-0.9.11.png" alt="CodeBurn macOS menubar" width="440" />
</p>

菜单栏图标显示在设置中选定的花费时段（默认为 Today；也可选 Week、Month 和 6 Months）。非 Today 时段会添加 `$42 / mo` 等短后缀，以便菜单栏数值清晰可辨。点击可打开弹出面板，包含 agent 标签页、时段切换器（Today、7 Days、30 Days、Month、All）、Trend、Forecast、Pulse、Stats 和 Plan 洞察、活动与模型细分、optimize 发现，以及 CSV/JSON 导出。每 30 秒刷新一次。

你也可以在 Terminal 中设置菜单栏状态时段：

```bash
defaults write org.agentseal.codeburn-menubar CodeBurnMenubarPeriod -string month
```

允许的值包括 `today`、`week`、`month` 和 `sixMonths`。重新启动应用以应用外部默认设置变更。

**紧凑模式**（Compact mode）会缩小菜单栏项以适配文本，省略小数（例如 `$110` 而非 `$110.20`）：

```bash
defaults write org.agentseal.codeburn-menubar CodeBurnMenubarCompact -bool true
```

重新启动应用以生效。若要恢复：`defaults delete org.agentseal.codeburn-menubar CodeBurnMenubarCompact`。

**刷新频率**在设置的 Usage Refresh 中配置。Auto（默认）在接电源时每 30 秒刷新，使用电池、处于低电量模式或显示器休眠时会降频；也可选择固定的 1、5 或 15 分钟频率，以及 Manual 模式（仅在你打开弹出面板或点击 Refresh Now 时刷新）。在 Terminal 中：

```bash
defaults write org.agentseal.codeburn-menubar CodeBurnMenubarRefreshSeconds -int 300
```

刷新间隔秒数：`60`、`300` 或 `900`；`0` 为 Manual，`-1` 为 Auto。下次刷新时生效，无需重新启动。

### Linux（GNOME）

Linux 通过 GNOME Shell 扩展（GNOME 45+）提供相同的常驻视图：顶栏显示花费、时段切换器、紧凑模式与每日预算提醒。扩展位于 [`gnome/`](gnome/)：

```bash
git clone https://github.com/getagentseal/codeburn && cd codeburn/gnome
./install.sh
gnome-extensions enable codeburn@codeburn.dev
```

设置与开发说明见 [gnome/README.md](gnome/README.md)。在 Windows 上，目前 `codeburn web` 是常驻视图。

## 在 agent 中使用 CodeBurn（MCP）

```bash
claude mcp add codeburn -- npx -y codeburn mcp
```

`codeburn mcp` 通过 stdio 运行本地 MCP 服务器，因此 Claude Code、Cursor 或任何 MCP 客户端都可以在对话中询问「本周 token 花在哪了？」或「如何少花钱？」。它提供两个工具：

| 工具 | 返回内容 |
|------|-----------------|
| `get_usage` | 花费与使用量，按工具、模型、项目和任务细分（快速） |
| `get_savings` | 降本建议：浪费发现、重试税（retry tax）、路由浪费（routing waste）（较慢，更深入分析） |

所有数据均从本地磁盘读取，与 CLI 相同。项目名默认经假名化处理；agent 仅在使用 `include_project_names: true` 询问时才能看到真实名称。对于其他 MCP 客户端，请配置 stdio 服务器，命令为 `npx`，参数为 `-y codeburn mcp`。

## 支持的工具

CodeBurn 会自动检测你使用的 AI 工具。每个徽标链接到对应的提供商文档。

<p align="center">
  <a href="docs/providers/claude.md" title="Claude Code &amp; Claude Desktop"><img src="assets/providers/claude.jpg" alt="Claude Code &amp; Claude Desktop" height="34" /></a>
  <a href="docs/providers/cline.md" title="Cline"><img src="assets/providers/cline.svg" alt="Cline" height="34" /></a>
  <a href="docs/providers/codex.md" title="Codex (OpenAI)"><img src="assets/providers/codex.png" alt="Codex (OpenAI)" height="34" /></a>
  <a href="docs/providers/cursor.md" title="Cursor"><img src="assets/providers/cursor.jpg" alt="Cursor" height="34" /></a>
  <a href="docs/providers/cursor-agent.md" title="cursor-agent"><img src="assets/providers/cursor-agent.jpg" alt="cursor-agent" height="34" /></a>
  <a href="docs/providers/devin.md" title="Devin"><img src="assets/providers/devin.png" alt="Devin" height="34" /></a>
  <a href="docs/providers/forge.md" title="Forge"><img src="assets/providers/forge.png" alt="Forge" height="34" /></a>
  <a href="docs/providers/gemini.md" title="Gemini CLI"><img src="assets/providers/gemini.png" alt="Gemini CLI" height="34" /></a>
  <a href="docs/providers/mistral-vibe.md" title="Mistral Vibe"><img src="assets/providers/mistral-vibe.svg" alt="Mistral Vibe" height="34" /></a>
  <a href="docs/providers/copilot.md" title="GitHub Copilot"><img src="assets/providers/copilot.jpg" alt="GitHub Copilot" height="34" /></a>
  <a href="docs/providers/ibm-bob.md" title="IBM Bob"><img src="assets/providers/ibm-bob.svg" alt="IBM Bob" height="34" /></a>
  <a href="docs/providers/kiro.md" title="Kiro"><img src="assets/providers/kiro.png" alt="Kiro" height="34" /></a>
  <a href="docs/providers/opencode.md" title="OpenCode"><img src="assets/providers/opencode.png" alt="OpenCode" height="34" /></a>
  <a href="docs/providers/openclaw.md" title="OpenClaw"><img src="assets/providers/openclaw.jpg" alt="OpenClaw" height="34" /></a>
  <a href="docs/providers/pi.md" title="Pi"><img src="assets/providers/pi.png" alt="Pi" height="34" /></a>
  <a href="docs/providers/omp.md" title="OMP (Oh My Pi)"><img src="assets/providers/omp.svg" alt="OMP (Oh My Pi)" height="34" /></a>
  <a href="docs/providers/droid.md" title="Droid"><img src="assets/providers/droid.png" alt="Droid" height="34" /></a>
  <a href="docs/providers/roo-code.md" title="Roo Code"><img src="assets/providers/roo-code.png" alt="Roo Code" height="34" /></a>
  <a href="docs/providers/kilo-code.md" title="KiloCode"><img src="assets/providers/kilo-code.png" alt="KiloCode" height="34" /></a>
  <a href="docs/providers/qwen.md" title="Qwen"><img src="assets/providers/qwen.png" alt="Qwen" height="34" /></a>
  <a href="docs/providers/kimi.md" title="Kimi Code CLI"><img src="assets/providers/kimi.svg" alt="Kimi Code CLI" height="34" /></a>
  <a href="docs/providers/lingtai-tui.md" title="LingTai TUI">LingTai TUI</a>
  <a href="docs/providers/goose.md" title="Goose"><img src="assets/providers/goose.png" alt="Goose" height="34" /></a>
  <a href="docs/providers/antigravity.md" title="Antigravity"><img src="assets/providers/antigravity.png" alt="Antigravity" height="34" /></a>
  <a href="docs/providers/crush.md" title="Crush"><img src="assets/providers/crush.png" alt="Crush" height="34" /></a>
  <a href="docs/providers/warp.md" title="Warp"><img src="assets/providers/warp.jpg" alt="Warp" height="34" /></a>
  <a href="docs/providers/mux.md" title="Mux (coder)"><img src="assets/providers/mux.png" alt="Mux (coder)" height="34" /></a>
  <a href="docs/providers/vercel-gateway.md" title="Vercel AI Gateway"><img src="assets/providers/vercel-gateway.png" alt="Vercel AI Gateway" height="34" /></a>
  <a href="docs/providers/zerostack.md" title="Zerostack"><img src="assets/providers/zerostack.png" alt="Zerostack" height="34" /></a>
  <a href="docs/providers/grok.md" title="Grok Build"><img src="assets/providers/grok.png" alt="Grok Build" height="34" /></a>
  <a href="docs/providers/zcode.md" title="ZCode"><img src="assets/providers/zcode.jpg" alt="ZCode" height="34" /></a>
  <a href="docs/providers/zed.md" title="Zed"><img src="assets/providers/zed.jpg" alt="Zed" height="34" /></a>
  <a href="docs/providers/hermes.md" title="Hermes Agent"><img src="assets/providers/hermes.png" alt="Hermes Agent" height="34" /></a>
</p>

如果磁盘上有多个提供商的会话数据，可在仪表板中按 `p` 在它们之间切换。

各提供商文档会列出确切的数据位置、存储格式和已知特性。Linux 与 Windows 路径会自动检测。若路径已变更或不正确，请[提交 issue](https://github.com/getagentseal/codeburn/issues).

`--provider` 标志可将任意命令限定到单个提供商：`codeburn report --provider claude`、`codeburn today --provider codex`、`codeburn export --provider cursor`。适用于所有命令：`report`、`today`、`month`、`overview`、`status`、`export`、`web`、`optimize`、`compare`、`yield`。

添加新提供商只需一个文件。示例见 `src/providers/codex.ts`。

## 命令

<details>
<summary><strong>全部命令与键盘快捷键</strong></summary>

运行 `codeburn` 打开仪表板，或使用下方子命令。大多数命令还支持 `--provider`、`--project` / `--exclude`，以及周期标志（`-p today|week|30days|month|all`）。

**仪表板与报告**

| Command | What it does |
|---------|--------------|
| `codeburn` | 交互式仪表板，最近 7 天（默认视图） |
| `codeburn today` | 今日用量 |
| `codeburn month` | 本自然月用量 |
| `codeburn overview` | 纯文本月度摘要，可复制粘贴（`--no-color`、`--from`/`--to`） |
| `codeburn report -p 30days` | 滚动 30 天窗口 |
| `codeburn report -p all` | 所有已记录会话 |
| `codeburn report --from 2026-04-01 --to 2026-04-10` | 精确日期范围 |
| `codeburn report --format json` | 完整仪表板数据以 JSON 输出到 stdout |
| `codeburn report --refresh 60` | 每 60 秒自动刷新（默认 30 秒；`--refresh 0` 可禁用） |

**状态与导出**

| Command | What it does |
|---------|--------------|
| `codeburn status` | 紧凑单行：今日 + 本月合计 |
| `codeburn status --format json` | 相同合计的 JSON 格式 |
| `codeburn export` | 覆盖今日、7 天与 30 天的 CSV |
| `codeburn export -f json` | 导出为 JSON 而非 CSV |

**Web 与设备**

| Command | What it does |
|---------|--------------|
| `codeburn web` | 本地浏览器仪表板（含图表）（http://localhost:4747) |
| `codeburn share --pair` | 将本设备用量共享到其他设备（PIN 配对） |
| `codeburn devices add` | 查找并配对附近设备 |
| `codeburn devices` | 已配对设备的合并用量合计 |

**分析**

| Command | What it does |
|---------|--------------|
| `codeburn audit` | 按提供商-模型的 token 来源表：每个数字从何而来 |
| `codeburn context` | 会话上下文窗口的构成：交互式浏览器（Claude Code 与 Codex） |
| `codeburn context <id> --json` | 相同上下文树，可脚本化 |
| `codeburn optimize` | 扫描浪费并输出可复制粘贴的修复建议（最近 30 天） |
| `codeburn optimize -p week` | 将浪费扫描限定为最近 7 天 |
| `codeburn compare` | 模型并排对比 |
| `codeburn yield` | 有效产出 vs 回退/放弃支出，并与 git 关联 |
| `codeburn yield -p 30days` | 最近 30 天的产出（yield）分析 |

**修复与控制**

| Command | What it does |
|---------|--------------|
| `codeburn optimize --apply` | 交互式应用配置类修复（`--yes`、`--dry-run`、`--only <ids>`） |
| `codeburn act list` | CodeBurn 已应用的每项变更，最新在前 |
| `codeburn act undo <id>` | 回滚某项变更（最近一项用 `--last`，文件已漂移时用 `--force`） |
| `codeburn act report` | 已应用修复的实际节省 vs 预估节省 |
| `codeburn guard install` | Claude Code 的预算上限钩子（`--global`、`--statusline`） |
| `codeburn guard status` | 显示上限、安装位置与已标记项目 |
| `codeburn guard allow` | 解除当前会话的硬性上限 |
| `codeburn mcp` | MCP 服务器（stdio），向 AI 智能体暴露用量与节省数据 |

**模型**

| Command | What it does |
|---------|--------------|
| `codeburn models` | 按模型的 token + 费用表（最近 30 天） |
| `codeburn models --by-task` | 将各模型拆分为按任务类型的行 |
| `codeburn models --top 10` | 仅显示费用最高的 10 个模型 |
| `codeburn models --format markdown` | 输出便于粘贴的 Markdown 表格 |
| `codeburn models --task feature` | 筛选功能开发类工作 |
| `codeburn models --provider claude` | 筛选到单个提供商 |

方向键可在 Today、7 Days、30 Days、Month 与 6 Months 之间切换（精确历史窗口请用 `--from` / `--to`）。按 `q` 退出，`1` `2` `3` `4` `5` 为快捷键，`c` 打开模型对比，`o` 打开优化。仪表板默认每 30 秒自动刷新（`--refresh 0` 可禁用）。还会显示各项目的平均每次会话费用，以及费用最高的五次会话。

</details>

## 功能

<details>
<summary><strong>定价、任务分类、套餐、货币、筛选等</strong></summary>

### 定价

根据输入、输出、缓存读取、缓存写入与网络搜索的 token 数量，为每次 API 调用计价；Claude 另有 fast mode 倍率。价格从 [LiteLLM](https://github.com/BerriAI/litellm) 获取，并在 `~/.cache/codeburn/` 本地缓存 24 小时。所有 Claude 与 GPT-5 模型的硬编码回退价可防止模糊匹配导致定价错误。

### 任务分类

根据工具使用模式与用户消息关键词划分为 13 个类别。不调用 LLM，完全确定性。

| Category | What triggers it |
|---|---|
| Coding | Edit、Write 工具 |
| Debugging | 错误/修复关键词 + 工具使用 |
| Feature Dev | "add"、"create"、"implement" 关键词 |
| Refactoring | "refactor"、"rename"、"simplify" |
| Testing | Bash 中的 pytest、vitest、jest |
| Exploration | Read、Grep、WebSearch，且无编辑 |
| Planning | EnterPlanMode、TaskCreate 工具 |
| Delegation | Agent 工具派生子任务 |
| Git Ops | Bash 中的 git push/commit/merge |
| Build/Deploy | npm build、docker、pm2 |
| Brainstorming | "brainstorm"、"what if"、"design" |
| Conversation | 无工具，纯文本交流 |
| General | Skill 工具，未归类 |

### 细分

每日费用图表、按项目、按模型（Opus、Sonnet、Haiku、GPT-5、GPT-4o、Gemini、Kiro 等）、按活动（含一次性成功率）、核心工具、shell 命令与 MCP 服务器。

### 一次性成功率（One-Shot Rate）

对于涉及代码编辑的类别，CodeBurn 会跟踪文件感知的重试周期。重试指：两次编辑同一文件之间夹有一次 shell 命令（Edit foo.ts、Bash、Edit foo.ts）。跨 shell 步骤编辑不同文件不算重试。一次性列显示无需重试即成功的编辑轮次占比。Coding 为 90% 表示 AI 十次中有九次一次就做对。文件级跟踪适用于 Claude、Codex 与 Goose；其他提供商回退到基于工具名的检测。

### 套餐

```bash
codeburn plan set claude-max                                  # $200/month
codeburn plan set claude-pro                                  # $20/month
codeburn plan set cursor-pro                                  # $20/month
codeburn plan set custom --monthly-usd 200 --provider codex   # ChatGPT Pro-style custom plan
codeburn plan reset --provider codex                          # remove one provider plan
codeburn plan set none                                        # disable plan view
codeburn plan                                                 # show configured plans
codeburn plan reset                                           # remove plan config
```

跟踪 Claude Pro、Claude Max、Cursor Pro 及自定义提供商套餐的订阅。套餐按提供商存储，可同时跟踪 Claude 与 Codex/Cursor 订阅；仪表板为每个活跃提供商套餐显示一行超额费用。旧版/自定义 `all` 套餐仍为单一汇总套餐，添加提供商专属套餐后会被替换，避免超额行重复计算。现有单套餐配置仍会作为回退读取。预设采用公开披露的套餐价格（截至 2026 年 4 月）；不建模精确 token 配额，因为厂商未公布消费者套餐的精确上限。

</details>

### 货币

```bash
codeburn currency GBP          # set to British Pounds
codeburn currency AUD          # set to Australian Dollars
codeburn currency JPY          # set to Japanese Yen
codeburn currency CNY          # set to Chinese Yuan
codeburn currency RON          # set to Romanian Leu
codeburn currency              # show current setting
codeburn currency --reset      # back to USD
```

支持任意 [ISO 4217 货币代码](https://en.wikipedia.org/wiki/ISO_4217#List_of_ISO_4217_currency_codes) is supported（共 162 种货币）。汇率从 [Frankfurter](https://www.frankfurter.app/)（欧洲央行数据，免费，无需 API key）获取，并缓存 24 小时。配置保存在 `~/.config/codeburn/config.json`。货币设置全局生效：仪表盘、状态栏、菜单栏、CSV/JSON 导出以及 JSON API 输出。

### 模型别名

若某些模型显示 `$0.00`，说明你的提供商上报的模型名称与 LiteLLM 定价数据中的任何条目都不匹配。在使用会重写模型名称的代理时，这种情况很常见。

```bash
codeburn model-alias "my-proxy-model" "claude-opus-4-6"   # add alias
codeburn model-alias --list                                # show configured aliases
codeburn model-alias --remove "my-proxy-model"             # remove alias
```

别名保存在 `~/.config/codeburn/config.json`，并在定价查询前于运行时应用。目标名称可以是 [LiteLLM 模型列表](https://github.com/BerriAI/litellm/blob/main/model_prices_and_context_window.json)中的任意项，或回退表（fallback table）中的规范名称（例如 `claude-sonnet-4-6`、`claude-opus-4-5`、`gpt-4o`）。内置别名覆盖已知的代理模型名称变体。用户配置的别名优先于内置别名。

### 本地模型、自定义价格与代理

```bash
codeburn price-override my-model --input 0.27 --output 1.10   # USD per 1M tokens
codeburn model-savings "llama3.1:8b" gpt-4o                   # local model, counted as savings
codeburn proxy-path ~/work/copilot-repo                       # subscription-covered project
```

`price-override` 可为任意模型设置精确费率（input、output、cache read、cache creation），适用于私有部署或 LiteLLM 定价有误的模型。`model-savings` 将免费的本地模型映射到付费基线：本地调用仍为 $0，仪表盘会显示相同 token 在基线上的费用。`proxy-path` 标记通过订阅支持的代理路由的项目（例如通过 GitHub Copilot 使用 Claude Code），其 API 费率成本记为订阅覆盖，使你的实际自付支出保持准确。三者均支持 `--list` 和 `--remove`。

### 筛选

```bash
codeburn report --project myapp                  # show only projects matching "myapp"
codeburn report --exclude myapp                  # show everything except "myapp"
codeburn report --exclude myapp --exclude tests  # exclude multiple projects
codeburn month --project api --project web       # include multiple projects
codeburn export --project inventory              # export only "inventory" project data
```

可按提供商、项目名称（不区分大小写的子串）或精确日期范围筛选。`--project` 和 `--exclude` 标志适用于所有命令，并可与 `--provider` 组合使用。

```bash
codeburn report --from 2026-04-01 --to 2026-04-10   # explicit window
codeburn report --from 2026-04-01                    # this date through today
codeburn report --to 2026-04-10                      # earliest data through this date
```

单独使用任一标志均有效。倒置或格式错误的日期会以明确错误退出。在 TUI 中，自定义范围仅设置初始加载；按 `1` 至 `5` 会切换回预定义时段。

### JSON 输出

`report`、`today` 和 `month` 支持 `--format json`，将完整仪表盘数据以结构化 JSON 输出到 stdout：

```bash
codeburn report --format json             # 7-day JSON report
codeburn today --format json              # today's data as JSON
codeburn month --format json              # this month as JSON
codeburn report -p 30days --format json   # 30-day window
```

JSON 包含所有仪表盘面板：概览（成本、调用次数、会话数、缓存命中率 %）、每日明细、项目（含 `avgCostPerSession`）、带 token 计数的模型、含一次性成功率的 activities、核心工具、MCP 服务器以及 shell 命令。可管道到 `jq` 进行筛选：

```bash
codeburn report --format json | jq '.projects'
codeburn today --format json | jq '.overview.cost'
```

如需更轻量的输出，可使用 `status --format json`（仅今日与本月合计）、`optimize --format json`（设置健康度、发现项及可复制粘贴的修复）、`yield --format json`（productive/reverted/abandoned 支出），或文件导出（`export -f json`）。

</details>

## 阅读仪表盘

<details>
<summary><strong>信号及其可能含义</strong></summary>

CodeBurn 呈现数据，你来解读故事。以下模式值得留意：

| 你看到的信号 | 可能的含义 |
|---|---|
| 缓存命中率 < 80% | 系统提示词或上下文不稳定，或未启用缓存 |
| 每个会话大量 `Read` 调用 | Agent 重复读取相同文件，缺少上下文 |
| 低一次性成功率（Coding 30%） | Agent 编辑困难，陷入重试循环 |
| Opus 4.6 在小轮次中占主导成本 | 简单任务使用了过于强大的模型 |
| `dispatch_agent` / `task` 占比高 | 子 Agent 扇出，属预期或过度 |
| 未显示 MCP 使用 | 要么未使用 MCP 服务器，要么配置有问题 |
| Bash 以 `git status`、`ls` 为主 | Agent 在探索而非执行 |
| Conversation 类别占主导 | Agent 在交谈而非做事 |

这些只是起点，而非定论。单次实验性会话 60% 的缓存命中率没问题。数周工作中持续 60% 的缓存命中率则是配置问题。

</details>

## 它如何读取你的数据

<details>
<summary><strong>各工具的数据位置与解析方式</strong></summary>

| 提供商 | 数据位置 | 说明 |
|----------|---------------|-------|
| **Claude Code** | `~/.claude/projects/<sanitized-path>/<session-id>.jsonl` | 每条 assistant 条目包含模型名称、token 用量（input、output、cache read、cache write）、`tool_use` 块以及时间戳。 |
| **Claude（多个配置目录）** | 通过 `CLAUDE_CONFIG_DIRS` 设置（例如 `~/.claude-work:~/.claude-personal`） | 扫描所列的每个目录，并将会话合并为每个项目一行，使合计反映你所有的 Claude 使用情况。在 POSIX 上使用 `:`，在 Windows 上使用 `;`；会覆盖 `CLAUDE_CONFIG_DIR`。缺失或不可读的目录会被跳过。 |
| **Codex (OpenAI)** | `~/.codex/sessions/YYYY/MM/DD/rollout-*.jsonl` | 读取 `token_count` 事件（每次调用及累计用量）和 `function_call` 条目以跟踪工具；按项目工作目录归属成本。`codeburn report --provider codex` 仅查看 Codex。 |
| **Cursor** | SQLite `state.vscdb`，位于 `globalStorage` 下：macOS `~/Library/Application Support/Cursor/User/globalStorage/`、Linux `~/.config/Cursor/User/globalStorage/`、Windows `%APPDATA%/Cursor/User/globalStorage/`；结果缓存在 `~/.cache/codeburn/cursor-results.json` | 输入 token 来自 Cursor 自身的每会话上下文计量（`composerData.promptTokenBreakdown`），在稳定锚点上每个会话计一次；工具调用和 shell 命令从 agent 流（`agentKv`）读取，Composer 内置模型按 Cursor 公布的费率定价。输出为回复文本估算，缓存 token 仅在服务端，因此数据标记为估算值，长会话会低于 Cursor 管理控制台。数据库变更时缓存自动失效；大型数据库首次运行可能需要一分钟。 |
| **OpenCode** | SQLite `~/.local/share/opencode/opencode*.db`（遵循 `XDG_DATA_HOME`） | 以只读方式查询 `session`、`message` 和 `part`，并通过 LiteLLM 重新计算成本（未定价模型回退到 OpenCode 自身的 cost 字段）。子任务会话（`parent_id IS NOT NULL`）被排除以避免重复计数；支持多个 channel 数据库。 |
| **Gemini CLI** | `~/.gemini/tmp/<project>/chats/session-*.json` | 每个会话一个 JSON 文件，每条消息有真实的 token 计数（input、output、cached、thoughts），因此无需估算。input 报告值包含 cached，因此 CodeBurn 在定价前减去 cached，以避免重复计费。 |
| **Antigravity (CLI & IDE)** | `.gemini/` 文件夹下的会话文件，以及运行中的 language server | 从 language server 进程拉取细粒度轨迹和定价。对于短生命周期的 CLI，可选安装 `codeburn antigravity-hook install` 状态行钩子，以便在菜单栏刷新之间捕获用量。IDE 在 Windows 上通过 `--app-data-dir antigravity-ide` 标志检测。 |
| **GitHub Copilot** | `~/.copilot/session-state/`（旧版 CLI）；VS Code/VSCodium `workspaceStorage/*` 聊天会话、`GitHub.copilot-chat/transcripts/`，以及 `agent-traces.db` OpenTelemetry 存储；JetBrains IDE（IntelliJ、PyCharm、…）位于 `~/.config/github-copilot/<ide>/<kind>/<storeId>/copilot-*-nitrite.db` 下 | 存在时优先使用 OTel SQLite 存储（包含真实的 input/output/cache token 计数）。其他来源没有显式计数，因此 token 根据内容长度估算，模型从工具调用 ID 前缀推断。JetBrains 会话从 Nitrite（H2 MVStore）`.db` 读取；项目来自插件的 `projectName` 字段（否则为引用文件的 `.git` 根目录）。参见 [docs/providers/copilot.md](docs/providers/copilot.md)。 |
| **Kiro** | `.chat` JSON 文件 | token 计数根据内容长度估算。模型未暴露，因此会话标记为 `kiro-auto`，并按 Sonnet 费率计费。 |
| **Mistral Vibe** | `~/.vibe/logs/session/`（或 `$VIBE_HOME/logs/session/`）；每个文件夹包含 `meta.json` + `messages.jsonl` | 从 `meta.json` 读取累计 prompt/completion 合计及模型定价，再从 `messages.jsonl` 读取首个用户 prompt 和工具调用。每个会话输出一条记录（源数据为累计值，非按轮次）；`agents/` 下的子 agent 会话单独计数。 |
| **OpenClaw** | `~/.openclaw/agents/*.jsonl`（旧版 `.clawdbot`、`.moltbot`、`.moldbot`） | token 用量来自 assistant 消息中的 `usage` 块；模型来自 `modelId` 或 `message.model`。 |
| **Warp** | `~/Library/Group Containers/2BBY89MBSN.dev.warp/Library/Application Support/dev.warp.Warp-Stable/warp.sqlite`（Preview 回退） | 读取 `agent_conversations`、`ai_queries` 和 `blocks`，每个已完成的 exchange 输出一次调用。exchange 的 token 占比根据 prompt 大小加权并归一化到会话合计进行估算；`run_command` 块按时间戳附加到最近的前一个 exchange。 |
| **Zed** | SQLite `~/Library/Application Support/Zed/threads/threads.db`（Linux `~/.local/share/zed/threads/`） | 每个 agent 线程一行；blob 为 zstd 压缩的 JSON，含每次请求的 token 用量（input、output、cache read、cache write）及线程模型。线程会补足到精确累计计数器，使合计与存储一致。内置 zstd 需要 Node 22.15+。 |
| **Forge** | SQLite `~/.forge/.forge.db` | 以只读方式查询 `conversations` 并解析 `context.messages`。assistant usage 条目提供 prompt、completion 和 cached 计数；CodeBurn 从 prompt 中减去 cached 用于 input 定价，每条 assistant 消息输出一次调用，并提取工具调用和 shell 命令。 |
| **Pi / OMP** | `~/.pi/agent/sessions/<sanitized-cwd>/*.jsonl`（Pi）、`~/.omp/agent/sessions/<sanitized-cwd>/*.jsonl`（OMP） | 每条 assistant 消息包含用量（input、output、cacheRead、cacheWrite）以及内联 `toolCall` 块。工具名称规范化为标准集合（`bash` → `Bash`，`dispatch_agent` → `Agent`）；bash 命令来自 `toolCall.arguments.command`。 |
| **Codebuff**（原 Manicode） | `~/.config/manicode/projects/<project>/chats/<chatId>/chat-messages.json`（遵循 `CODEBUFF_DATA_DIR`；遍历 `manicode-dev` / `manicode-staging`） | 以 credits 计费，因此每条已完成的 assistant 消息按 `msg.credits` 的公开费率 $0.01/credit 计费。当上游提供商暂存的 RunState 记录 token 级用量（`message.metadata.runState.sessionState.mainAgentState.messageHistory[*].providerOptions`）时，真实 token 和 LiteLLM 成本优先。原生工具名称（`read_files`、`str_replace`、`run_terminal_command`、`spawn_agents`）规范化为 `Read`、`Edit`、`Bash`、`Agent`。 |
| **Cline / Roo Code / KiloCode** | VS Code `globalStorage`：Cline 位于 `saoudrizwan.claude-dev` 和 `~/.cline/data`；Roo Code 和 KiloCode 覆盖 VS Code、VS Code Insiders 和 VSCodium | Cline 系列 agent。CodeBurn 从每个任务目录读取 `ui_messages.json`，从带 `say: "api_req_started"` 的 `type: "say"` 条目中提取 token 计数。 |
| **IBM Bob** | `User/globalStorage/ibm.bob-code/tasks/<task-id>/`（GA `IBM Bob` 和预览版 `Bob-IDE` 应用文件夹） | 读取 `ui_messages.json` 获取 API 请求 token/成本记录，读取 `api_conversation_history.json` 获取所选模型。 |
| **Kimi Code CLI** | `$KIMI_SHARE_DIR/sessions/<workdir-hash>/<session-id>/` 或 `~/.kimi/sessions/<workdir-hash>/<session-id>/` | 读取 `wire.jsonl` `StatusUpdate.token_usage` 记录，将 `input_other`、`input_cache_read`、`input_cache_creation` 和 `output` 映射到标准 token 列；包含每个会话 `subagents/` 文件夹下的子 agent。 |
| **LingTai TUI** | `~/.lingtai/<agent>/logs/token_ledger.jsonl` 以及来自 `~/.lingtai-tui/registry.jsonl`（`<project>/.lingtai/<agent>/logs/token_ledger.jsonl`）的项目主目录；遵循 `LINGTAI_HOME` / `LINGTAI_TUI_HOME` | 读取 LingTai 的仅追加 token 账本，将 `input - cached` 映射为 fresh input，`cached` 映射为 cache reads，`output` 映射为 output，`thinking` 映射为 reasoning。嵌套 daemon 账本会被跳过，因为父账本已通过 `source`/`run_id` 标签镜像 daemon 用量。 |
| **Vercel AI Gateway** | [Vercel AI Gateway reporting API](https://vercel.com/docs/ai-gateway/capabilities/custom-reporting)（云端，非本地日志） | 设置 `AI_GATEWAY_API_KEY` 或 `VERCEL_OIDC_TOKEN`（来自 `vercel env pull` / `vercel dev`）；需要带有 Custom Reporting 的 Vercel 套餐。无凭据时在合并仪表盘中会静默跳过。 |

CodeBurn 对消息进行去重（Claude 按 API message ID，Codex 按累计 token 交叉校验，Cursor 按 conversation/timestamp，Gemini 按 session ID，OpenCode 按 session+message ID，Pi/OMP 按 responseId，Codebuff 按 chat folder + message ID，Kimi 按 session+message ID），按每条记录过滤日期范围，并对每一轮对话进行分类。

</details>

## 环境变量

<details>
<summary><strong>覆盖数据目录和路径</strong></summary>

| Variable | Description |
|----------|-------------|
| `CLAUDE_CONFIG_DIR` | 覆盖 Claude Code 数据目录（默认：`~/.claude`） |
| `CLAUDE_CONFIG_DIRS` | Claude 数据目录的 OS 分隔列表，用于一并扫描（例如 `~/.claude-work:~/.claude-personal`）。会话按项目合并为一行。设置后覆盖 `CLAUDE_CONFIG_DIR`。 |
| `CODEX_HOME` | 覆盖 Codex 数据目录（默认：`~/.codex`） |
| `CODEBUFF_DATA_DIR` | 覆盖 Codebuff 数据目录（默认：`~/.config/manicode`） |
| `FACTORY_DIR` | 覆盖 Droid 数据目录（默认：`~/.factory`） |
| `KIMI_SHARE_DIR` | 覆盖 Kimi Code CLI 共享目录（默认：`~/.kimi`） |
| `KIMI_MODEL_NAME` | 当 Kimi 会话未记录模型时，覆盖 Kimi 模型名称 |
| `LINGTAI_HOME` | 覆盖 LingTai 数据目录（默认：`~/.lingtai`） |
| `LINGTAI_TUI_HOME` | LingTai 数据目录的备用覆盖项；`LINGTAI_HOME` 优先级更高 |
| `LINGTAI_TUI_GLOBAL_DIR` | 覆盖用于项目注册表发现的 LingTai TUI 全局目录（默认：`~/.lingtai-tui`） |
| `QWEN_DATA_DIR` | 覆盖 Qwen 数据目录（默认：`~/.qwen/projects`） |
| `VIBE_HOME` | 覆盖 Mistral Vibe 主目录（默认：`~/.vibe`） |
| `WARP_DB_PATH` | 覆盖 Warp 数据库路径（默认：Warp Stable，其次 Warp Preview） |

</details>

## 赞助 CodeBurn

CodeBurn 免费，完全在你的机器上运行，旨在降低你的 AI 账单。如果它已经为你节省的金额超过了赞助费用，不妨回馈一部分。

保持 30 个集成的准确性是一项持续工作。底层工具每周都在变化：Cursor 重构数据库，Claude 迁移配置路径，新模型以新价格发布。赞助能让 CodeBurn 跟上所有这些变化，因此你看到的数字始终是真实的。

你的赞助将用于：

- **真实数字。** 快速映射新模型和价格变动，让你的成本是真实成本，而非猜测。
- **更多工具。** 30 个提供商中的每一个最初都只是一个文件。赞助资助下一个集成。
- **快速修复。** 当供应商破坏某些功能时，付费时间让它现在就能修复，而不是等到某天。

以团队或公司名义赞助？你的 Logo 将展示在这里，呈现在每位打开该仓库的开发者面前。首位赞助商可独占展示，直到下一位赞助商出现。

<p align="center">
  <a href="https://github.com/sponsors/iamtoruk"><img src="https://img.shields.io/badge/Sponsor_CodeBurn-♥-F97316?style=for-the-badge&logo=github&labelColor=1a1a1a" alt="Sponsor CodeBurn" /></a>
</p>

## Star 历史

<a href="https://www.star-history.com/?repos=getagentseal%2Fcodeburn&type=date&legend=top-left">
 <picture>
   <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/chart?repos=getagentseal/codeburn&type=date&theme=dark&legend=top-left" />
   <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/chart?repos=getagentseal/codeburn&type=date&legend=top-left" />
   <img alt="Star History Chart" src="https://api.star-history.com/chart?repos=getagentseal/codeburn&type=date&legend=top-left" />
 </picture>
</a>

## 许可证

MIT
CodeBurn 是 AgentSeal 开源项目，与 CodeBurn Bt. 或 codeburn.hu 无任何关联。

## 致谢

定价数据来自 [LiteLLM](https://github.com/BerriAI/litellm). 汇率数据来自 [Frankfurter](https://www.frankfurter.app/).

由 [AgentSeal](https://agentseal.org). 构建