Claude / Codex Usage Dashboard

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.

!Platform !Node !License

Features

• 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.

Important Limitations

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.

Requirements

• 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

node -v

Quick Start

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.

KOBO / E-ink Mode

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 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 Scripts

Windows

.\start-dashboard.bat

macOS

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.

Configure Claude Code Usage

This step lets the dashboard show real Claude Code usage.

Windows

.\setup-claude-statusline.bat

macOS

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.

If You Already Have a statusLine

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.

Enable fanout mode before replacing your existing statusLine:

Windows

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

macOS

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

Setup saves the existing command verbatim to config.json as extraStatuslineCommand if no nonempty command is already configured. It preserves other config/settings fields, including statusLine padding, and backs up files before changing them. Re-running setup does not save the dashboard's own wrapper as the extra command. A normal (non-fanout) install also saves the previous command for a later switch to fanout.

Fanout sends the same stdin JSON to both commands. The dashboard always runs to update ~/.claude/usage-cache.json. A successful extra command with non-whitespace stdout owns the display: multiline layout, ANSI escapes, and trailing newlines are preserved. If it is missing, empty, exits unsuccessfully, or times out (15 seconds per child), the dashboard's default status line is shown. If the dashboard also fails, the display falls back to Claude. Commands run sequentially, so both timeouts can add up.

To configure a different command manually, edit config.json (do not overwrite an existing file with the example):

{
  "extraStatuslineCommand": "node \"/absolute/path/to/your-existing-statusline.js\""
}

Use the exact original Claude-HUD or other statusLine command, including its arguments and shell quoting. EXTRA_STATUSLINE_COMMAND takes precedence over the config value. Only configure trusted commands; they run through your shell.

If an older installation already replaced your HUD command, setup cannot reconstruct it automatically. Retrieve it from a ~/.claude/settings.json.bak-* backup or run your HUD's setup again, then enable fanout. Do not point extraStatuslineCommand at either dashboard statusline script.

Regression Tests

With Node.js 18 or newer, run:

npm test

The tests use Node's built-in test runner and isolated temporary homes/configs. They exercise real child processes and verify usage-cache updates, verbatim multiline/ANSI output, fallback behavior, environment precedence, and setup preservation/backups. The timeout case takes about 15 seconds. These automated tests do not replace an end-to-end check in Claude Code with Claude-HUD on macOS or Windows.

Start Automatically on Login

Windows

Install autostart:

.\install-autostart.bat

Remove autostart:

.\uninstall-autostart.bat

macOS

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

Environment Variables

| Variable | Default | Description | | --- | --- | --- | | PORT | 8787 | Dashboard port | | HOST | 0.0.0.0 | Allows devices on the same Wi-Fi to connect. Use 127.0.0.1 for local-only preview | | ALERT_PERCENT | 85 | Usage percentage that turns the dashboard red | | DISPLAY_MODE | used | Display used percentage or remaining percentage | | KOBO_REFRESH_SECONDS | 60 | Refresh interval for /kobo; minimum rendered value is 15 seconds | | CODEX_LOOKBACK_DAYS | 14 | How many days of Codex sessions to scan | | CLAUDE_USAGE_CACHE | ~/.claude/usage-cache.json | Claude usage cache path | | CODEX_SESSIONS_DIR | ~/.codex/sessions | Codex sessions path | | EXTRA_STATUSLINE_COMMAND | empty | Extra command for fanout mode |

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.

Network Access

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

Windows Firewall

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

macOS Firewall

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.

Privacy

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

Uploading to GitHub

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

License

MIT