luwill

Token Watcher — AI skill for Claude Code

AI community

⏱ Token Watcher — local real-time token usage & quota dashboard for AI coding agents (Claude Code, ccmr, Codex, ZCode, dsh, WorkBuddy, Grok Build).

How to install Token Watcher

This entry records only its repository, not the path inside it, so there is no exact command to give. Open luwill/token-watcher and copy the folder into ~/.claude/skills/, or the file into ~/.claude/agents/.

What Token Watcher does

⏱ Token Watcher — local real-time token usage & quota dashboard for AI coding agents (Claude Code, ccmr, Codex, ZCode, dsh, WorkBuddy, Grok Build). 7 sources, zero-dep backend, live SSE panel, macOS menu bar. npx token-watcher serve

Alternatives in AI

EchoBird — One-click install + model switch:Claude Code,Codex CLI (OpenAI), Grok Build (xAI), DeepSeek Harness, Kimi Code 3.1k ★
Fact Checker — Verify claims and facts with sources 653 ★
Karpathy LLM Wiki — Agent Skills-compatible LLM wiki for Claude Code, Cursor, and Codex 618 ★

README

Token Watcher

**Mac 本地多源 AI Agent 用量与配额实时面板。** 一个常驻进程解析你机器上各 AI 编码工具留下的本地会话记录，统一归一化为 token 事件流，提供 Codex 风格的统计面板、实时配额卡、厂商余额轮询、费用估算与菜单栏胶囊。零框架依赖、纯本地运行。

![Token Watcher](docs/screenshot.png)

截图为真实运行数据（厂商余额已脱敏）。

支持的工具（7 源）

工具	数据位置	能看到什么
Claude Code	`~/.claude/projects`	逐请求 token 明细、模型分布
ccmr（claude-code-model-router）	`~/.claude-gateway/projects`	同上（国产模型隔离目录，真实模型名）
Codex	`~/.codex/sessions`、`archived_sessions`	token 明细、官方周配额百分比与重置时间、模型（含 auto-review 子代理）、工具调用
ZCode	`~/.zcode/cli/db/db.sqlite`	逐请求明细（model_usage 表）、工具调用
dsh（DeepSeek Harness）	`~/.dsh/sessions`	逐请求明细（zstd 压缩会话）
WorkBuddy	`~/.WorkBuddy/projects`	逐请求明细 + 积分费率自学习（credit 账本 × token 最小二乘）
Grok Build	`~/.grok/sessions`	轮次用量明细（含厂商侧成本刻度）、工具调用

不支持的：网页版聊天（ChatGPT/豆包/DeepSeek 网页等）——token 计数在服务端，本地无留痕，原理上不可统计。

快速开始

# 方式一：npx 直接运行（推荐，无需克隆仓库）
npx token-watcher serve
open http://127.0.0.1:8787

# 方式二：克隆仓库开发（首扫历史 ~3.3GB 约 6 秒，仅首次）
git clone https://github.com/luwill/token-watcher.git
cd token-watcher && npm install
npm run serve

要求：**Node ≥ 22.5**（内置 `node:sqlite`，零原生依赖）；dsh 源需要系统 `zstd`（`brew install zstd`，缺失自动跳过该源）。

平台支持：**macOS 全功能验证**（含菜单栏 App 与 launchd）；Linux 理论可用（Node 20+ 支持 recursive watch），未完整测试；Windows 未测试。菜单栏 App 为 macOS 专属。

开发与测试：`npm test` 运行三层回归——语法检查、静态断言（渲染函数存在性/DOM id 一致性）、端到端冒烟（fixtures 黄金数字 + 幂等 + API 结构），零依赖、可跑在 CI。

其他命令：

tokenmeter today       # 终端速览今日消耗
tokenmeter scan        # 只扫描一次
tokenmeter serve --port 9000
npm run install-agent  # launchd 开机自启（KeepAlive 崩溃自拉起）
npm run bar            # macOS 菜单栏胶囊（需 npm run build-bar 编译）

功能

实时：FSEvents 监听各数据目录 → 增量解析 → SSE 推送，面板秒级刷新（实测 <1s）
增量采集：字节级游标 / rowid 水位 / 快照重解析三种策略，二次扫描 0ms；dedup 键保证幂等；采集器版本号机制支持逻辑升级后自动全量回填
统计面板：指标卡、近一年 GitHub 风格日历热力图（每日/每周/累计）、按天/模型/工具图表、最近请求实时流
会话钻取：点击趋势图任意一天 → 会话列表（峰值上下文估算）→ 单会话逐请求 token 曲线
工具活动：四源工具调用频次榜
配额：Codex 官方配额直读（百分比/重置倒计时）、Claude 订阅 5h 窗口推算（session-blocks 法）