Claudescope

Claudescope (Claude usage)

Your Valar Scope can also run as a live gauge for your Claude usage limits — the same current‑session and weekly caps you see in Claude Code's status bar and at claude.ai/settings/usage, but glanceable on your desk so you can pace a long coding day without opening a menu. The round screen becomes a ring gauge for your rolling session limit and a set of bars for your weekly caps, each with a live countdown to when it resets — and it pings your phone when a limit runs low.

It's a separate firmware build for the same Valar Scopes hardware: flash the Claudescope firmware and the device boots into the usage gauge instead of the radar. Everything else you already know carries over — Wi‑Fi setup, the web config page, persistent storage, over‑the‑air updates, and ntfy alerts.

⚠️ Where the data comes from — and why it needs a helper. Anthropic doesn't publish your session/weekly usage as a supported public API; those numbers reach the Claude apps through an undocumented, login‑authenticated endpoint. So Claudescope does not talk to Anthropic directly and holds no login on the device. Instead, a tiny companion script — the "sidecar" — runs on a computer on your own network, reads the Claude login that Claude Code already stores there, fetches the usage numbers, and hands the device just the percentages. Your login/token never touches the device or leaves your network. Because it reads your own account through an unofficial endpoint, treat Claudescope as a fun read‑out rather than something to rely on — the endpoint can change or break at any time. It is not affiliated with or endorsed by Anthropic.

🧩 How it fits together

  Claude login on your PC              your LAN                 on your desk
  (~/.claude, kept fresh      ┌───────────────────────┐      ┌───────────────┐
   by Claude Code)  ────────► │  claudescope‑sidecar  │ ───► │  Claudescope  │
                              │  reads usage, serves  │ JSON │  (ESP32‑S3)   │
                              │  /usage.json on :8080 │      │  draws gauges │
                              └───────────────────────┘      └───────────────┘
        token stays here ▲ (never sent to the device)

The sidecar is the only thing that ever touches your Claude credential. The device just polls a plain JSON page on your network and draws it.

🛠️ Setup

You'll do this once: (1) start the sidecar on a machine that has Claude Code signed in, (2) flash the Claudescope firmware, (3) point the device at the sidecar.

1. Run the sidecar

Requirements: Python 3.8+ (standard library only — nothing to pip install) and Claude Code installed and signed in on this machine, so a token exists and stays refreshed. The machine needs to stay on and reachable from the same network as the device.

The script lives in the firmware repo at tools/claudescope-sidecar/. Run it:

python3 sidecar.py

You should see it start up and print where it's serving:

[claudescope] sidecar starting
[claudescope]   token source : /home/you/.claude/.credentials.json
[claudescope]   poll every   : 60s
[claudescope]   serving      : http://0.0.0.0:8080/usage.json
[claudescope]   set the device's 'Sidecar URL' to http://<this-host>:8080

Confirm it works in a browser or with curl — you should get JSON with "valid": true:

curl http://localhost:8080/usage.json

{ "plan": "Max (20x)",
  "session":  { "pct": 34, "resets_at": 1751824000 },
  "week_all": { "pct": 16, "resets_at": 1752000000 },
  "week_models": [ { "label": "Fable", "pct": 2, "resets_at": 1752000000 } ],
  "extra_usage": false, "valid": true }

Keep it running with your OS's service manager so it survives reboots — systemd on Linux, a LaunchAgent on macOS, or Task Scheduler / nssm on Windows. Run it as the user who has Claude Code signed in.

Options & troubleshooting

The sidecar is configured entirely through environment variables (all optional):

Variable	Default	Meaning
CLAUDESCOPE_PORT	8080	Port to serve on
CLAUDESCOPE_BIND	0.0.0.0	Bind address (all interfaces)
CLAUDESCOPE_POLL_SECONDS	60	Seconds between upstream polls (keep ≥ 30 — the endpoint rate‑limits hard)
CLAUDESCOPE_PLAN	(empty)	Force the plan label shown on‑device (e.g. Max (20x))
CLAUDE_CREDENTIALS_PATH	~/.claude/.credentials.json	Where to read the Claude token
CLAUDE_CODE_OAUTH_TOKEN	—	Use this token directly instead of the credentials file (generate one with claude setup-token)

How the token stays fresh: Claude Code stores its login at ~/.claude/.credentials.json and refreshes it about hourly. The sidecar re‑reads that file every poll, so it rides Claude Code's refresh and never runs a login flow of its own — just keep Claude Code signed in on that machine. (macOS: if your build keeps credentials in the Keychain instead of the file, export them once with security find-generic-password -s "Claude Code-credentials" -w > ~/.claude/.credentials.json, or use CLAUDE_CODE_OAUTH_TOKEN.)

