内容
<h1 align="center">
<picture>
<source media="(prefers-color-scheme: dark)" srcset="docs/assets/wordmark-dark.png">
<img src="docs/assets/wordmark-light.png" alt="tokentrace" height="42">
</picture>
</h1>
<p align="center">
<strong>自动记录编码代理的会话。</strong><br>
每个 Claude Code 和 Codex 会话 — 记录、成本、差异 — 均在本地保存，无需任何设置。
</p>
<p align="center">
<a href="https://www.npmjs.com/package/@j___avi/tokentrace"><img src="https://img.shields.io/npm/v/@j___avi/tokentrace?color=000&labelColor=000&style=flat-square" alt="npm"></a>
<a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-000?labelColor=000&style=flat-square" alt="MIT"></a>
<a href="https://github.com/fjgbue/tokentrace"><img src="https://img.shields.io/badge/by-fjgbue-000?labelColor=000&style=flat-square" alt="作者"></a>
</p>
<br>
<p align="center">
<img src="docs/assets/dashboard-screenshot.png" width="820" alt="tokentrace dashboard showing session list, cost breakdown, and cost-per-day chart" />
</p>
<br>
## 安装
```bash
npm install -g @j___avi/tokentrace
tt install
```
就这样。**安装后请重启您的 shell**。现在每个会话都将自动记录。
```
✓ Claude Code hook 已安装 → ~/.claude/settings.json
✓ Codex CLI shim 已安装 → ~/.zshrc
✓ Codex Desktop watcher 已安装 → ~/Library/LaunchAgents/io.tokentrace.codex-watcher.plist
```
## 自动记录的内容
| 界面 | 状态 |
|---|---|
| Claude Code CLI | ✅ 自动 |
| Claude Code Desktop | ✅ 自动 — 使用相同的 hook 文件 |
| Claude Code VS Code 扩展 | ✅ 自动 — 使用相同的 hook 文件 |
| Codex CLI | ✅ 自动 — 在 `tt install` 后透明地使用 shell shim |
| Codex Desktop 应用 | ✅ 自动 — 每 30 秒运行一个后台监视器（macOS） |
| VS Code / IDE 插件 | 🔜 计划中 |
## 查看会话
```bash
tt summarize
```
```
2026-05-25 ok tokens=223K cost=$1.43 changed=7 claude-sonnet-4-6 Refactor auth middleware to use JWT
2026-05-24 ok tokens=104K cost=$0.71 changed=4 claude-sonnet-4-6 Add dark mode to settings page
2026-05-24 ok tokens=44K cost=$0.23 changed=2 gpt-5.5 Fix race condition in queue processor
2026-05-23 ok tokens=84K cost=$0.43 changed=17 gpt-5.5 DESKTOP Write unit tests for billing module
2026-05-22 ok tokens=531K cost=$11.24 changed=12 claude-opus-4-7 Migrate Postgres schema to multi-tenancy
```
## 打开仪表盘
```bash
tt serve # 启动服务器 + 打开浏览器
tt stop # 停止服务器
```
浏览会话、比较随时间变化的成本、检查记录和差异、设置增值税率。仪表盘显示每个会话的界面 — CLI、桌面应用或 IDE 扩展。
## 每个记录会话的内容
```
~/.tokentrace/runs/<session-id>/
run.json # 代理、模型、tokens、成本、git 状态、持续时间
transcript.txt # 完整的对话 — 用户提示和代理回复
diff.patch # 代理触及的每个文件，作为统一的补丁
summary.md # 可读的单页摘要
report.html # 独立的 HTML 报告，可离线打开
```
单个会话的 `tt summarize` 输出示例：
```
2026-05-25T09:12Z ok tokens=223K cost=$1.43 changed=7 claude
```
## 为什么存在
代理会话消失在终端滚动缓冲区中。你要么信任结果，要么不信任，结果之间没有任何中间状态。tokentrace 为你提供了证据：
- **成本可见性** — 每个会话的 token 支出、每日成本、累计总成本
- **信任** — 完整的记录 + git 差异附在每个会话上
- **调试** — 当代理执行意外操作时，日志准确告诉你发生了什么
- **PR 证据** — 将 `summary.md` 或 `diff.patch` 附加到拉取请求中，以便审查者查看代理实际执行的操作
## MCP 服务器 — 在 Claude Code 中查询您的会话
tokentrace 附带一个 MCP 服务器，为 Claude Code 提供直接访问本地会话数据的方式。配置后，您可以在会话中用纯英文询问有关会话的问题 — 无需仪表盘。
**设置：** 将以下内容添加到 `~/.claude/mcp.json`（如果文件不存在，请创建）：
```json
{
"mcpServers": {
"tokentrace": {
"command": "npx",
"args": ["-y", "-p", "@j___avi/tokentrace", "tokentrace-mcp"]
}
}
}
```
重启 Claude Code，然后在任何会话中询问：
> *"这周我花了多少钱购买 tokens？"*
> *"我上次会话中更改了什么？"*
> *"显示昨天的差异"*
Claude 将直接查询您的 `~/.tokentrace/runs/` 文件夹 — 不会离开您的机器。在 Claude Code CLI、桌面应用和 VS Code 扩展中均可使用。
## 诚实的局限性
tokentrace 读取从每个界面可用的内容。有些数据不是由代理本身记录的：
| 界面 | Token 计数 | 成本 | 记录 |
|---|---|---|---|
| Claude Code CLI / Desktop / VS Code | ✅ 输入 + 输出 | ✅ 精确 | ✅ 完整 |
| Codex CLI（通过 shim） | ✅ 输入 + 输出 | ✅ 精确 | ✅ 完整 |
| Codex Desktop | ✅ 输入 + 输出（每回合） | ✅ 精确 | ✅ 完整 |
## 开发
```bash
git clone https://github.com/fjgbue/tokentrace
cd tokentrace
npm install
npm test # 48 个测试
# 使用演示数据运行
node scripts/gen-demo-data.mjs
TOKENTRACE_RUNS_DIR=~/.tokentrace-demo/runs tt serve
```
## 贡献
欢迎贡献。请参阅 [CONTRIBUTING.md](CONTRIBUTING.md)。在可移植的本地优先跟踪中保持新功能的接地气。
## 许可证
MIT — [fjgbue](https://github.com/fjgbue)
