codeburn-claude-cost-dashboard

用途

CodeBurn 是一个交互式 TUI（终端用户界面）仪表盘，用于可视化 Claude Code 的 token 用量、成本以及任务明细。它直接从本地磁盘读取 Claude Code 会话记录（位于 ~/.claude/projects/），按项目、模型、活动类型、MCP 服务器和工具进行统计。整个过程无需 API 密钥、无需代理，属于纯本地文件分析。

主要能力

交互式 TUI 仪表盘，默认展示最近 7 天数据。
时间周期快捷命令：today、month，以及通过 -p 标志显式指定周期。
紧凑单行摘要（status），支持 JSON 格式输出。
数据导出：CSV（today、7d、30d 三个表）和 JSON。
macOS 菜单栏小组件（需 SwiftBar），每 5 分钟刷新，显示今日成本及明细下拉。
13 类任务分类（确定性规则，不调用 LLM）：Coding、Debugging、Feature Dev、Refactoring、Testing、Exploration、Planning、Delegation、Git Ops、Build/Deploy、Brainstorming、Conversation、General。
一次性成功率（One-Shot Rate）：针对编辑密集型类别，检测 Edit → Bash → Edit 重试循环，显示编辑轮次首次即成功的百分比。
定价数据来自 LiteLLM 模型价格，自动缓存 24 小时于 ~/.cache/codeburn/，覆盖输入、输出、缓存写入、缓存读取和网络搜索成本；获取失败时回退到硬编码价格。

使用方式

安装：

npm install -g codeburn
# 或无需安装直接运行
npx codeburn

要求：Node.js 20+，已安装 Claude Code（会话数据位于 ~/.claude/projects/）。

常用命令：

# 交互式 TUI 仪表盘（默认：最近 7 天）
codeburn

# 时间周期快捷命令
codeburn today
codeburn month
codeburn report -p month      # 显式周期标志

# 紧凑单行摘要
codeburn status
codeburn status --format json

# 导出数据
codeburn export               # CSV：today、7d、30d
codeburn export -f json       # JSON 导出

# macOS 菜单栏小组件（需 SwiftBar）
codeburn install-menubar
codeburn uninstall-menubar

TUI 键盘导航：← → 方向键在 Today / 7 Days / Month 之间切换；1 2 3 为周期快捷键；q 退出。

macOS 菜单栏设置：

# 1. 安装 SwiftBar
brew install --cask swiftbar

# 2. 安装 CodeBurn 插件
codeburn install-menubar

# 3. 启动 SwiftBar — 菜单栏出现 CodeBurn 火焰图标
# 每 5 分钟刷新，显示今日成本 + 明细下拉

移除：codeburn uninstall-menubar

导出示例：

# 导出 CSV（三个表：today、7d、30d）
codeburn export
# 输出：codeburn-export-2026-04-14.csv

# 导出 JSON
codeburn export -f json
# 输出：codeburn-export-2026-04-14.json

JSON 导出结构示例：

{
  "exported_at": "2026-04-14T10:00:00Z",
  "periods": {
    "today": {
      "total_cost": 1.42,
      "total_tokens": 284000,
      "by_project": { "my-app": 0.89, "other-project": 0.53 },
      "by_model": { "claude-sonnet-4-5": 1.10, "claude-opus-4-5": 0.32 },
      "by_activity": {
        "Coding": { "cost": 0.65, "turns": 34, "one_shot_rate": 0.88 },
        "Debugging": { "cost": 0.41, "turns": 18, "one_shot_rate": 0.72 }
      }
    },
    "7d": { ... },
    "30d": { ... }
  }
}

编程式使用（TypeScript）：

import { parseSessions } from 'codeburn/parser';
import { calculateCost } from 'codeburn/models';
import { classifyTurn } from 'codeburn/classifier';

// 解析日期范围内的所有会话
const sessions = await parseSessions({
  startDate: new Date('2026-04-01'),
  endDate: new Date('2026-04-14'),
});

// 会话按 API 消息 ID 去重
for (const turn of sessions.turns) {
  const category = classifyTurn(turn);
  const cost = await calculateCost(turn.model, turn.usage);
  console.log(`${category}: $${cost.toFixed(4)}`);
}

// 以编程方式获取状态摘要
import { getStatus } from 'codeburn/format';

const status = await getStatus();
console.log(status);
// → "🔥 Today: $1.42 (284k tokens) | Month: $18.30 (3.6M tokens)"

// 用于脚本的 JSON 格式
const statusJson = await getStatus({ format: 'json' });
const data = JSON.parse(statusJson);
// { today: { cost: 1.42, tokens: 284000 }, month: { cost: 18.30, tokens: 3600000 } }

常见模式：

在 CI/Shell 脚本中检查每日成本：

#!/bin/bash
# 添加到 .zshrc 或在 CI 中运行以记录每日 AI 支出
SPEND=$(codeburn status --format json | jq '.today.cost')
echo "Today's Claude spend: \$$SPEND"

# 超过阈值时告警
if (( $(echo "$SPEND > 5.00" | bc -l) )); then
  echo "⚠️  High AI spend today: \$$SPEND"
fi

导出并用 jq 分析：

# 导出 JSON 并按模型分析
codeburn export -f json | jq '.periods["7d"].by_model'

# 找出本月最昂贵的项目
codeburn export -f json | jq '
  .periods["30d"].by_project
  | to_entries
  | sort_by(-.value)
  | .[0]
'

自动化周报：

#!/bin/bash
# weekly-ai-report.sh — 通过 cron 在周一运行
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"
echo "[$DATE] Report saved to $OUTPUT_DIR/week-$DATE.json"

数据来源

Claude Code 将会话记录存储为 JSONL：

~/.claude/projects/<sanitized-path>/<session-id>.jsonl

每个 assistant 条目包含：模型名称、token 用量（input/output/cache_read/cache_write）、tool_use 块、时间戳。CodeBurn 按 API 消息 ID 去重，防止跨会话重复计数。

项目结构

src/
  cli.ts          # Commander.js 入口点
  dashboard.tsx   # Ink TUI（终端中的 React）
  parser.ts       # JSONL 读取器、去重、日期过滤
  models.ts       # LiteLLM 定价、成本计算
  classifier.ts   # 13 类任务分类器
  types.ts        # 类型定义
  format.ts       # 文本渲染（状态栏）
  menubar.ts      # SwiftBar 插件生成器
  export.ts       # CSV/JSON 多周期导出

适用场景

开发者希望了解自己在 Claude Code 上的 token 消耗与成本分布。
按项目、模型、活动类型分析 AI 使用情况。
在 CI 或 shell 脚本中监控每日 AI 支出并设置阈值告警。
自动化生成周报或月度成本报告。
在 macOS 菜单栏实时查看今日成本。

限制

需要 Node.js 20+ 和已安装的 Claude Code（会话数据位于 ~/.claude/projects/）。
仅分析本地 Claude Code 会话记录，不涉及其他来源。
macOS 菜单栏小组件需要 SwiftBar。
定价依赖 LiteLLM 模型价格，获取失败时回退到硬编码价格。
任务分类为确定性规则，不调用 LLM。
其他平台支持情况暂未提供。