Symptom (the sidecar's error field / log)	Fix
no Claude token found	Run Claude Code once so it writes ~/.claude/.credentials.json, or set CLAUDE_CODE_OAUTH_TOKEN.
401 Unauthorized	Token expired — open Claude Code so it refreshes, or mint a new claude setup-token.
429 rate‑limited	Raise CLAUDESCOPE_POLL_SECONDS (60–120 s is plenty).
Device stuck on the splash	Make sure the Sidecar URL is reachable from the device's network and curl returns "valid": true.

Full details are in the sidecar's own README.

2. Flash the firmware

Claudescope is its own PlatformIO build. From the firmware repo:

pio run -e blipscope-claude-s3-146 -t upload

(Kits can be re‑flashed to any edition at any time; see the repo's Firmware section for the PlatformIO basics.) On first boot the device brings up its Wi‑Fi setup exactly like every other edition — see Network and Setup.

3. Point the device at the sidecar

Open the device's config page (Configuration Reference explains how) and set the Sidecar URL to the address the sidecar printed — e.g. http://192.168.1.50:8080. Use the machine's LAN IP if .local names don't resolve on your network. A bare host/port is fine; the device appends /usage.json. Save, and within a few seconds the splash gives way to your live gauges.

🖥️ The screens

Claudescope uses the hybrid shell: the screens with data auto‑rotate on a dwell timer and you can also swipe left/right by hand. Tap a gauge to open a detail card. There's no PPI sweep.

Screen	What it shows
🟠 Session	A 270° ring gauge for your current rolling session limit — the big % used in the centre, coloured green → amber → red as it fills, with a live countdown to the reset below.
📊 Weekly	Stacked bars for your weekly caps: All models plus each per‑model cap the feed reports (e.g. Fable), each with its own colour‑by‑usage, and the shared reset day/time.
🕑 Clock	An idle clock (your UTC offset) that honours the night **[[Clock and Brightness
✨ Splash	A welcome card on cold start, with a setup hint ("set the sidecar URL in web config") until data arrives.

Tapping Session or Weekly opens a detail card with the exact percentages, reset times, plan name, and whether usage credits are switched on.

🚨 Alerts

Claudescope can push phone notifications via ntfy (see Alerts and Watchlist for how ntfy works). Set a topic and pick which triggers fire — each independently toggleable, and both edge‑seeded at boot so a limit that's already high at startup never pings you, only a fresh crossing:

• Session limit — your session usage crosses up through a % threshold you set (e.g. 80%), so you know to wrap up or slow down.
• Weekly limit — your weekly all‑models usage crosses up through its threshold.

Leave the topic blank to disable all phone alerts.

⚙️ Configuration

Everything is set from the same web page as the radar — Configuration Reference explains how to open it. The Claudescope build's page offers:

Setting	Description
Sidecar URL	Required. The address of your claudescope‑sidecar on the LAN (e.g. http://192.168.1.50:8080). Nothing is polled until this is set. A bare host gets /usage.json appended.
ntfy.sh topic + triggers	Phone‑alert topic and the two per‑trigger toggles (session / weekly), each with its own % threshold. Blank topic = all alerts off.
UTC offset	Sets the idle clock and the weekly "resets" day/time to your local zone.
Location (optional)	Latitude / longitude — used only for the day/night **[[Clock and Brightness
Brightness / Auto‑dim	The same backlight and night‑dim controls as the radar.

Changes apply live on Save, with no reboot — same as the radar.

⬆️ Getting it & updates

Claudescope is its own firmware image on its own update channel, so a device set up as Claudescope only ever pulls Claudescope firmware — the editions never cross. Over‑the‑air updates otherwise work exactly as on the radar; see Firmware Updates.

🔒 A note on trust

The sidecar holds a powerful account credential (your Claude login). Run it on a machine you trust, as the account that owns that login. It serves only the read‑only usage percentages over HTTP — never the token — and it makes only read requests upstream. On a home network that's fine; if you'd rather not expose even the percentages, bind it to a specific interface (CLAUDESCOPE_BIND) or put it behind your own auth. Treat the credentials file like a password.

Related

• Configuration Reference — opening the web config page
• Alerts and Watchlist — how ntfy phone alerts work
• Screens and Gestures — the swipe/tap model this edition shares with the radar
• Clock and Brightness — the auto‑dim this edition honours
• Network and Setup — Wi‑Fi setup
• Missileer · Orbitscope · Quakescope · Quillscope · Reelscope — its sibling editions