claudestat — Claude Code & OpenCode usage tracker with MCP

---

目录

• 为什么选择 claudestat？
• ClaudeStat 适合哪些人？
• 如果你……，请使用 ClaudeStat
• 询问 Claude 自身的情况
• 功能
• 快速开始
• 要求
• 安装
• 命令
• 仪表盘
• 库 API
• OpenCode 支持
• MCP 服务
• MCP Bundle（独立版）
• 配置
• 故障排除
• 常见问题
• 卸载
• 贡献
• 许可证

---

为什么选择 claudestat？

编码 Agent 领域有两种不同的需求：

• 发生了什么 — 费用、Token 总量、每日／每周／每月报告。ccusage 是历史分析方面的参考工具。
• 现在正在运行什么 — 实时会话、实时预算，在配额用尽之前。claudestat 和 OpenUsage 专注于此。

claudestat 会在 Claude Code 事件触发的瞬间进行挂钩，将所有数据保存在本地 SQLite 中，并提供实时 Web 仪表板、配额提醒和 MCP 服务。

	claudestat	ccusage	OpenUsage	Langfuse	Agent Trail
实时事件流	✅	部分支持	✅	✅	✅
实时终端跟踪（watch）	✅	—	—	—	—
Web 仪表板	✅	—	TUI	✅	✅
配额提醒 + 强制终止开关	✅	—	仅配额	—	—
循环／空转检测器	✅	—	—	—	—
MCP 服务（询问 Claude 自身情况）	✅	—	—	—	—
支持 Claude Code	✅	✅	✅	✅	✅
支持 OpenCode	✅	✅	✅	—	—
工具跟踪	✅	有限支持	—	✅	✅
Agent／子 Agent	✅	—	—	✅	✅
编排视图	✅	—	—	✅	✅
历史报告	✅	✅	部分支持	✅	✅
本地优先／SQLite（无需云端）	✅	✅	✅	可配置	✅

主要区别在于时机：ccusage 回答的是我昨天花了多少；claudestat 展示的是你编写代码时正在发生什么。Langfuse 和 Agent Trail 提供可观测性，但它们以云端为先，或需要配置基础设施。

如果 claudestat 对你有帮助，请点个 ⭐ — 这能帮助其他开发者找到它。

---

ClaudeStat 适合哪些人？

ClaudeStat 面向使用 AI 编码 Agent，并想了解这些 Agent 正在做什么、成本是多少，以及何时效率开始下降的开发者。

如果你符合以下情况，ClaudeStat 尤其有用：

• 使用 Claude Code
• 使用 OpenCode
• 同时运行多个编码 Agent
• 使用子 Agent 和编排
• 使用 MCP 服务
• 关注 Token 和 API 费用
• 处理长时间运行的 Agent 会话
• 希望使用本地／私有遥测（无需云端）
• 需要实时可见性，而不是会话结束后的报告

---

在以下情况下使用 ClaudeStat……

如果你想要以下功能，请使用 ClaudeStat：

• 实时监控 Claude Code
• 实时监控 OpenCode
• 跟踪 Token 用量和 AI 编码费用
• 查看哪些工具消耗的预算最多
• 监控 Agent 和子 Agent
• 检查 MCP 活动
• 检测上下文空转和循环
• 通过提醒和强制终止开关保护配额
• 了解多 Agent 编排
• 将遥测数据完全保存在本地

---

询问 Claude 自身情况

claudestat 自带 MCP 服务。注册后，你可以直接向 Claude Code 询问它自身的用量情况，无需离开终端。

claude mcp add claudestat -s user -- claudestat-mcp

然后直接提问：

> How much did I spend this week?
> What are my top 5 tools by cost?
> Break down my usage by model
> What's my cost projection for next month?

完整 MCP 参考 →

---

功能

