docs: make Chinese README the default
CI / semgrep (push) Waiting to run

This commit is contained in:
wehub-resource-sync
2026-07-13 10:55:08 +00:00
parent 7f312106ef
commit 0695547e4a
+260 -253
View File
@@ -1,3 +1,9 @@
<!-- 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>
@@ -6,7 +12,7 @@
<img src="https://raw.githubusercontent.com/getagentseal/codeburn/main/assets/providers.png" alt="CodeBurn" width="420" />
</p>
<p align="center"><strong>See where your AI spend goes.</strong></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>
@@ -18,62 +24,62 @@
<a href="https://github.com/sponsors/iamtoruk"><img src="https://img.shields.io/badge/sponsor-♥-F97316?logo=github" alt="Sponsor" /></a>
</p>
**CodeBurn is a free, open-source, local-first tool that tracks AI coding token usage and cost across 32 tools and agents (Claude Code, Cursor, Codex, Gemini, Grok and more), broken down by model, project, and task.**
**CodeBurn 是一款免费、开源、本地优先(local-first)的工具,可追踪 32 款工具与智能体(Claude CodeCursorCodexGeminiGrok 等)的 AI 编程 token 用量与费用,并按模型、项目和任务细分。**
You pay for Claude, Codex, Cursor, and a stack of other AI tools. The bill tells you the total. It never tells you that half of it went to conversation instead of code, or that an expensive model burned your budget on work a cheaper one would have one-shot.
你为 ClaudeCodexCursor 以及一整套其他 AI 工具付费。账单只告诉你总额,却从不告诉你其中一半花在了对话而非代码上,也不告诉你某款昂贵模型把预算烧在了更便宜的模型一次就能搞定的工作上。
CodeBurn does. It reads the session files your tools already write to disk and breaks down every token and dollar by **task, model, tool, and project**, across **32 AI tools**.
CodeBurn 可以。它读取你的工具已经写入磁盘的会话文件,按**任务、模型、工具、项目**细分每一笔 token 和美元,覆盖 **32 AI 工具**
Everything runs locally. No wrapper, no proxy, no API keys, nothing leaves your machine. Pricing comes from [LiteLLM](https://github.com/BerriAI/litellm), refreshed daily.
一切都在本地运行。无需包装器、无需代理、无需 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>A week across every tool you use, in one screen.</em></p>
<p align="center"><em>你使用的所有工具,一周数据,一屏呈现。</em></p>
<p align="center">
<a href="#quick-start">Quick start</a> ·
<a href="#find-and-fix-waste">Find waste</a> ·
<a href="#apply-fixes-undo-anytime">Apply fixes</a> ·
<a href="#guard-your-budget">Guard</a> ·
<a href="#compare-models">Compare models</a> ·
<a href="#track-what-shipped">Track what shipped</a> ·
<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">Supported tools</a> ·
<a href="#commands">Commands</a> ·
<a href="#features">Features</a> ·
<a href="#how-it-reads-your-data">How it reads data</a>
<a href="#supported-tools">支持的工具</a> ·
<a href="#commands">命令</a> ·
<a href="#features">功能</a> ·
<a href="#how-it-reads-your-data">数据读取方式</a>
</p>
## Quick start
## 快速开始
**Run it instantly**, no install needed:
**即刻运行**,无需安装:
```bash
npx codeburn
```
That opens the interactive dashboard (last 7 days by default). Arrow keys switch periods, `q` quits. That is the 30-second version. You now know where your AI budget goes.
这会打开交互式仪表盘(默认显示最近 7 天)。方向键切换时间段,`q` 退出。这就是 30 秒版本。你现在就知道 AI 预算花在了哪里。
**Install it** for a permanent `codeburn` command:
**安装**以获得持久的 `codeburn` 命令:
```bash
npm install -g codeburn
```
Also runs via `bunx codeburn` or `dx codeburn`, or `brew install codeburn` on macOS.
也可通过 `bunx codeburn``dx codeburn` 运行,或在 macOS 上使用 `brew install codeburn`
**Menu bar app** for macOS, with your spend always in the menu bar:
**菜单栏应用**(macOS),让你的支出始终显示在菜单栏中:
```bash
codeburn menubar
```
On Linux, a GNOME Shell extension gives the same panel view; see [Linux (GNOME)](#linux-gnome).
Linux 上,GNOME Shell 扩展提供同样的面板视图;参见 [Linux (GNOME)](#linux-gnome)
Requires **Node.js 22.13+** and at least one supported tool with session data on disk. For Cursor and OpenCode, `better-sqlite3` installs automatically.
需要 **Node.js 22.13+**,且至少有一款支持的工具在磁盘上有会话数据。对于 Cursor OpenCode`better-sqlite3` 会自动安装。
## Your month at a glance
## 纵览你的月度支出
```bash
codeburn overview # this month, clean tables
@@ -83,7 +89,7 @@ codeburn overview -p all # all time
codeburn overview --provider claude # one tool only
```
`codeburn overview` prints a copy-pasteable summary of where your AI spend went: totals (cost, tokens, cache hit), a breakdown by tool and by top model, your highest-value days, top projects, a per-day table, and activity and tool usage. Pipe it anywhere (into `pbcopy`, a PR, Slack, or a tweet); color drops automatically when the output is not a terminal, or pass `--no-color`.
`codeburn overview` 会打印一份可复制粘贴的 AI 支出摘要:总计(费用、token、缓存命中)、按工具与热门模型的细分、价值最高的日期、主要项目、按日表格,以及活动与工具使用情况。可管道输出到任意位置(`pbcopy`、PR、Slack 或推文);当输出目标不是终端时颜色会自动去除,也可传入 `--no-color`
```text
CodeBurn June 2026
@@ -105,7 +111,7 @@ By tool
(plus Top models, Highest-value days, Top projects, a per-day table, By activity, and Tools)
```
## Find and fix waste
## 发现并修复浪费
```bash
codeburn optimize # scan the last 30 days
@@ -115,28 +121,27 @@ codeburn optimize --provider claude # restrict to one provider
codeburn optimize --format json # setup health + findings as JSON
```
`codeburn optimize` scans your sessions and your `~/.claude/` setup for waste patterns:
`codeburn optimize` 会扫描你的会话以及 `~/.claude/` 配置,查找浪费模式:
- Files Claude re-reads across sessions (same content, same context, over and over)
- Low Read:Edit ratio (editing without reading leads to retries and wasted tokens)
- Wasted bash output (uncapped `BASH_MAX_OUTPUT_LENGTH`, trailing noise)
- Unused MCP servers still paying their tool-schema overhead every session
- Ghost agents, skills, and slash commands defined in `~/.claude/` but never invoked
- Bloated `CLAUDE.md` files (with `@-import` expansion counted)
- Cache creation overhead and junk directory reads
- Context-heavy sessions where effective input/cache tokens swamp output
- Possibly low-worth expensive sessions with no edit turns or repeated retries
when no `git`/`gh` delivery command is observed
- 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>
Each finding shows the estimated token and dollar savings plus a ready-to-paste fix: a `CLAUDE.md` line, an environment variable, or a `mv` command to archive unused items. Findings are ranked by urgency (impact weighted against observed waste) and rolled up into an A to F setup health grade. Repeat runs classify each finding as new, improving, or resolved against a 48-hour recent window.
每条发现都会显示预估的 token 与美元节省,以及可直接粘贴的修复方案:一行 `CLAUDE.md`、环境变量,或用于归档未使用项的 `mv` 命令。发现按紧急程度排序(影响与已观察浪费加权),并汇总为 A F 的配置健康评级。重复运行会将每条发现归类为新增、改善或已解决(对照最近 48 小时窗口)。
You can also open it inline from the dashboard: press `o` when a finding count appears in the status bar, `b` to return.
你也可以从仪表盘内联打开:当状态栏出现发现计数时按 `o`,按 `b` 返回。
## Apply fixes, undo anytime
## 应用修复,随时撤销
```bash
codeburn optimize --apply # review and apply fixes interactively
@@ -147,11 +152,11 @@ codeburn act undo --last # roll the most recent change back
codeburn act report # realized vs estimated savings
```
`codeburn optimize` finds the waste; `--apply` fixes the config-class findings for you: settings values, environment variables, archiving unused agents and skills. Every change is backed up and journaled before it lands. `codeburn act list` shows the history and `codeburn act undo <id>` restores the original files (it refuses if the files changed since being applied, unless you pass `--force`).
`codeburn optimize` 发现浪费;`--apply` 为你修复配置类发现:设置值、环境变量、归档未使用的智能体与技能。每次变更在生效前都会备份并记入日志。`codeburn act list` 显示历史,`codeburn act undo <id>` 恢复原始文件(若文件自应用后已变更则拒绝恢复,除非你传入 `--force`)。
The loop closes on honesty: once an applied fix is at least 3 days old, `codeburn act report` compares its estimated savings against what your sessions actually did, and later `codeburn optimize` runs show that realized figure in the header. Estimates get checked against reality, not just claimed.
闭环讲求诚实:一旦某次应用的修复已满 3 天,`codeburn act report` 会将其预估节省与实际会话表现对比;后续 `codeburn optimize` 运行会在页眉显示已实现数字。预估会与现实核对,而不只是宣称。
## Guard your budget
## 守护你的预算
```bash
codeburn guard install # hooks into this project's .claude/settings.json
@@ -160,16 +165,16 @@ codeburn guard status # caps, install locations, flagged projects
codeburn guard uninstall # removes cleanly, leaves your own hooks alone
```
Guard installs opt-in hooks into Claude Code that watch session cost while you work:
Guard 会向 Claude Code 安装可选的 hooks,在你工作时监控会话成本:
- **Soft cap** (default $5): a one-time in-session warning when a session passes it.
- **Hard cap** (default $15): stops the session; `codeburn guard allow` lifts it for that session only.
- **Checkpoint** (default $3): if a session ends past this with no edits and no commits, a nudge suggests starting fresh with a named deliverable.
- **Session openers**: projects where optimize found waste get a one-line flag at session start.
- **软上限**Soft cap,默认 $5):会话超过该值时,在会话内发出一次性警告。
- **硬上限**Hard cap,默认 $15):终止会话;`codeburn guard allow` 可仅对该会话解除限制。
- **检查点**Checkpoint,默认 $3):若会话结束时已超过该阈值且没有任何编辑或提交,会提示你以明确的交付物重新开始。
- **会话开场提示**Session openers):optimize 发现浪费的项目,在会话开始时会显示一行标记。
Caps are edited in `~/.config/codeburn/guard.json` (set a value to `null` to disable it). Add `--statusline` to show session cost in the Claude Code status line. Installs go through the same journal as everything else, so `codeburn act undo` removes them too. Hooks fail open: a broken guard never blocks a session.
上限在 `~/.config/codeburn/guard.json` 中编辑(将值设为 `null` 可禁用它)。添加 `--statusline` 可在 Claude Code 状态栏显示会话成本。安装会与其他组件一样写入同一日志,因此 `codeburn act undo` 也会一并移除它们。Hooks 采用 fail open 策略:即使 Guard 损坏,也不会阻断会话。
## Compare models
## 对比模型
```bash
codeburn compare # interactive model picker (default: last 6 months)
@@ -178,25 +183,25 @@ codeburn compare -p today # today only
codeburn compare --provider claude # Claude Code sessions only
```
Which model is actually better for *your* work? Press `c` in the dashboard, or run `codeburn compare`. Arrow keys switch periods, `b` to return.
哪种模型更适合*你的*工作?在仪表板中按 `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>
| Section | Metric | What it measures |
| 板块 | 指标 | 衡量内容 |
|---------|--------|-----------------|
| Performance | One-shot rate | Edits that succeed without retries |
| Performance | Retry rate | Average retries per edit turn |
| Performance | Self-correction | Turns where the model corrected its own mistake |
| Efficiency | Cost per call | Average cost per API call |
| Efficiency | Cost per edit | Average cost per edit turn |
| Efficiency | Output tokens per call | Average output tokens per call |
| Efficiency | Cache hit rate | Proportion of input from cache |
| 性能 | 一次成功率 | 无需重试即成功的编辑 |
| 性能 | 重试率 | 每次编辑轮次的平均重试次数 |
| 性能 | 自我纠正 | 模型自行纠正错误的轮次 |
| 效率 | 每次调用成本 | 每次 API 调用的平均成本 |
| 效率 | 每次编辑成本 | 每次编辑轮次的平均成本 |
| 效率 | 每次调用输出 token 数 | 每次调用的平均输出 token 数 |
| 效率 | 缓存命中率 | 来自缓存的输入占比 |
Also compares per-category one-shot rates, delegation rate, planning rate, average tools per turn, and fast mode usage.
还会对比各类别的一次成功率、委派率、规划率、每轮平均工具调用数,以及 fast mode 使用情况。
## Track what shipped
## 追踪实际交付
```bash
codeburn yield # last 7 days (default)
@@ -206,17 +211,17 @@ codeburn yield -p month # this calendar month
codeburn yield --format json # productive/reverted/abandoned spend as JSON
```
Did the spend actually ship? `codeburn yield` correlates AI sessions with git commits by timestamp:
花费是否真正产出了成果?`codeburn yield` 按时间戳将 AI 会话与 git 提交关联:
| Category | Meaning |
| 类别 | 含义 |
|----------|---------|
| Productive | Commits from this session landed in main |
| Reverted | Commits were later reverted |
| Abandoned | No commits near session, or commits never merged |
| 有效产出 | 该会话的提交已合入 main |
| 已回滚 | 提交后来被回滚 |
| 已放弃 | 会话附近无提交,或提交从未合并 |
Requires a git repository. Run from your project directory.
需要 git 仓库。请在你的项目目录中运行。
## Browser dashboard
## 浏览器仪表板
```bash
codeburn web # opens http://localhost:4747 in your browser
@@ -225,17 +230,17 @@ 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
```
A local web dashboard with the same task, model, tool, and project breakdowns as the TUI, rendered with charts. Everything is read from disk on your machine and the server binds to localhost; nothing is uploaded.
本地 Web 仪表板,提供与 TUI 相同的任务、模型、工具和项目细分,并以图表呈现。所有数据均从你的本机磁盘读取,服务器绑定到 localhost;不会上传任何内容。
### Combine usage across your devices
### 汇总多台设备的使用量
See one total across your laptop, desktop, and work machine on the same network. On each other device, share its usage:
在同一网络上的笔记本、台式机和工作机上查看汇总总量。在每台其他设备上共享其使用量:
```bash
codeburn share --pair # opens a pairing window and prints a PIN
```
Then add it once from your main device (the PIN authorizes the pairing):
然后在主设备上添加一次(PIN 用于授权配对):
```bash
codeburn devices add # find nearby devices and pair, or: add <host> --pin <pin>
@@ -243,49 +248,49 @@ codeburn devices # combined totals by machine
codeburn devices rm <name> # forget a device
```
Pairing is PIN-authorized and stays on your local network. You can also discover and pair devices straight from the browser dashboard.
配对需 PIN 授权,且仅在本地网络内进行。你也可以直接从浏览器仪表板发现并配对设备。
## Menu bar
## 菜单栏
```bash
codeburn menubar
```
One command: downloads the latest `.app`, installs into `~/Applications`, and launches it. Re-run with `--force` to reinstall. Native Swift and SwiftUI app lives in `mac/` (see `mac/README.md` for build details).
一条命令即可:下载最新 `.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>
The menubar icon shows the spend period selected in Settings (Today by default; Week, Month, and 6 Months are also available). Non-today periods add a short suffix such as `$42 / mo` so the menu bar value stays clear. Click to open a popover with agent tabs, period switcher (Today, 7 Days, 30 Days, Month, All), Trend, Forecast, Pulse, Stats, and Plan insights, activity and model breakdowns, optimize findings, and CSV/JSON export. Refreshes every 30 seconds.
菜单栏图标显示在设置中选定的花费时段(默认为 Today;也可选 WeekMonth 6 Months)。非 Today 时段会添加 `$42 / mo` 等短后缀,以便菜单栏数值清晰可辨。点击可打开弹出面板,包含 agent 标签页、时段切换器(Today7 Days30 DaysMonthAll)、TrendForecastPulseStats Plan 洞察、活动与模型细分、optimize 发现,以及 CSV/JSON 导出。每 30 秒刷新一次。
You can also set the menubar status period from Terminal:
你也可以在 Terminal 中设置菜单栏状态时段:
```bash
defaults write org.agentseal.codeburn-menubar CodeBurnMenubarPeriod -string month
```
Allowed values are `today`, `week`, `month`, and `sixMonths`. Relaunch the app to apply external defaults changes.
允许的值包括 `today``week``month` `sixMonths`。重新启动应用以应用外部默认设置变更。
**Compact mode** shrinks the menubar item to fit the text, dropping decimals (e.g. `$110` instead of `$110.20`):
**紧凑模式**Compact mode)会缩小菜单栏项以适配文本,省略小数(例如 `$110` 而非 `$110.20`):
```bash
defaults write org.agentseal.codeburn-menubar CodeBurnMenubarCompact -bool true
```
Relaunch the app to apply. To revert: `defaults delete org.agentseal.codeburn-menubar CodeBurnMenubarCompact`.
重新启动应用以生效。若要恢复:`defaults delete org.agentseal.codeburn-menubar CodeBurnMenubarCompact`
**Refresh cadence** is set in Settings under Usage Refresh. Auto (the default) refreshes every 30 seconds on AC power and backs off on battery, in Low Power Mode, and while the display sleeps; fixed 1, 5, or 15 minute cadences and a Manual mode (refresh only when you open the popover or click Refresh Now) are also available. From Terminal:
**刷新频率**在设置的 Usage Refresh 中配置。Auto(默认)在接电源时每 30 秒刷新,使用电池、处于低电量模式或显示器休眠时会降频;也可选择固定的 1、5 或 15 分钟频率,以及 Manual 模式(仅在你打开弹出面板或点击 Refresh Now 时刷新)。在 Terminal 中:
```bash
defaults write org.agentseal.codeburn-menubar CodeBurnMenubarRefreshSeconds -int 300
```
Seconds between refreshes: `60`, `300`, or `900`; `0` is Manual and `-1` is Auto. Takes effect on the next refresh tick, no relaunch needed.
刷新间隔秒数:`60``300` `900``0` Manual`-1` Auto。下次刷新时生效,无需重新启动。
### Linux (GNOME)
### LinuxGNOME
Linux gets the same ambient view through a GNOME Shell extension (GNOME 45+): spend in the top panel, period switcher, compact mode, and daily budget alerts. It lives in [`gnome/`](gnome/):
Linux 通过 GNOME Shell 扩展(GNOME 45+)提供相同的常驻视图:顶栏显示花费、时段切换器、紧凑模式与每日预算提醒。扩展位于 [`gnome/`](gnome/)
```bash
git clone https://github.com/getagentseal/codeburn && cd codeburn/gnome
@@ -293,26 +298,26 @@ git clone https://github.com/getagentseal/codeburn && cd codeburn/gnome
gnome-extensions enable codeburn@codeburn.dev
```
See [gnome/README.md](gnome/README.md) for settings and development notes. On Windows, `codeburn web` is the always-on view for now.
设置与开发说明见 [gnome/README.md](gnome/README.md)。在 Windows 上,目前 `codeburn web` 是常驻视图。
## CodeBurn in your agent (MCP)
## 在 agent 中使用 CodeBurnMCP
```bash
claude mcp add codeburn -- npx -y codeburn mcp
```
`codeburn mcp` runs a local MCP server over stdio, so Claude Code, Cursor, or any MCP client can ask "where did my tokens go this week?" or "how do I spend less?" mid-conversation. It exposes two tools:
`codeburn mcp` 通过 stdio 运行本地 MCP 服务器,因此 Claude CodeCursor 或任何 MCP 客户端都可以在对话中询问「本周 token 花在哪了?」或「如何少花钱?」。它提供两个工具:
| Tool | What it returns |
| 工具 | 返回内容 |
|------|-----------------|
| `get_usage` | Spend and usage with breakdowns by tool, model, project, and task (fast) |
| `get_savings` | Cost reductions: waste findings, retry tax, routing waste (slower, deeper analysis) |
| `get_usage` | 花费与使用量,按工具、模型、项目和任务细分(快速) |
| `get_savings` | 降本建议:浪费发现、重试税(retry tax)、路由浪费(routing waste)(较慢,更深入分析) |
Everything is read from local disk, same as the CLI. Project names are pseudonymized by default; the agent only sees real names if it asks with `include_project_names: true`. For other MCP clients, configure a stdio server with command `npx` and args `-y codeburn mcp`.
所有数据均从本地磁盘读取,与 CLI 相同。项目名默认经假名化处理;agent 仅在使用 `include_project_names: true` 询问时才能看到真实名称。对于其他 MCP 客户端,请配置 stdio 服务器,命令为 `npx`,参数为 `-y codeburn mcp`
## Supported tools
## 支持的工具
CodeBurn auto-detects which AI tools you use. Each logo links to its provider doc.
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>
@@ -350,132 +355,132 @@ CodeBurn auto-detects which AI tools you use. Each logo links to its provider do
<a href="docs/providers/hermes.md" title="Hermes Agent"><img src="assets/providers/hermes.png" alt="Hermes Agent" height="34" /></a>
</p>
If multiple providers have session data on disk, press `p` in the dashboard to toggle between them.
如果磁盘上有多个提供商的会话数据,可在仪表板中按 `p` 在它们之间切换。
Each provider doc lists the exact data location, storage format, and known quirks. Linux and Windows paths are detected automatically. If a path has changed or is wrong, please [open an issue](https://github.com/getagentseal/codeburn/issues).
各提供商文档会列出确切的数据位置、存储格式和已知特性。Linux Windows 路径会自动检测。若路径已变更或不正确,请[提交 issue](https://github.com/getagentseal/codeburn/issues).
The `--provider` flag filters any command to a single provider: `codeburn report --provider claude`, `codeburn today --provider codex`, `codeburn export --provider cursor`. Works on all commands: `report`, `today`, `month`, `overview`, `status`, `export`, `web`, `optimize`, `compare`, `yield`.
`--provider` 标志可将任意命令限定到单个提供商:`codeburn report --provider claude``codeburn today --provider codex``codeburn export --provider cursor`。适用于所有命令:`report``today``month``overview``status``export``web``optimize``compare``yield`
Adding a new provider is a single file. See `src/providers/codex.ts` for an example.
添加新提供商只需一个文件。示例见 `src/providers/codex.ts`
## Commands
## 命令
<details>
<summary><strong>All commands and keyboard shortcuts</strong></summary>
<summary><strong>全部命令与键盘快捷键</strong></summary>
Run `codeburn` for the dashboard, or use a subcommand below. Most commands also accept `--provider`, `--project` / `--exclude`, and a period flag (`-p today|week|30days|month|all`).
运行 `codeburn` 打开仪表板,或使用下方子命令。大多数命令还支持 `--provider``--project` / `--exclude`,以及周期标志(`-p today|week|30days|month|all`)。
**Dashboard & reports**
**仪表板与报告**
| Command | What it does |
|---------|--------------|
| `codeburn` | Interactive dashboard, last 7 days (the default view) |
| `codeburn today` | Today's usage |
| `codeburn month` | This calendar month's usage |
| `codeburn overview` | Plain-text monthly summary, copy-pasteable (`--no-color`, `--from`/`--to`) |
| `codeburn report -p 30days` | Rolling 30-day window |
| `codeburn report -p all` | Every recorded session |
| `codeburn report --from 2026-04-01 --to 2026-04-10` | An exact date range |
| `codeburn report --format json` | Full dashboard data as JSON, printed to stdout |
| `codeburn report --refresh 60` | Auto-refresh every 60s (default 30s; `--refresh 0` disables) |
| `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` 可禁用) |
**Status & export**
**状态与导出**
| Command | What it does |
|---------|--------------|
| `codeburn status` | Compact one-liner: today + month totals |
| `codeburn status --format json` | The same totals as JSON |
| `codeburn export` | CSV covering today, 7 days, and 30 days |
| `codeburn export -f json` | Export as JSON instead of CSV |
| `codeburn status` | 紧凑单行:今日 + 本月合计 |
| `codeburn status --format json` | 相同合计的 JSON 格式 |
| `codeburn export` | 覆盖今日、7 天与 30 天的 CSV |
| `codeburn export -f json` | 导出为 JSON 而非 CSV |
**Web & devices**
**Web 与设备**
| Command | What it does |
|---------|--------------|
| `codeburn web` | Local browser dashboard with charts (http://localhost:4747) |
| `codeburn share --pair` | Share this device's usage to your other devices (PIN pairing) |
| `codeburn devices add` | Find and pair a nearby device |
| `codeburn devices` | Combined usage totals across your paired devices |
| `codeburn web` | 本地浏览器仪表板(含图表)(http://localhost:4747) |
| `codeburn share --pair` | 将本设备用量共享到其他设备(PIN 配对) |
| `codeburn devices add` | 查找并配对附近设备 |
| `codeburn devices` | 已配对设备的合并用量合计 |
**Analysis**
**分析**
| Command | What it does |
|---------|--------------|
| `codeburn audit` | Per provider-model token source table: where every number comes from |
| `codeburn context` | What fills a session's context window: interactive browser (Claude Code and Codex) |
| `codeburn context <id> --json` | The same context tree, scriptable |
| `codeburn optimize` | Scan for waste and print copy-paste fixes (last 30 days) |
| `codeburn optimize -p week` | Scope the waste scan to the last 7 days |
| `codeburn compare` | Side-by-side model comparison |
| `codeburn yield` | Productive vs reverted/abandoned spend, correlated against git |
| `codeburn yield -p 30days` | Yield analysis for the last 30 days |
| `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)分析 |
**Fix & control**
**修复与控制**
| Command | What it does |
|---------|--------------|
| `codeburn optimize --apply` | Interactively apply config-class fixes (`--yes`, `--dry-run`, `--only <ids>`) |
| `codeburn act list` | Every change CodeBurn has applied, newest first |
| `codeburn act undo <id>` | Roll a change back (`--last` for the most recent, `--force` if files drifted) |
| `codeburn act report` | Realized vs estimated savings for applied fixes |
| `codeburn guard install` | Budget-cap hooks for Claude Code (`--global`, `--statusline`) |
| `codeburn guard status` | Show caps, install locations, and flagged projects |
| `codeburn guard allow` | Lift the hard cap for the current session |
| `codeburn mcp` | MCP server (stdio) exposing usage and savings to AI agents |
| `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 智能体暴露用量与节省数据 |
**Models**
**模型**
| Command | What it does |
|---------|--------------|
| `codeburn models` | Per-model token + cost table (last 30 days) |
| `codeburn models --by-task` | Break each model into per-task-type rows |
| `codeburn models --top 10` | Only the 10 most expensive models |
| `codeburn models --format markdown` | Emit a paste-friendly markdown table |
| `codeburn models --task feature` | Filter to feature-development work |
| `codeburn models --provider claude` | Filter to a single provider |
| `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` | 筛选到单个提供商 |
Arrow keys switch between Today, 7 Days, 30 Days, Month, and 6 Months (use `--from` / `--to` for an exact historical window). Press `q` to quit, `1` `2` `3` `4` `5` as shortcuts, `c` to open model comparison, `o` to open optimize. The dashboard auto-refreshes every 30 seconds by default (`--refresh 0` to disable). It also shows average cost per session and the five most expensive sessions across all projects.
方向键可在 Today7 Days30 DaysMonth 6 Months 之间切换(精确历史窗口请用 `--from` / `--to`)。按 `q` 退出,`1` `2` `3` `4` `5` 为快捷键,`c` 打开模型对比,`o` 打开优化。仪表板默认每 30 秒自动刷新(`--refresh 0` 可禁用)。还会显示各项目的平均每次会话费用,以及费用最高的五次会话。
</details>
## Features
## 功能
<details>
<summary><strong>Pricing, task categories, plans, currency, filtering, and more</strong></summary>
<summary><strong>定价、任务分类、套餐、货币、筛选等</strong></summary>
### Pricing
### 定价
Prices every API call using input, output, cache read, cache write, and web search token counts, with a fast mode multiplier for Claude. Prices are fetched from [LiteLLM](https://github.com/BerriAI/litellm) and cached locally for 24 hours at `~/.cache/codeburn/`. Hardcoded fallbacks for all Claude and GPT-5 models prevent fuzzy-matching mispricing.
根据输入、输出、缓存读取、缓存写入与网络搜索的 token 数量,为每次 API 调用计价;Claude 另有 fast mode 倍率。价格从 [LiteLLM](https://github.com/BerriAI/litellm) 获取,并在 `~/.cache/codeburn/` 本地缓存 24 小时。所有 Claude GPT-5 模型的硬编码回退价可防止模糊匹配导致定价错误。
### Task Categories
### 任务分类
13 categories classified from tool usage patterns and user message keywords. No LLM calls, fully deterministic.
根据工具使用模式与用户消息关键词划分为 13 个类别。不调用 LLM,完全确定性。
| Category | What triggers it |
|---|---|
| Coding | Edit, Write tools |
| Debugging | Error/fix keywords + tool usage |
| Feature Dev | "add", "create", "implement" keywords |
| Refactoring | "refactor", "rename", "simplify" |
| Testing | pytest, vitest, jest in Bash |
| Exploration | Read, Grep, WebSearch without edits |
| Planning | EnterPlanMode, TaskCreate tools |
| Delegation | Agent tool spawns |
| Git Ops | git push/commit/merge in Bash |
| Build/Deploy | npm build, docker, pm2 |
| Brainstorming | "brainstorm", "what if", "design" |
| Conversation | No tools, pure text exchange |
| General | Skill tool, uncategorized |
| Coding | EditWrite 工具 |
| Debugging | 错误/修复关键词 + 工具使用 |
| Feature Dev | "add""create""implement" 关键词 |
| Refactoring | "refactor""rename""simplify" |
| Testing | Bash 中的 pytestvitestjest |
| Exploration | ReadGrepWebSearch,且无编辑 |
| Planning | EnterPlanModeTaskCreate 工具 |
| Delegation | Agent 工具派生子任务 |
| Git Ops | Bash 中的 git push/commit/merge |
| Build/Deploy | npm builddockerpm2 |
| Brainstorming | "brainstorm""what if""design" |
| Conversation | 无工具,纯文本交流 |
| General | Skill 工具,未归类 |
### Breakdowns
### 细分
Daily cost chart, per-project, per-model (Opus, Sonnet, Haiku, GPT-5, GPT-4o, Gemini, Kiro, and more), per-activity with one-shot rate, core tools, shell commands, and MCP servers.
每日费用图表、按项目、按模型(OpusSonnetHaikuGPT-5GPT-4oGeminiKiro 等)、按活动(含一次性成功率)、核心工具、shell 命令与 MCP 服务器。
### One-Shot Rate
### 一次性成功率(One-Shot Rate
For categories that involve code edits, CodeBurn tracks file-aware retry cycles. A retry is when the same file is re-edited after a shell command in between (Edit foo.ts, Bash, Edit foo.ts). Editing different files across shell steps is not a retry. The one-shot column shows the percentage of edit turns that succeeded without retries. Coding at 90% means the AI got it right first try 9 out of 10 times. File-level tracking is available for Claude, Codex, and Goose; other providers fall back to tool-name-based detection.
对于涉及代码编辑的类别,CodeBurn 会跟踪文件感知的重试周期。重试指:两次编辑同一文件之间夹有一次 shell 命令(Edit foo.tsBashEdit foo.ts)。跨 shell 步骤编辑不同文件不算重试。一次性列显示无需重试即成功的编辑轮次占比。Coding 90% 表示 AI 十次中有九次一次就做对。文件级跟踪适用于 ClaudeCodex Goose;其他提供商回退到基于工具名的检测。
### Plans
### 套餐
```bash
codeburn plan set claude-max # $200/month
@@ -488,9 +493,11 @@ codeburn plan # show configured
codeburn plan reset # remove plan config
```
Subscription tracking for Claude Pro, Claude Max, Cursor Pro, and custom provider plans. Plans are stored per provider, so you can track Claude and Codex/Cursor subscriptions at the same time; the dashboard shows one overage line per active provider plan. A legacy/custom `all` plan remains a single aggregate plan and is replaced when you add a provider-specific plan, avoiding double-counted overage rows. Existing single-plan config is still read as a fallback. Presets use publicly stated plan prices (as of April 2026); they do not model exact token allowances, because vendors do not publish precise consumer-plan limits.
跟踪 Claude ProClaude MaxCursor Pro 及自定义提供商套餐的订阅。套餐按提供商存储,可同时跟踪 Claude Codex/Cursor 订阅;仪表板为每个活跃提供商套餐显示一行超额费用。旧版/自定义 `all` 套餐仍为单一汇总套餐,添加提供商专属套餐后会被替换,避免超额行重复计算。现有单套餐配置仍会作为回退读取。预设采用公开披露的套餐价格(截至 2026 年 4 月);不建模精确 token 配额,因为厂商未公布消费者套餐的精确上限。
### Currency
</details>
### 货币
```bash
codeburn currency GBP # set to British Pounds
@@ -502,11 +509,11 @@ codeburn currency # show current setting
codeburn currency --reset # back to USD
```
Any [ISO 4217 currency code](https://en.wikipedia.org/wiki/ISO_4217#List_of_ISO_4217_currency_codes) is supported (162 currencies). Exchange rates fetched from [Frankfurter](https://www.frankfurter.app/) (European Central Bank data, free, no API key) and cached for 24 hours. Config stored at `~/.config/codeburn/config.json`. The currency setting applies everywhere: dashboard, status bar, menu bar, CSV/JSON exports, and JSON API output.
支持任意 [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 输出。
### Model Aliases
### 模型别名
If you see `$0.00` for some models, the model name reported by your provider does not match any entry in the LiteLLM pricing data. This commonly happens when using a proxy that rewrites model names.
若某些模型显示 `$0.00`,说明你的提供商上报的模型名称与 LiteLLM 定价数据中的任何条目都不匹配。在使用会重写模型名称的代理时,这种情况很常见。
```bash
codeburn model-alias "my-proxy-model" "claude-opus-4-6" # add alias
@@ -514,9 +521,9 @@ codeburn model-alias --list # show configured ali
codeburn model-alias --remove "my-proxy-model" # remove alias
```
Aliases are stored in `~/.config/codeburn/config.json` and applied at runtime before pricing lookup. The target name can be anything in the [LiteLLM model list](https://github.com/BerriAI/litellm/blob/main/model_prices_and_context_window.json) or a canonical name from the fallback table (e.g. `claude-sonnet-4-6`, `claude-opus-4-5`, `gpt-4o`). Built-in aliases ship for known proxy model name variants. User-configured aliases take precedence over built-ins.
别名保存在 `~/.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`)。内置别名覆盖已知的代理模型名称变体。用户配置的别名优先于内置别名。
### Local Models, Custom Prices, and Proxies
### 本地模型、自定义价格与代理
```bash
codeburn price-override my-model --input 0.27 --output 1.10 # USD per 1M tokens
@@ -524,9 +531,9 @@ codeburn model-savings "llama3.1:8b" gpt-4o # local model, cou
codeburn proxy-path ~/work/copilot-repo # subscription-covered project
```
`price-override` sets exact rates for any model (input, output, cache read, cache creation), useful for private deployments or models LiteLLM prices wrong. `model-savings` maps a free local model to a paid baseline: the local calls stay $0, and the dashboard shows what the same tokens would have cost on the baseline. `proxy-path` marks a project routed through a subscription-backed proxy (e.g. Claude Code over GitHub Copilot), so its API-rate cost is reported as subscription-covered and your net out-of-pocket stays honest. All three support `--list` and `--remove`.
`price-override` 可为任意模型设置精确费率(inputoutputcache readcache creation),适用于私有部署或 LiteLLM 定价有误的模型。`model-savings` 将免费的本地模型映射到付费基线:本地调用仍为 $0,仪表盘会显示相同 token 在基线上的费用。`proxy-path` 标记通过订阅支持的代理路由的项目(例如通过 GitHub Copilot 使用 Claude Code),其 API 费率成本记为订阅覆盖,使你的实际自付支出保持准确。三者均支持 `--list` `--remove`
### Filtering
### 筛选
```bash
codeburn report --project myapp # show only projects matching "myapp"
@@ -536,7 +543,7 @@ codeburn month --project api --project web # include multiple projects
codeburn export --project inventory # export only "inventory" project data
```
Filter by provider, project name (case-insensitive substring), or exact date range. The `--project` and `--exclude` flags work on all commands and can be combined with `--provider`.
可按提供商、项目名称(不区分大小写的子串)或精确日期范围筛选。`--project` `--exclude` 标志适用于所有命令,并可与 `--provider` 组合使用。
```bash
codeburn report --from 2026-04-01 --to 2026-04-10 # explicit window
@@ -544,11 +551,11 @@ codeburn report --from 2026-04-01 # this date through today
codeburn report --to 2026-04-10 # earliest data through this date
```
Either flag alone is valid. Inverted or malformed dates exit with a clear error. In the TUI, the custom range sets the initial load only; pressing `1` through `5` switches back to predefined periods.
单独使用任一标志均有效。倒置或格式错误的日期会以明确错误退出。在 TUI 中,自定义范围仅设置初始加载;按 `1``5` 会切换回预定义时段。
### JSON Output
### JSON 输出
`report`, `today`, and `month` support `--format json` to output the full dashboard data as structured JSON to stdout:
`report``today` `month` 支持 `--format json`,将完整仪表盘数据以结构化 JSON 输出到 stdout
```bash
codeburn report --format json # 7-day JSON report
@@ -557,114 +564,114 @@ codeburn month --format json # this month as JSON
codeburn report -p 30days --format json # 30-day window
```
The JSON includes all dashboard panels: overview (cost, calls, sessions, cache hit %), daily breakdown, projects (with `avgCostPerSession`), models with token counts, activities with one-shot rates, core tools, MCP servers, and shell commands. Pipe to `jq` for filtering:
JSON 包含所有仪表盘面板:概览(成本、调用次数、会话数、缓存命中率 %)、每日明细、项目(含 `avgCostPerSession`)、带 token 计数的模型、含一次性成功率的 activities、核心工具、MCP 服务器以及 shell 命令。可管道到 `jq` 进行筛选:
```bash
codeburn report --format json | jq '.projects'
codeburn today --format json | jq '.overview.cost'
```
For lighter output, use `status --format json` (today and month totals only), `optimize --format json` (setup health, findings, and copy-paste fixes), `yield --format json` (productive/reverted/abandoned spend), or file exports (`export -f json`).
如需更轻量的输出,可使用 `status --format json`(仅今日与本月合计)、`optimize --format json`(设置健康度、发现项及可复制粘贴的修复)、`yield --format json`productive/reverted/abandoned 支出),或文件导出(`export -f json`)。
</details>
## Reading the dashboard
## 阅读仪表盘
<details>
<summary><strong>Signals and what they might mean</strong></summary>
<summary><strong>信号及其可能含义</strong></summary>
CodeBurn surfaces the data, you read the story. A few patterns worth knowing:
CodeBurn 呈现数据,你来解读故事。以下模式值得留意:
| Signal you see | What it might mean |
| 你看到的信号 | 可能的含义 |
|---|---|
| Cache hit < 80% | System prompt or context is not stable, or caching not enabled |
| Lots of `Read` calls per session | Agent re-reading same files, missing context |
| Low 1-shot rate (Coding 30%) | Agent struggling with edits, retry loops |
| Opus 4.6 dominating cost on small turns | Overpowered model for simple tasks |
| `dispatch_agent` / `task` heavy | Sub-agent fan-out, expected or excessive |
| No MCP usage shown | Either you don't use MCP servers, or your config is broken |
| Bash dominated by `git status`, `ls` | Agent exploring instead of executing |
| Conversation category dominant | Agent talking instead of doing |
| 缓存命中率 < 80% | 系统提示词或上下文不稳定,或未启用缓存 |
| 每个会话大量 `Read` 调用 | Agent 重复读取相同文件,缺少上下文 |
| 低一次性成功率(Coding 30% | Agent 编辑困难,陷入重试循环 |
| Opus 4.6 在小轮次中占主导成本 | 简单任务使用了过于强大的模型 |
| `dispatch_agent` / `task` 占比高 | 子 Agent 扇出,属预期或过度 |
| 未显示 MCP 使用 | 要么未使用 MCP 服务器,要么配置有问题 |
| Bash `git status``ls` 为主 | Agent 在探索而非执行 |
| Conversation 类别占主导 | Agent 在交谈而非做事 |
These are starting points, not verdicts. A 60% cache hit on a single experimental session is fine. A persistent 60% cache hit across weeks of work is a config issue.
这些只是起点,而非定论。单次实验性会话 60% 的缓存命中率没问题。数周工作中持续 60% 的缓存命中率则是配置问题。
</details>
## How it reads your data
## 它如何读取你的数据
<details>
<summary><strong>Per-tool data locations and parsing</strong></summary>
<summary><strong>各工具的数据位置与解析方式</strong></summary>
| Provider | Data location | Notes |
| 提供商 | 数据位置 | 说明 |
|----------|---------------|-------|
| **Claude Code** | `~/.claude/projects/<sanitized-path>/<session-id>.jsonl` | Each assistant entry carries model name, token usage (input, output, cache read, cache write), `tool_use` blocks, and timestamps. |
| **Claude (multiple config dirs)** | Set via `CLAUDE_CONFIG_DIRS` (e.g. `~/.claude-work:~/.claude-personal`) | Scans every listed directory and merges sessions into one row per project so totals reflect all your Claude usage. Use `:` on POSIX, `;` on Windows; overrides `CLAUDE_CONFIG_DIR`. Missing or unreadable directories are skipped. |
| **Codex (OpenAI)** | `~/.codex/sessions/YYYY/MM/DD/rollout-*.jsonl` | Reads `token_count` events (per-call and cumulative usage) and `function_call` entries for tool tracking; attributes cost by project working directory. `codeburn report --provider codex` views Codex alone. |
| **Cursor** | SQLite `state.vscdb` under `globalStorage`: macOS `~/Library/Application Support/Cursor/User/globalStorage/`, Linux `~/.config/Cursor/User/globalStorage/`, Windows `%APPDATA%/Cursor/User/globalStorage/`; results cached at `~/.cache/codeburn/cursor-results.json` | Input tokens come from Cursor's own per-conversation context meter (`composerData.promptTokenBreakdown`), credited once per conversation on a stable anchor; tool calls and shell commands are read from the agent stream (`agentKv`), and Composer house models are priced from Cursor's published rates. Output is a reply-text estimate and cache tokens are server-side only, so figures are marked estimated and undercount the Cursor admin console for long conversations. The cache auto-invalidates when the database changes; first run on a large database can take a minute. |
| **OpenCode** | SQLite `~/.local/share/opencode/opencode*.db` (respects `XDG_DATA_HOME`) | Queries `session`, `message`, and `part` read-only and recalculates cost via LiteLLM (falling back to OpenCode's own cost field for unpriced models). Subtask sessions (`parent_id IS NOT NULL`) are excluded to avoid double counting; multiple channel databases are supported. |
| **Gemini CLI** | `~/.gemini/tmp/<project>/chats/session-*.json` | One JSON file per session with real token counts (input, output, cached, thoughts) per message, so no estimation is needed. Input is reported inclusive of cached, so CodeBurn subtracts cached before pricing to avoid double charging. |
| **Antigravity (CLI & IDE)** | Session files under `.gemini/` folders, plus the running language server | Pulls granular trajectory and pricing from the language server process. For the short-lived CLI, optionally install a status-line hook with `codeburn antigravity-hook install` so usage is captured between menubar refreshes. The IDE is detected via the `--app-data-dir antigravity-ide` flag on Windows. |
| **GitHub Copilot** | `~/.copilot/session-state/` (legacy CLI); VS Code/VSCodium `workspaceStorage/*` chat sessions, `GitHub.copilot-chat/transcripts/`, and the `agent-traces.db` OpenTelemetry store; JetBrains IDEs (IntelliJ, PyCharm, …) under `~/.config/github-copilot/<ide>/<kind>/<storeId>/copilot-*-nitrite.db` | The OTel SQLite store is preferred when present (it carries real input/output/cache token counts). Other sources carry no explicit counts, so tokens are estimated from content length and the model is inferred from tool call ID prefixes. JetBrains sessions read from a Nitrite (H2 MVStore) `.db`; project comes from the plugin's `projectName` field (else the `.git` root of a referenced file). See [docs/providers/copilot.md](docs/providers/copilot.md). |
| **Kiro** | `.chat` JSON files | Token counts are estimated from content length. The model is not exposed, so sessions are labeled `kiro-auto` and costed at Sonnet rates. |
| **Mistral Vibe** | `~/.vibe/logs/session/` (or `$VIBE_HOME/logs/session/`); each folder has `meta.json` + `messages.jsonl` | Reads cumulative prompt/completion totals and model pricing from `meta.json`, then the first user prompt and tool calls from `messages.jsonl`. Emits one record per session (source data is cumulative, not per turn); subagent sessions under `agents/` are counted separately. |
| **OpenClaw** | `~/.openclaw/agents/*.jsonl` (legacy `.clawdbot`, `.moltbot`, `.moldbot`) | Token usage comes from assistant message `usage` blocks; the model from `modelId` or `message.model`. |
| **Warp** | `~/Library/Group Containers/2BBY89MBSN.dev.warp/Library/Application Support/dev.warp.Warp-Stable/warp.sqlite` (Preview fallback) | Reads `agent_conversations`, `ai_queries`, and `blocks`, emitting one call per finalized exchange. Exchange token share is estimated from prompt-size weighting normalized to conversation totals; `run_command` blocks attach to the nearest preceding exchange by timestamp. |
| **Zed** | SQLite `~/Library/Application Support/Zed/threads/threads.db` (Linux `~/.local/share/zed/threads/`) | One row per agent thread; the blob is zstd-compressed JSON with per-request token usage (input, output, cache read, cache write) and the thread's model. Threads are topped up to the exact cumulative counter so totals match the store. Needs Node 22.15+ for built-in zstd. |
| **Forge** | SQLite `~/.forge/.forge.db` | Queries `conversations` read-only and parses `context.messages`. Assistant usage entries provide prompt, completion, and cached counts; CodeBurn subtracts cached from prompt for input pricing, emits one call per assistant message, and extracts tool calls plus shell commands. |
| **Pi / OMP** | `~/.pi/agent/sessions/<sanitized-cwd>/*.jsonl` (Pi), `~/.omp/agent/sessions/<sanitized-cwd>/*.jsonl` (OMP) | Each assistant message carries usage (input, output, cacheRead, cacheWrite) plus inline `toolCall` blocks. Tool names normalize to the standard set (`bash``Bash`, `dispatch_agent``Agent`); bash commands come from `toolCall.arguments.command`. |
| **Codebuff** (formerly Manicode) | `~/.config/manicode/projects/<project>/chats/<chatId>/chat-messages.json` (honors `CODEBUFF_DATA_DIR`; walks `manicode-dev` / `manicode-staging`) | Bills in credits, so each completed assistant message is costed at the public rate of $0.01/credit via `msg.credits`. When an upstream provider's stashed RunState records token-level usage (`message.metadata.runState.sessionState.mainAgentState.messageHistory[*].providerOptions`), the real tokens and LiteLLM cost take precedence. Native tool names (`read_files`, `str_replace`, `run_terminal_command`, `spawn_agents`) normalize to `Read`, `Edit`, `Bash`, `Agent`. |
| **Cline / Roo Code / KiloCode** | VS Code `globalStorage`: Cline at `saoudrizwan.claude-dev` and `~/.cline/data`; Roo Code and KiloCode across VS Code, VS Code Insiders, and VSCodium | Cline-family agents. CodeBurn reads `ui_messages.json` from each task directory, extracting token counts from `type: "say"` entries with `say: "api_req_started"`. |
| **IBM Bob** | `User/globalStorage/ibm.bob-code/tasks/<task-id>/` (GA `IBM Bob` and preview `Bob-IDE` app folders) | Reads `ui_messages.json` for API request token/cost records and `api_conversation_history.json` for the selected model. |
| **Kimi Code CLI** | `$KIMI_SHARE_DIR/sessions/<workdir-hash>/<session-id>/` or `~/.kimi/sessions/<workdir-hash>/<session-id>/` | Reads `wire.jsonl` `StatusUpdate.token_usage` records, mapping `input_other`, `input_cache_read`, `input_cache_creation`, and `output` into the standard token columns; includes subagents under each session's `subagents/` folder. |
| **LingTai TUI** | `~/.lingtai/<agent>/logs/token_ledger.jsonl` plus project homes from `~/.lingtai-tui/registry.jsonl` (`<project>/.lingtai/<agent>/logs/token_ledger.jsonl`); honors `LINGTAI_HOME` / `LINGTAI_TUI_HOME` | Reads LingTai's append-only token ledger, mapping `input - cached` to fresh input, `cached` to cache reads, `output` to output, and `thinking` to reasoning. Nested daemon ledgers are skipped because parent ledgers already mirror daemon usage with `source`/`run_id` tags. |
| **Vercel AI Gateway** | [Vercel AI Gateway reporting API](https://vercel.com/docs/ai-gateway/capabilities/custom-reporting) (cloud, not local logs) | Set `AI_GATEWAY_API_KEY` or `VERCEL_OIDC_TOKEN` (from `vercel env pull` / `vercel dev`); requires a Vercel plan with Custom Reporting. Without credentials it's skipped silently in the combined dashboard. |
| **Claude Code** | `~/.claude/projects/<sanitized-path>/<session-id>.jsonl` | 每条 assistant 条目包含模型名称、token 用量(inputoutputcache readcache 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 计数(inputoutputcachedthoughts),因此无需估算。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 IDEIntelliJPyCharm、…)位于 `~/.config/github-copilot/<ide>/<kind>/<storeId>/copilot-*-nitrite.db` 下 | 存在时优先使用 OTel SQLite 存储(包含真实的 input/output/cache token 计数)。其他来源没有显式计数,因此 token 根据内容长度估算,模型从工具调用 ID 前缀推断。JetBrains 会话从 NitriteH2 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 用量(inputoutputcache readcache write)及线程模型。线程会补足到精确累计计数器,使合计与存储一致。内置 zstd 需要 Node 22.15+。 |
| **Forge** | SQLite `~/.forge/.forge.db` | 以只读方式查询 `conversations` 并解析 `context.messages`。assistant usage 条目提供 promptcompletion cached 计数;CodeBurn 从 prompt 中减去 cached 用于 input 定价,每条 assistant 消息输出一次调用,并提取工具调用和 shell 命令。 |
| **Pi / OMP** | `~/.pi/agent/sessions/<sanitized-cwd>/*.jsonl`Pi)、`~/.omp/agent/sessions/<sanitized-cwd>/*.jsonl`OMP | 每条 assistant 消息包含用量(inputoutputcacheReadcacheWrite)以及内联 `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 CodeVS Code Insiders VSCodium | Cline 系列 agentCodeBurn 从每个任务目录读取 `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 deduplicates messages (by API message ID for Claude, by cumulative token cross-check for Codex, by conversation/timestamp for Cursor, by session ID for Gemini, by session+message ID for OpenCode, by responseId for Pi/OMP, by chat folder + message ID for Codebuff, by session+message ID for Kimi), filters by date range per entry, and classifies each turn.
CodeBurn 对消息进行去重(Claude 按 API message IDCodex 按累计 token 交叉校验,Cursor 按 conversation/timestampGemini 按 session IDOpenCode 按 session+message IDPi/OMP 按 responseIdCodebuff 按 chat folder + message IDKimi 按 session+message ID),按每条记录过滤日期范围,并对每一轮对话进行分类。
</details>
## Environment Variables
## 环境变量
<details>
<summary><strong>Override data directories and paths</strong></summary>
<summary><strong>覆盖数据目录和路径</strong></summary>
| Variable | Description |
|----------|-------------|
| `CLAUDE_CONFIG_DIR` | Override Claude Code data directory (default: `~/.claude`) |
| `CLAUDE_CONFIG_DIRS` | OS-delimited list of Claude data directories to scan together (e.g. `~/.claude-work:~/.claude-personal`). Sessions merge into one row per project. Overrides `CLAUDE_CONFIG_DIR` when set. |
| `CODEX_HOME` | Override Codex data directory (default: `~/.codex`) |
| `CODEBUFF_DATA_DIR` | Override Codebuff data directory (default: `~/.config/manicode`) |
| `FACTORY_DIR` | Override Droid data directory (default: `~/.factory`) |
| `KIMI_SHARE_DIR` | Override Kimi Code CLI share directory (default: `~/.kimi`) |
| `KIMI_MODEL_NAME` | Override Kimi model name when Kimi sessions do not record the model |
| `LINGTAI_HOME` | Override LingTai data directory (default: `~/.lingtai`) |
| `LINGTAI_TUI_HOME` | Alternate override for LingTai data directory; `LINGTAI_HOME` takes precedence |
| `LINGTAI_TUI_GLOBAL_DIR` | Override LingTai TUI global directory used for project registry discovery (default: `~/.lingtai-tui`) |
| `QWEN_DATA_DIR` | Override Qwen data directory (default: `~/.qwen/projects`) |
| `VIBE_HOME` | Override Mistral Vibe home directory (default: `~/.vibe`) |
| `WARP_DB_PATH` | Override Warp database path (default: Warp Stable, then Warp Preview) |
| `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>
## Sponsoring CodeBurn
## 赞助 CodeBurn
CodeBurn is free, runs entirely on your machine, and exists to cut your AI bill. If it has already saved you more than a sponsorship costs, consider sending a little of that back.
CodeBurn 免费,完全在你的机器上运行,旨在降低你的 AI 账单。如果它已经为你节省的金额超过了赞助费用,不妨回馈一部分。
Keeping 30 integrations accurate is constant work. The tools underneath change every week: Cursor reshapes its database, Claude moves a config path, new models ship at new prices. Sponsorship keeps CodeBurn current with all of it, so the numbers you see are always the real ones.
保持 30 个集成的准确性是一项持续工作。底层工具每周都在变化:Cursor 重构数据库,Claude 迁移配置路径,新模型以新价格发布。赞助能让 CodeBurn 跟上所有这些变化,因此你看到的数字始终是真实的。
Where your sponsorship goes:
你的赞助将用于:
- **Honest numbers.** New models and price changes mapped quickly, so your cost is the real cost, not a guess.
- **More tools.** Every one of the 30 providers started as a single file. Sponsorship funds the next one.
- **Fast fixes.** When a vendor breaks something, paid time is what gets it patched now instead of someday.
- **真实数字。** 快速映射新模型和价格变动,让你的成本是真实成本,而非猜测。
- **更多工具。** 30 个提供商中的每一个最初都只是一个文件。赞助资助下一个集成。
- **快速修复。** 当供应商破坏某些功能时,付费时间让它现在就能修复,而不是等到某天。
Sponsoring as a team or company? Your logo lands right here, in front of every developer who opens the repo. The first sponsor gets it to themselves until the next one shows up.
以团队或公司名义赞助?你的 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 History
## Star 历史
<a href="https://www.star-history.com/?repos=getagentseal%2Fcodeburn&type=date&legend=top-left">
<picture>
@@ -674,13 +681,13 @@ Sponsoring as a team or company? Your logo lands right here, in front of every d
</picture>
</a>
## License
## 许可证
MIT
CodeBurn is an AgentSeal open-source project and is not affiliated with CodeBurn Bt. or codeburn.hu.
CodeBurn AgentSeal 开源项目,与 CodeBurn Bt. codeburn.hu 无任何关联。
## Credits
## 致谢
Pricing data from [LiteLLM](https://github.com/BerriAI/litellm). Exchange rates from [Frankfurter](https://www.frankfurter.app/).
定价数据来自 [LiteLLM](https://github.com/BerriAI/litellm). 汇率数据来自 [Frankfurter](https://www.frankfurter.app/).
Built by [AgentSeal](https://agentseal.org).
[AgentSeal](https://agentseal.org). 构建