需要按项目、模型和活动类型追踪 Claude Code 的…

适用于已使用 Claude Code 并希望从本地会话日志查看、导出和告警 AI 编程成本的开发者。

适用场景

解决思路

1. 安装并运行 CodeBurn：执行 `npm install -g codeburn` 全局安装，或用 `npx codeburn` 免安装运行。
2. 启动交互式 TUI 仪表盘：执行 `codeburn`，默认查看最近 7 天数据。
3. 使用时间范围快捷命令：执行 `codeburn today` 查看今天，执行 `codeburn month` 查看本月，或执行 `codeburn report -p month` 显式指定时间段。
4. 查看紧凑单行摘要：执行 `codeburn status`；需要脚本处理时执行 `codeburn status --format json`。
5. 导出数据：执行 `codeburn export` 导出 CSV，执行 `codeburn export -f json` 导出 JSON。
6. 安装或卸载 macOS 菜单栏组件：执行 `codeburn install-menubar` 安装，执行 `codeburn uninstall-menubar` 卸载；菜单栏组件需要 SwiftBar。
7. 在 TUI 中导航：按 `←`/`→` 在 Today / 7 Days / Month 间切换，按 `1`/`2`/`3` 使用时间段快捷键，按 `q` 退出。
8. 利用本地文件分析：CodeBurn 直接从 `~/.claude/projects/` 读取 Claude Code 会话记录，可视化 token 用量、成本，以及按项目、模型、活动类型、MCP server 和工具的任务拆分；无需 API key、无需代理。
9. 使用 13 个确定性任务分类识别活动类型：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 工具 spawn）；Git Ops（Bash 中的 git push/commit/merge）；Build/Deploy（npm build、docker、pm2）；Brainstorming（brainstorm、what if、design）；Conversation（无工具纯文本交换）；General（Skill 工具或未分类）。这些分类不调用 LLM。
10. 查看 one-shot rate：对编辑密集类别，CodeBurn 检测 Edit → Bash → Edit 重试循环，并显示编辑轮次首次成功且无需重试的百分比；例如 90% 表示 10 次中 9 次首次成功。
11. 依赖 LiteLLM 定价：模型价格从 LiteLLM 获取并自动缓存 24 小时到 `~/.cache/codeburn/`，覆盖 input、output、cache write、cache read 和 web search 成本；获取失败时回退硬编码价格。
12. 理解数据源：Claude Code 将会话记录存为 JSONL，路径为 `~/.claude/projects/<sanitized-path>/<session-id>.jsonl`；每个 assistant entry 包含模型名、token 用量（input/output/cache_read/cache_write）、tool_use blocks 和时间戳；CodeBurn 按 API message ID 去重，避免跨 session 重复计数。
13. 配置 macOS 菜单栏：先执行 `brew install --cask swiftbar` 安装 SwiftBar，再执行 `codeburn install-menubar` 安装插件；启动 SwiftBar 后菜单栏出现 CodeBurn 火焰图标，每 5 分钟刷新，显示今日成本 + 细分下拉。
14. 移除 macOS 菜单栏：执行 `codeburn uninstall-menubar`。
15. 导出 CSV 示例：执行 `codeburn export`，输出类似 `codeburn-export-2026-04-14.csv`，包含 today、7d、30d 三张表。
16. 导出 JSON 示例：执行 `codeburn export -f json`，输出类似 `codeburn-export-2026-04-14.json`；结构包含 `exported_at`、`periods.today.total_cost`、`total_tokens`、`by_project`、`by_model`、`by_activity`（含 cost、turns、one_shot_rate），以及 `7d`、`30d`。
17. 按项目结构定位能力：`src/cli.ts` 是 Commander.js 入口；`dashboard.tsx` 是 Ink TUI（React for terminals）；`parser.ts` 负责 JSONL 读取、去重、日期过滤；`models.ts` 负责 LiteLLM 定价与成本计算；`classifier.ts` 是 13 类任务分类器；`types.ts` 是类型定义；`format.ts` 负责文本渲染（状态栏）；`menubar.ts` 生成 SwiftBar 插件；`export.ts` 负责 CSV/JSON 多周期导出。
18. 在 TypeScript 中程序化集成：从 `codeburn/parser` 导入 `parseSessions`，从 `codeburn/models` 导入 `calculateCost`，从 `codeburn/classifier` 导入 `classifyTurn`；调用 `parseSessions({ startDate: new Date('2026-04-01'), endDate: new Date('2026-04-14') })`；遍历 `sessions.turns`，对每个 turn 调用 `classifyTurn(turn)` 和 `await calculateCost(turn.model, turn.usage)`，并输出分类与成本。
19. 程序化获取状态摘要：从 `codeburn/format` 导入 `getStatus`；`await getStatus()` 返回如 `🔥 Today: $1.42 (284k tokens) | Month: $18.30 (3.6M tokens)`；`await getStatus({ format: 'json' })` 返回 JSON 字符串，解析后得到 `today.cost`、`today.tokens`、`month.cost`、`month.tokens`。
20. 在 CI/Shell 脚本中做每日成本检查：用 `SPEND=$(codeburn status --format json | jq '.today.cost')` 获取今日花费，输出今日 Claude 花费；若超过阈值（如 `$5.00`），用 `bc -l` 比较并打印高花费告警。
21. 用 jq 导出并分析：执行 `codeburn export -f json | jq '.periods["7d"].by_model'` 按模型分析；用 `codeburn export -f json | jq '.periods["30d"].by_project | to_entries | sort_by(-.value) | .[0]'` 找本月最贵项目。
22. 自动化周报：创建 `weekly-ai-report.sh`，设置 `OUTPUT_DIR="$HOME/ai-cost-reports"`，执行 `mkdir -p "$OUTPUT_DIR"`；用 `DATE=$(date +%Y-%m-%d)`；执行 `codeburn export -f json > "$OUTPUT_DIR/week-$DATE.json"`；执行 `codeburn status >> "$OUTPUT_DIR/history.log"`；输出保存路径；通过 cron 在周一运行。
23. 排查无数据/No sessions found：执行 `ls ~/.claude/projects/` 和 `ls ~/.claude/projects/<project-name>/` 确认存在 `*.jsonl` 文件；执行 `node --version` 确认 Node.js 20+。
24. 排查定价获取失败/显示 $0.00：执行 `rm -rf ~/.cache/codeburn/` 清除价格缓存后重试；CodeBurn 会自动回退硬编码价格；再次运行 `codeburn today` 会重新从 LiteLLM 获取。
25. 排查菜单栏 widget 不更新：执行 `codeburn uninstall-menubar` 后执行 `codeburn install-menubar` 重装；确保 SwiftBar 正在运行，且插件目录指向 `~/Library/Application Support/SwiftBar/Plugins/`。
26. 排查双倍计数成本：CodeBurn 默认按 API message ID 去重；若数字异常高，执行 `find ~/.claude/projects/ -name "*.jsonl" | xargs wc -l | sort -rn | head -20` 列出所有会话文件并按大小排序检查重复。
27. 排查 TUI 渲染问题：执行 `echo $TERM` 确保终端支持 256 色（应为 `xterm-256color` 或类似）；可用 `COLORTERM=truecolor codeburn` 强制真彩色。

适用边界 · 注意事项

• 未安装 Claude Code，或 `~/.claude/projects/` 下没有 JSONL 会话数据时，CodeBurn 无数据可分析。
• Node.js 低于 20，或无法使用 npm/npx 安装运行 CodeBurn 时不适用。
• 需要 macOS 菜单栏组件时，必须先安装 SwiftBar；非 macOS 环境无法使用该菜单栏功能。