• 实时工具调用追踪 —— 实时显示每次调用的耗时和令牌成本
• 支持 OpenCode —— 为 OpenCode 会话提供相同的实时仪表板（工具调用、提示词、模型、意图）
• 配额守护 —— 在使用量达到 70%、85%、95% 时发出提醒；可选的终止开关会在达到 X% 时阻止新会话
• 循环检测器 —— 标记上下文反复折腾的情况，并估算浪费的成本
• 热门工具 —— 了解哪些工具消耗了大部分预算；展开“其他”行可查看前 10 名以外的工具
• 成本预测 —— 使用线性回归，显示趋势、置信区间和 R²
• 计费区块 —— 跟踪 5 小时计费窗口和每个区块的累计支出（claudestat blocks）
• 会话分享 —— 将任意会话摘要导出为格式化的 ASCII 或 JSON（claudestat share）
• 52 周活动热力图 —— 在 Analytics 中查看全年编码活动
• 时段环比变化 —— Analytics KPI 显示与上一时段相比的 ↑↓% 趋势
• 项目搜索与筛选 —— 即时查找项目；按活动、成本或效率阈值筛选
• 编排指挥中心 —— 实时泳道视图，展示 CC+OC 多 Agent 运行情况：每个周期的成本、令牌（含缓存）、变更文件、Git 提交和模型细分；周期追踪记录在日志轮转后仍会保留
• Web 仪表板 —— 包含 7 个标签页：Live、History、Projects、Analytics、Top、System、Orchestrate
• MCP 服务 —— 提供 9 个工具，让 Claude 能回答有关自身使用情况的问题；可使用独立软件包 @statforge/claudestat-mcp-bundle
• 每周洞察 —— 分析使用模式并提供可操作的建议
• 多源支持 —— 一键切换 Claude Code 和 OpenCode 会话
• 来源筛选器 —— 在所有标签页中按 Claude Code / OpenCode 筛选 KPI、图表和工具排名
• 多工具协调 —— 实时意图面板，可检测真实冲突（CC 和 OC 编辑同一个文件）
• 程序化库 API —— 可直接在自己的工具中导入 dbOps、定价和智能分析函数（v1.13.0+，@experimental）
• KPI 迷你图表 —— KPI 卡片中的交互式柱状图，用于显示成本/区块变化；以及用于显示上下文变化的面积图
• 增强的标题栏布局 —— 紧凑型导航栏，显示模型名称、项目和统一高度的徽章

---

快速开始

npm install -g @statforge/claudestat && claudestat setup
open http://localhost:7337

启动一个 Claude Code 会话，即可查看事件流入。就这么简单。

---

要求

• Node.js >= 22（node:sqlite 的必需版本）
• 已安装 Claude Code（npm install -g @anthropic-ai/claude-code）

---

安装

npm install -g @statforge/claudestat && claudestat setup

claudestat setup 会安装 Claude Code 钩子，并将守护进程注册为系统服务——无需 sudo。每次登录时，守护进程都会自动启动（macOS 使用 launchd，Linux 使用 systemd，Windows 使用 Scheduled Task）。

使用 NVM？ 请确保当前使用的是默认 Node 版本：

nvm use default && npm install -g @statforge/claudestat && claudestat setup

设置完成后，重启 Claude Code，让钩子生效。

手动设置

npm install -g @statforge/claudestat
claudestat install   # installs hooks into Claude Code
claudestat start     # start the daemon manually

---

命令

命令	描述
claudestat setup	一键设置：安装钩子 + 将守护进程注册为系统服务
claudestat setup --uninstall	移除钩子和系统服务
claudestat start / stop / restart	管理后台守护进程
claudestat install / uninstall	安装或移除 Claude Code 钩子
claudestat watch	实时终端跟踪视图
claudestat status	显示配额、成本和消耗速率
claudestat top	按成本、调用次数或持续时间对工具排名
claudestat weekly	每周用量摘要
claudestat insights	深入分析用量：成本、缓存、效率、模型
claudestat project	使用线性回归预测成本
claudestat config	查看或编辑配置
claudestat doctor	检查安装状态并诊断问题
claudestat blocks	显示 5 小时计费区间历史记录
claudestat share [session-id]	将会话摘要导出为 ASCII 或 JSON（使用 --copy 复制到剪贴板）
claudestat export [format]	将会话数据导出为 JSON 或 CSV
claudestat roast	讽刺风格的用量分析
claudestat resume	恢复已暂停的会话
claudestat loops	列出检测到循环（上下文反复折腾）的会话
claudestat logs	显示守护进程日志（使用 -n、--follow、--level）
claudestat update	检查更新，并从 npm 安装最新版本
claudestat version	显示版本并检查更新

