An unofficial local dashboard for viewing Claude Code and Codex usage limits on a spare phone, tablet, or small screen.

The server runs on your own Windows or macOS machine, reads local usage data, and serves a simple dashboard that can be opened from another device on the same Wi-Fi network.

• Shows Claude Code and Codex usage for the 5-hour and weekly windows.
• Can display either used percentage or remaining percentage.
• Reads Claude Code usage through a local statusLine cache.
• Reads Codex usage from the newest local ~/.codex/sessions rate_limits snapshot.
• Works on a phone or tablet connected to the same Wi-Fi network.
• Tap the dashboard to refresh and request fullscreen mode.
• Turns red when usage reaches the alert threshold.
• Uses only Node.js built-in modules. No npm dependencies.
• Includes helper scripts for Windows and macOS.
• Includes a server-rendered KOBO / e-ink page for older browsers.

Usage numbers only update after you actually use Claude Code or Codex.

Claude Code usage comes from statusLine, so opening Claude in the web app or desktop app will not update this dashboard. Codex usage is read from local Codex session files, so it updates only after Codex writes new session data.

This project is not affiliated with Anthropic or OpenAI. It does not include official logos. Make sure your own use of third-party names, trademarks, and local tool output formats follows the relevant terms.

This is a personal side project. Support is best-effort.

• Windows 10/11 or macOS
• Node.js 18 or newer
• Claude Code, with statusLine configured for real Claude usage
• Codex, with local ~/.codex/sessions data

Check Node.js:

node -v

Clone the repository:

git clone https://github.com/frankchiu-dev/claude-codex-usage-dashboard.git
cd claude-codex-usage-dashboard

Start the dashboard:

node server.js

You should see output similar to:

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

Open http://localhost:8787 on the computer running the server. To use a phone or tablet, connect it to the same Wi-Fi network and open the Device URL.

Many KOBO browsers are old and do not reliably support modern JavaScript features such as fetch, async/await, wake lock, or modern CSS. If the normal dashboard loads but the numbers never appear, use the KOBO page instead:

Shortest URL for remaining percentage:

http://YOUR-LAN-IP:8787/k

Shortest URL for used percentage:

http://YOUR-LAN-IP:8787/u

These short URLs are useful on e-ink devices where typing is slow and copy/paste may not work.

Long remaining URL:

http://YOUR-LAN-IP:8787/kobo

/eink, /e, /r, /kr, and /ku are also available as aliases. In short: /k = remaining, /u = used.

The KOBO page is rendered on the server, so the numbers are already inside the HTML. It does not require JavaScript. It refreshes with a simple <meta refresh> tag.

Display remaining percentage:

http://YOUR-LAN-IP:8787/kobo?mode=remaining

Display used percentage:

http://YOUR-LAN-IP:8787/kobo?mode=used

KOBO browsers also may not rotate web pages reliably. The /kobo page is designed for portrait reading mode instead of relying on landscape rotation.

.\start-dashboard.bat

chmod +x ./start-dashboard.sh ./start-dashboard.command
./start-dashboard.sh

You can also double-click start-dashboard.command in Finder after making it executable.

This step lets the dashboard show real Claude Code usage.

.\setup-claude-statusline.bat

chmod +x ./setup-claude-statusline.sh
./setup-claude-statusline.sh

Then:

1. Fully quit Claude Code.
2. Open Claude Code again.
3. Send one message.
4. Refresh the dashboard.

The Claude card will start reading ~/.claude/usage-cache.json.

Claude Code supports one statusLine.command at a time. If you already use another statusLine script, such as a Stream Deck integration or a custom prompt status line, use fanout mode.

Copy the example config:

Copy-Item .\config.example.json .\config.json

cp ./config.example.json ./config.json

Edit config.json.

Windows example:

{
  "extraStatuslineCommand": "powershell -NoProfile -ExecutionPolicy Bypass -File \"%USERPROFILE%\\.claude\\your-existing-statusline.ps1\""
}

macOS example:

{
  "extraStatuslineCommand": "/Users/YOUR_NAME/.claude/your-existing-statusline.sh"
}

Then enable fanout mode.

.\setup-claude-statusline.bat --fanout

./setup-claude-statusline.sh --fanout

This sends the same Claude Code statusLine JSON to both this dashboard and your existing command.

Install autostart:

.\install-autostart.bat

Remove autostart:

.\uninstall-autostart.bat

Install a LaunchAgent:

chmod +x ./install-autostart-macos.sh ./uninstall-autostart-macos.sh
./install-autostart-macos.sh

Remove the LaunchAgent:

./uninstall-autostart-macos.sh

The macOS LaunchAgent writes logs to:

~/Library/Logs/claude-codex-usage-dashboard.log
~/Library/Logs/claude-codex-usage-dashboard.err.log

Windows example:

$env:PORT="8790"
$env:HOST="127.0.0.1"
$env:DISPLAY_MODE="remaining"
$env:KOBO_REFRESH_SECONDS="120"
node server.js

macOS example:

PORT=8790 HOST=127.0.0.1 DISPLAY_MODE=remaining KOBO_REFRESH_SECONDS=120 node server.js

DISPLAY_MODE=used shows how much of the limit has been used. DISPLAY_MODE=remaining shows how much is left. The red alert color is still based on used percentage reaching ALERT_PERCENT.

If another device cannot connect, make sure it is on the same Wi-Fi network as the computer running the dashboard.

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

macOS may ask whether Node.js can accept incoming network connections. Allow it if you want to open the dashboard from a phone or tablet.

Data stays on your machine. The server reads local Claude and Codex usage records, but does not upload them anywhere.

Do not commit:

• ~/.claude/usage-cache.json
• ~/.codex/sessions
• ~/.claude/settings.json
• config.json

See GITHUB_UPLOAD_GUIDE.md for a first-time step-by-step guide.

MIT