claude-codex-usage-dashboard

用途

claude-codex-usage-dashboard 是一个本地 Node.js 服务器，用于在连接到同一 Wi-Fi 网络的备用手机、平板或电子墨水屏设备上显示 Claude Code 和 Codex 的 API 用量限制。它从本地缓存文件读取用量数据，并提供实时仪表盘，在达到限制时给出可视化告警。注意：它不轮询外部 API，仅读取本地文件。

主要能力

显示 Claude Code 和 Codex 的 5 小时和每周用量窗口
显示已用或剩余百分比
Claude Code 用量通过 statusLine 从 ~/.claude/usage-cache.json 读取
Codex 用量从 ~/.codex/sessions 快照读取
可在同一 Wi-Fi 网络的任意设备上使用
包含为旧电子墨水屏浏览器准备的服务器端渲染 /kobo 页面
零 npm 依赖（仅使用 Node.js 内置模块）
用量达到阈值时红色告警

使用方式

快速开始

# 克隆仓库
git clone https://github.com/frankchiu-dev/claude-codex-usage-dashboard.git
cd claude-codex-usage-dashboard

# 启动服务器（需要 Node.js 18+）
node server.js

输出显示两个 URL：

Local:  http://localhost:8787
Device: http://192.168.1.23:8787

在同一 Wi-Fi 网络的任意设备上打开 Device URL。

平台专用设置

Windows：

.\start-dashboard.bat
.\setup-claude-statusline.bat
.\install-autostart.bat
.\uninstall-autostart.bat

macOS：

chmod +x ./start-dashboard.sh ./setup-claude-statusline.sh
./start-dashboard.sh
./setup-claude-statusline.sh
chmod +x ./install-autostart-macos.sh
./install-autostart-macos.sh
./uninstall-autostart-macos.sh

Claude Code statusLine 配置

首次设置：运行对应平台的 setup 脚本，然后完全退出 Claude Code、重新打开、发送一条消息以更新缓存、刷新仪表盘。仪表盘将从 ~/.claude/usage-cache.json 读取。

Fanout 模式（多个 statusLine 命令）：若已有自定义 statusLine 命令，可复制 ./config.example.json 为 ./config.json，编辑其中的 extraStatuslineCommand 字段，然后用 --fanout 参数运行 setup 脚本。

配置

环境变量：

PORT=8790 node server.js                 # 端口，默认 8787
HOST=127.0.0.1 node server.js            # 绑定地址，默认 0.0.0.0
ALERT_PERCENT=90 node server.js          # 告警阈值百分比，默认 85
DISPLAY_MODE=remaining node server.js    # 显示模式，used 或 remaining，默认 used
KOBO_REFRESH_SECONDS=120 node server.js  # KOBO 页面刷新间隔秒，默认 60，最小 15
CODEX_LOOKBACK_DAYS=7 node server.js     # Codex 会话回溯天数，默认 14
CLAUDE_USAGE_CACHE=~/.claude/usage-cache.json node server.js
CODEX_SESSIONS_DIR=~/.codex/sessions node server.js
EXTRA_STATUSLINE_COMMAND="/path/to/other-script.sh" node server.js

config.json（fanout 模式可选）：

{
  "extraStatuslineCommand": "/path/to/your-existing-statusline.sh"
}

使用模式

标准仪表盘：在电脑上访问 http://localhost:8787，手机/平板访问 http://192.168.1.23:8787。功能包括：点击任意处刷新、点击请求全屏、用量 ≥ ALERT_PERCENT 时红色告警、显示 5 小时和每周窗口。

KOBO / 电子墨水模式（用于不支持现代 JavaScript 的旧浏览器）：

http://YOUR-LAN-IP:8787/k    # 剩余百分比（默认）
http://YOUR-LAN-IP:8787/u    # 已用百分比
http://YOUR-LAN-IP:8787/kobo                  # 剩余模式
http://YOUR-LAN-IP:8787/kobo?mode=used
http://YOUR-LAN-IP:8787/kobo?mode=remaining

别名：/eink → /kobo，/e → /kobo，/r → /kobo?mode=remaining，/k → /kobo?mode=remaining，/kr → /kobo?mode=remaining，/ku → /kobo?mode=used。KOBO 页面为服务器端渲染，使用 <meta refresh> 标签，无需 JavaScript。

显示模式：used 模式显示已消耗多少限额；remaining 模式显示剩余配额，但仍在已用百分比 ≥ ALERT_PERCENT 时变红（而非剩余 ≤ 15%）。

网络设置

Windows 防火墙规则：

netsh advfirewall firewall add rule name="AIUsageDashboard" dir=in action=allow protocol=TCP localport=8787

自定义端口时替换 localport。macOS 在 Node.js 尝试接受连接时会提示许可，点击 Allow。

代码示例

自定义 Node.js 集成（读取相同用量数据）的示例代码见原文，包含 getClaudeUsage() 与 getCodexUsage() 函数，分别读取 ~/.claude/usage-cache.json 和 ~/.codex/sessions 下最新 JSON 会话文件的 rate_limits。

自定义 statusLine 处理器：可使用 PowerShell 或 Bash 脚本接收 Claude Code statusLine 的 JSON，写入自定义缓存并显示，再通过 config.json 的 extraStatuslineCommand 配置并启用 fanout 模式。

服务器 API 端点

GET /：主仪表盘页面（现代 JavaScript）
GET /kobo, /eink, /e, /k, /r：服务器端渲染的电子墨水/KOBO 页面，查询参数 mode=used 或 mode=remaining
GET /u, /ku：KOBO 页面的 used 模式
GET /api/usage：JSON 端点，供程序化访问

curl http://localhost:8787/api/usage

响应示例如原文所述，包含 claude 与 codex 的 fiveHour、weekly 用量对象（used、limit、percentage、remaining），以及 alertThreshold 和 displayMode。

故障排查

原文提供了 Claude 无数据、Codex 无数据、设备无法连接、KOBO 页面不刷新、数字仅在用后更新、端口占用、fanout 模式不工作、macOS 自启动不工作等问题的排查步骤，包括检查缓存文件、目录、增加回溯天数、添加防火墙规则、更换端口、检查 config.json 路径与脚本可执行权限等。

最佳实践

保持 Node.js 更新：需要 Node.js 18+
使用环境变量：不要硬编码端口或路径
防火墙规则：为端口添加显式允许规则
电子墨水设备：使用 /k 或 /u 短 URL 便于输入
Fanout 模式：启用前先独立测试额外的 statusLine 脚本
隐私：切勿将缓存文件或 config.json 提交到版本控制

适用场景

希望在闲置设备（手机、平板、电子墨水屏）上以仪表盘形式持续查看 Claude Code 与 Codex API 用量限制的个人用户，尤其适用于同一局域网内、需要快速了解用量是否接近上限的场景。

限制

仅读取本地缓存文件，不轮询外部 API；数据更新依赖实际使用 Claude Code 或 Codex
Claude Code 仅在发送消息时更新（非网页/桌面应用）
Codex 仅在写入新会话文件时更新
KOBO 页面部分旧浏览器可能忽略 meta refresh，需手动刷新
要求 Node.js 18+
许可证为 MIT