完整命令参考（含输出示例）→

---

仪表板

仪表板位于 http://localhost:7337，包含七个标签页：Live、History、Projects、Analytics、Top、System 和 Orchestrate。

仪表板详情 →

---

AI 开发基准

claudestat 由一位人类开发者与 AI 作为结对编程伙伴共同打造。AI 加快了实现过程，但架构、设计和工程决策始终由人类作出。恰如其分的是，claudestat 也会衡量自身：以下每项指标均来自其自身的事件数据库。

我们如何协作

人类负责	AI 实现，始终由人类审核
产品愿景与功能设计	TypeScript 服务生成
MCP 服务协议与设计	工具脚手架、仪表板组件
数据模型（SQLite 架构）	重构、测试脚手架
架构决策	配置解析、CLI 命令
代码审查与最终验收	文档、辅助脚本

工作流： 构思 → 规格说明 → AI 实现 → 人工审核 → 测试 → 改进 → 合并

开发过程是迭代式的，绝非只靠一个提示词完成：需求 → 准备上下文 → 生成 → 审查 → 修复 → 验证 → 重复。代码和测试一同交付；未经人工审核的内容一律不会合并。PR 均控制在预算范围内，必要时使用 /chained-pr 拆分。

AI 开发原则

• AI 从不作出产品决策。
• 每项实现都从书面规格说明开始。
• 文档被视为 AI 可执行的上下文。
• 所有生成的代码都必须经过人工审核。
• 优先维护架构，而非追求实现速度。
• 根据任务类型选择模型（复杂功能使用 Claude Code，快速迭代使用 OpenCode）。

辅助指标

指标	数值
AI 会话	记录了 116 次
测量的开发时间	约 344 小时
平均会话效率	77/100
主要模型	Claude Sonnet 4.6（48 次 CC 会话）
次要模型	OpenCode：DeepSeek V4 Flash/Pro、GLM-5、Mimo v2.5（68 次会话）

使用 ClaudeStat 测量——这是本项目自带的跟踪工具。数值为近似值。

---

OpenCode 支持

当你在运行 Claude Code 的同时运行 OpenCode 时，claudestat 会自动检测这两个会话，并在 Live 标签页中显示来源切换器。

点击 Claude Code 和 OpenCode，即可查看各个会话的实时视图——工具调用、提示词、模型名称、意图徽标和耗时——无需离开仪表板。

功能	Claude Code	OpenCode
工具调用（Read、Write、Bash、Edit……）	✅	✅
每个区块的提示词	✅	✅
模型名称	✅	✅
意图检测（探索中 / 实现中……）	✅	✅
会话费用	✅	✅
每周用量图表	✅	✅
每个区块的费用明细	✅	✅
配额 / 上下文窗口	✅	—

OpenCode 数据直接从其本地 SQLite 数据库读取，无需配置。

---

MCP 服务

claudestat 内置了一个 MCP 服务，提供 9 个用于查询用量统计的工具。注册一次即可：

claude mcp add claudestat -s user -- claudestat-mcp

然后向 Claude 提问：“我的配额状态如何？”、“显示我最近的会话”、“费用最高的 5 个工具”、“我的上下文窗口状态如何？”、“今天的摘要是什么？”。

该服务还会针对上下文饱和度（50/75/90%）、每周配额阈值和 5h 计费周期限制发送推送通知——无需你提问，Claude 就会主动提醒你。

从 v1.16.0 起，MCP 服务改用官方 @modelcontextprotocol/sdk（v1.30.0），取代手写的 JSON-RPC 引擎。这意味着符合标准的握手、与现代 MCP 客户端进行协议版本协商、在 stdin EOF 时可靠地启动和关闭，以及对工具参数进行正确的输入验证。公共 API 保持不变，因此现有注册仍可照常使用。

工具	描述
get_quota_status	5h 周期百分比、各模型的每周使用时长、消耗速率、套餐检测
get_current_session	最新会话费用、令牌、效率、循环次数
get_session_stats	最近 N 天的汇总统计
get_top_tools	按费用、调用次数或耗时排列的前 10 个工具
get_usage_insights	各项目费用、缓存节省、输出 / 输入比、使用高峰时段
get_model_breakdown	按 Claude 模型拆分的费用和会话数
get_weekly_insight	每周摘要及可执行建议
get_context_status	当前上下文窗口用量及饱和度条
get_daily_summary	今天与昨天及近 7 天平均值的对比

