1. 项目概述:Claude Code Tokens Tracker工具
作为一名长期使用Claude API的开发者,我深知token消耗监控的重要性。每次看到账单上那些不明不白的token支出,总让人头疼不已。为此,我开发了这款Claude Code Tokens Tracker工具,它就像是你代码中的"智能电表",能实时监测每个API调用的token消耗情况。
这个工具的核心价值在于:
- 实时可视化监控:告别"黑盒"操作,每个API调用的token消耗都清晰可见
- 多维度数据分析:按工具、文件、时间等维度深入分析使用情况
- 零侵入集成:通过hook机制自动收集数据,无需修改现有代码
提示:虽然工具能精确统计token用量,但实际账单可能受服务商套餐、促销活动等因素影响,建议仅作为优化参考。
2. 核心功能解析
2.1 实时监控系统
监控模块采用轮询机制,每2秒扫描一次会话记录文件。其工作原理如下:
- 通过文件系统watcher监听.claude/sessions目录变化
- 解析最新会话JSON文件,提取token使用数据
- 聚合统计:总消耗、输入/输出token比例、各工具调用占比
关键数据结构示例:
javascript复制{
"total_tokens": 2456,
"input_tokens": 892,
"output_tokens": 1564,
"tools": [
{"name": "code-generator", "count": 3, "tokens": 1200},
{"name": "doc-writer", "count": 5, "tokens": 800}
]
}
2.2 历史统计功能
每日统计模块采用增量存储设计:
- 原始数据:按天存储为JSON文件(data/daily/YYYY-MM-DD.json)
- 聚合数据:生成周报、月报时动态计算,避免冗余存储
统计维度包括:
- 时间趋势分析(日/周/月)
- 工具使用热力图(按小时分布)
- 文件级消耗排名
2.3 Hook收集机制
数据收集采用Claude官方提供的PostToolUse钩子:
json复制{
"hooks": {
"PostToolUse": [{
"hooks": [{
"type": "command",
"command": "node /path/to/token-hook.js",
"async": true
}]
}]
}
}
这种设计保证了:
- 异步执行不影响主流程性能
- 完整记录每次工具调用的上下文
- 自动关联会话ID和时间戳
3. 环境准备与安装
3.1 系统要求检查
在开始前,请确保满足以下条件:
bash复制# Node.js版本检查(必须≥14.0)
node --version
# 应返回类似:v16.14.2
# npm版本检查
npm --version
# 应返回类似:8.5.0
如果版本不符,推荐使用nvm管理多版本Node环境:
bash复制# 安装nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.3/install.sh | bash
# 安装指定Node版本
nvm install 16.14.2
3.2 工具安装步骤
- 克隆仓库到Claude工具目录:
bash复制cd ~/.claude/tools
git clone https://github.com/luoshanxuli/token-tracker.git
- 初始化依赖:
bash复制cd token-tracker
npm install
- 配置hook(关键步骤):
编辑~/.claude/settings.json,添加hook配置:
json复制{
"hooks": {
"PostToolUse": [{
"hooks": [{
"type": "command",
"command": "node /absolute/path/to/token-hook.js",
"async": true
}]
}]
}
}
注意:Windows用户路径需使用双反斜杠或正斜杠,如:
"command": "node C:\\\\claude\\\\tools\\\\token-tracker\\\\token-hook.js"
4. 功能使用详解
4.1 实时监控面板
启动监控:
bash复制node ~/.claude/tools/token-tracker/monitor.js
界面元素解析:
- 头部摘要区:显示当前会话的token总量、成本估算、输入输出比例
- 最近操作区:最近10次工具调用详情,包括:
- 时间戳(精确到毫秒)
- 工具名称和版本
- 消耗token数
- 关联文件路径
- 文件热度区:token消耗最多的5个文件
- 工具消耗区:各工具调用次数和token占比
4.2 历史数据查询
基本查询命令:
bash复制# 查看当天统计
node daily-stats.js
# 查询指定日期(格式必须为YYYY-MM-DD)
node daily-stats.js 2026-03-05
# 生成周报(最近7天)
node daily-stats.js --week
# 导出全部历史数据
node daily-stats.js --all > stats.csv
高级筛选选项:
bash复制# 按工具过滤(支持通配符)
node daily-stats.js --tool=code-*
# 按文件路径过滤
node daily-stats.js --file=src/utils/*.js
# 设置时间范围
node daily-stats.js --from 2026-03-01 --to 2026-03-07
4.3 数据备份策略
工具默认将数据存储在data/目录下,建议设置定期备份:
bash复制# 简单压缩备份
tar -czvf token-stats-backup-$(date +%Y%m%d).tar.gz data/
# 使用rsync同步到远程
rsync -avz data/ user@backup-server:/path/to/backup/
5. 常见问题排查
5.1 Hook未触发问题
症状:监控面板无数据更新
排查步骤:
- 检查settings.json语法是否正确(可用JSONLint验证)
- 确认hook路径为绝对路径
- 查看Claude日志是否有错误输出:
bash复制tail -f ~/.claude/logs/claude.log - 手动测试hook是否正常工作:
bash复制node token-hook.js test
5.2 数据不一致问题
可能原因及解决方案:
- 时间不同步:确保系统时区设置正确
bash复制timedatectl status # Linux systemsetup -gettimezone # macOS - 文件权限问题:确保工具对数据目录有读写权限
bash复制chmod -R 755 ~/.claude/tools/token-tracker/data - 会话文件被清理:调整Claude的会话保留设置
5.3 性能优化建议
当数据量较大时(>10万条记录),建议:
- 启用数据库模式(需安装SQLite):
bash复制
npm install sqlite3 node migrate-to-sqlite.js - 设置数据保留策略:
bash复制
node cleanup.js --keep-days 30 - 对于长期运行的监控,建议使用PM2守护进程:
bash复制
pm2 start monitor.js --name token-tracker
6. 高级使用技巧
6.1 自定义监控指标
编辑config/metrics.json可添加自定义统计维度:
json复制{
"custom_metrics": [
{
"name": "cost_per_feature",
"type": "group_by",
"field": "tool_category",
"aggregate": ["sum(tokens)", "avg(tokens)"]
}
]
}
6.2 告警系统集成
设置token阈值告警:
- 创建
config/alerts.json:
json复制{
"daily_limit": 50000,
"notify_command": "sendmail -s 'Token警报' admin@example.com"
}
- 在crontab中添加每日检查:
bash复制0 9 * * * node ~/.claude/tools/token-tracker/check-alerts.js
6.3 与CI/CD集成
在构建流程中添加token审计:
yaml复制# .gitlab-ci.yml示例
token_audit:
stage: audit
script:
- node token-tracker/daily-stats.js --since-last-commit > token_report.md
- python check_token_budget.py
artifacts:
paths:
- token_report.md
7. 开发路线图
当前版本已实现核心监控功能,未来计划:
- 可视化增强:集成Web Dashboard(基于Express+Vue)
- 预测功能:基于历史数据的token消耗预测
- 团队协作版:多用户token配额管理
- 插件系统:支持自定义数据分析插件
欢迎通过GitHub提交Issue或PR参与开发:
bash复制git clone https://github.com/luoshanxuli/token-tracker.git
cd token-tracker
git checkout -b feature/your-idea