MCP 工具参考 →

MCP Bundle（独立版）

更倾向于使用更轻量的依赖？将 MCP 服务作为独立软件包安装——不含 CLI，也不含守护进程，只有 stdio MCP 服务及其 SQLite 读取器：

npm install -g @statforge/claudestat-mcp-bundle
claude mcp add claudestat -s user -- npx @statforge/claudestat-mcp-bundle

同样提供 9 个工具和上下文通知，不增加额外负担。

Bundle 仓库 →

---

库 API

@experimental（v1.13.0+）——在 v2.0.0 发布之前，程序化接口可能会在任何次要版本或补丁版本中发生变化。集成时请固定到确切版本。

claudestat 除 CLI 外还提供 TypeScript 库入口。你可以构建导出器、告警器和集成，直接读取会话数据——无需 spawn，也无需解析输出。

import { dbOps, analyzeSession, computeProjection, configure } from '@statforge/claudestat'

// Opt out of the daemon-required guard (CI / batch jobs):
configure({ throwOnNoDaemon: false })

const sessions = dbOps.getAllSessions(20)
const report   = analyzeSession(events, costUsd)
const forecast = computeProjection(30)

默认情况下，首次调用 dbOps.* 时会探测 http://127.0.0.1:7337/health；如果守护进程未运行，则会抛出 DaemonNotRunningError。纯函数（findPricing、analyzeSession、computeProjection……）不会进行探测。

内容	稳定性
dbOps（50 多个只读查询函数）	@experimental — 延迟执行并由守护进程检查保护
定价表（MODEL_PRICING、KNOWN_CONTEXT_WINDOWS、PRICING）	@experimental
智能分析（analyzeSession、detectLoops、predictSaturation……）	@experimental
预测与配额（computeProjection、computeQuota……）	@experimental
configure({throwOnNoDaemon})	@experimental

完整库参考与 3 个完整示例 →

---

配置

配置存储在 ~/.claudestat/config.json。使用 claudestat config 查看，或直接编辑该文件。

claudestat config --kill-switch true --threshold 90
claudestat config --plan max5
claudestat config --alerts false

完整配置参考 →

---

工作原理

Claude Code / OpenCode event
      │
      ▼
  Hook script  (~/.claudestat/hooks/event.js)
       │  POST JSON → daemon
       ▼
  Daemon  (localhost:7337)
       │  stores events in SQLite
       │  enriches with JSONL token data
       │  runs pattern analyzer
       │  context/quota push notifications
       ▼
  ┌──────────────────────────────────┐
  │  Dashboard (React + Vite)        │
  │  Terminal (claudestat watch)     │
  │  MCP Server (9 tools)            │
  │  Library API (dbOps, pricing)    │
  └──────────────────────────────────┘
              │
              ▼
  You see everything — live

---

故障排除

claudestat start 卡住约 5 秒 这是正常现象——首次加载时，require('express') 需要几秒钟。守护进程正在运行；请等待“Daemon started”确认信息。

钩子未触发／仪表盘没有显示任何事件 运行 claudestat doctor——它会检查每个组件，并打印确切的修复命令。

安装后找不到 claudestat 命令 如果使用 NVM，二进制文件可能指向错误的 Node 版本：

nvm use default && npm install -g @statforge/claudestat && hash -r claudestat

终止开关阻止了新会话 使用 claudestat config --kill-switch false 禁用，或等待 5 小时配额窗口重置。

接近速率限制 守护进程每 60 秒轮询一次配额，并在达到 70%、85% 和 95% 时记录警告。随时使用 claudestat status 查看。

处理多个项目 claudestat 会自动跟踪每个项目。“Projects”选项卡会按工作目录对会话分组。

仪表盘对所有会话均显示 0 成本／$0.00 令牌数据来自 Claude Code 的 JSONL 文件，而非钩子事件。请确保 Claude Code 正在写入 JSONL 日志——检查 ~/.claude/projects/ 中是否有 .jsonl 文件。如果该目录为空，Claude Code 可能未启用日志记录。

终端关闭后守护进程停止 必须使用 nohup 启动守护进程，才能让它在 shell 会话结束后继续运行：

nohup claudestat start &

也可以使用 claudestat setup 安装系统服务（macOS 上为 launchd，Linux 上为 systemd，Windows 上为计划任务）。

claudestat export 生成空输出 如果没有显示会话，守护进程可能在你的 Claude Code 会话期间没有运行。请检查 claudestat status，并使用 claudestat start 重启。即使没有运行中的守护进程，也可以仅导出历史数据：导出仍会读取本地 SQLite 数据库，因此守护进程运行期间捕获的过往会话始终可用。

循环检测器触发过于频繁／不够频繁 调整阈值和时间窗口：

claudestat config --loop-threshold 5   # default: 8 calls
claudestat config --loop-window 90     # default: 120 seconds

MCP 服务无响应 重启守护进程（claudestat restart），并确认它已注册：

claude mcp list

如果未列出，请重新运行：claude mcp add claudestat -s user -- claudestat-mcp

未显示 OpenCode 会话 claudestat 从 ~/.local/share/opencode/opencode.db 读取 OpenCode 数据。如果该文件不存在，说明 OpenCode 尚未运行，或在你的系统上使用了不同的数据路径。至少运行一次 opencode 以初始化数据。

启动时出现 Node.js 实验性 SQLite 警告 这是预期行为——node:sqlite 在 Node 22 中处于实验阶段。该警告会自动隐藏。如果反复看到，请确认你运行的是 Node.js 22 或更高版本（node --version）。

常见问题

什么是 claudestat？它与 ccusage 有什么不同？ claudestat 是 Claude Code 的实时监控工具，不是日志读取器。它会在每次工具调用触发时进行挂钩，实时跟踪令牌用量和费用，通过可配置的提醒保护你的配额，并提供 MCP 服务。ccusage 会在会话结束后读取 JSONL 历史记录；claudestat 则在你编写代码时持续运行。

如何跟踪 Claude Code 的费用？ 使用 npm install -g @statforge/claudestat && claudestat setup 安装，然后打开 http://localhost:7337 查看实时仪表板。使用 claudestat status 快速查看摘要，或使用 claudestat export 导出完整数据。

claudestat 支持 Claude Pro、Max 5 和 Max 20 吗？ 支持。claudestat 会自动检测你的套餐。你也可以使用 claudestat config --plan max5 手动指定。

我的数据会发送到任何服务吗？ 不会。所有数据都存储在本地的 SQLite 中，路径为 ~/.claudestat/。完全不依赖云服务。

claudestat 支持 Windows 吗？ 支持，macOS、Linux 和 Windows 均可使用。在 Windows 上，claudestat setup 会注册计划任务以实现自动启动，剪贴板操作使用 clip，守护进程运行状况检查使用 Node 内置的 HTTP 客户端。

什么是 MCP bundle？ @statforge/claudestat-mcp-bundle 是一个独立的 npm 包，仅包含 MCP 服务，不含 CLI、仪表板或守护进程。如果你想让 Claude 通过 MCP 查询自身统计数据，而不运行完整的 claudestat 守护进程，可以安装它。

我可以通过编程方式使用 claudestat 吗？ 可以。你可以直接从 @statforge/claudestat 导入 dbOps、computeProjection、analyzeSession、createMcpServer 等函数。请参阅库 API一节。

---

卸载

claudestat setup --uninstall                          # remove hooks + system service
rm -rf ~/.claudestat                                  # macOS / Linux
Remove-Item -Recurse -Force "$env:USERPROFILE\.claudestat"  # Windows (PowerShell)

如果你是手动安装的，请使用 claudestat uninstall 仅移除挂钩。 在 Windows 上，claudestat setup --uninstall 还会移除计划任务。

---

贡献

欢迎提交 PR！完整指南请参阅 CONTRIBUTING.md。

git clone https://github.com/DeibyGS/claudestat
cd claudestat
npm install
node --require tsx/cjs tests/index.ts   # run all tests

适合入门的领域：模式分析器（src/pattern-analyzer.ts）、仪表板组件（dashboard/src/components/）、新命令。

---

许可证

MIT — 使用它、分叉它、发布它。