Show how much AI coding-assistant quota you have left on an AWTRIX 3 LED matrix clock — so you can glance at your desk instead of squinting at a status line.
Percentages are remaining, each followed by time until that window resets. The bar tracks whichever window is tightest — the limit that will actually bite first — and turns amber below 50% and red below 20%. Optional alerts interrupt the loop with a buzzer when you cross a threshold.
Ships with a Claude Code provider. The provider layer is pluggable, so other tools (Codex, etc.) are a new file rather than surgery — see Adding a provider.
Tested on a Ulanzi Pixel Smart Clock running AWTRIX 3 firmware 0.98, driven from macOS.
Claude Code ──stdin──> your status line script ──> ~/.claude/usage-snapshot.json
│
launchd (60s) ──> usage_meter.py ───┘
│
POST /api/custom ──> device
Claude Code pipes a JSON blob to your configured statusLine command on every
render, and that blob carries the official, account-wide rate-limit numbers:
"rate_limits": {
"five_hour": { "used_percentage": 23.5, "resets_at": 1738425600 },
"seven_day": { "used_percentage": 41.2, "resets_at": 1738857600 }
}A small snippet in that script snapshots those fields to a file. A separate scheduled job reads the snapshot and pushes to the device.
The split is the whole design. A status line runs on every render, so it must never make a network call — a hanging socket would stall your terminal. The capture side only writes a file; the push side does the I/O.
- Reset awareness. Once a window's
resets_atpasses, the meter reports it as 100% remaining rather than echoing a stale percentage, so an overnight gap self-heals instead of showing yesterday's 93% forever. - Self-removal. The screen is pushed with
lifetime: 900, so if your machine sleeps or the job dies, it drops out of the loop within 15 minutes rather than displaying numbers that quietly stopped being true.
The numbers are account-wide and accurate, but they only refresh while a Claude Code session is rendering on the machine running this. Usage from elsewhere appears the next time you open Claude Code here.
- An AWTRIX 3 device on your network (no auth configured, or adapt
post()) - macOS for the bundled launchd job — the Python is portable, so cron/systemd works elsewhere
python3(3.9+, stdlib only — no pip installs)jq, for the status line snippet
git clone https://github.com/nicolasguzca/awtrix-ai-usage.git
cd awtrix-ai-usage
cp config.example.json config.json
# edit config.json -> set device_ip to your device's address
./install.shThen set up the capture side (below). Verify:
python3 usage_meter.py --dry-run # renders the payload, no device I/O
launchctl list | grep awtrix # 2nd column is the last exit code; want 0
tail -f /tmp/awtrix-ai-usage.loginstall.sh copies the code and config.json into ~/.awtrix-ai-usage/
and points launchd there. That indirection is not decoration — see the TCC
gotcha. After editing config.json, re-run ./install.sh.
Claude Code's status line is the only live source for these numbers, so the snapshot has to be written from there.
If you already have a status line script, paste the contents of
statusline-snippet.sh into it, after it reads stdin
into input. Back up your script first.
If you don't, create one:
cat > ~/.claude/statusline.sh <<'EOF'
#!/usr/bin/env bash
input=$(cat)
EOF
cat statusline-snippet.sh >> ~/.claude/statusline.sh
echo 'printf "%s" "$(printf "%s" "$input" | jq -r ".model.display_name")"' >> ~/.claude/statusline.sh
chmod +x ~/.claude/statusline.shand register it in ~/.claude/settings.json:
{ "statusLine": { "type": "command", "command": "bash ~/.claude/statusline.sh" } }The snapshot appears at ~/.claude/usage-snapshot.json once Claude Code has
made its first API call of a session.
python3 usage_meter.py --dry-run # print the payload, no device I/O
python3 usage_meter.py --once # push one update
python3 usage_meter.py --test-alert # notification + buzzer
python3 usage_meter.py --delete # remove the screen from the loop
python3 usage_meter.py --list-providers # what's installed
./uninstall.sh # remove job, runtime, and screen| Key | Meaning |
|---|---|
device_ip |
Your AWTRIX address |
app_name |
Name of the screen in the device loop |
providers |
List of {"module": ..., ...}; extra keys go to that provider |
separator |
Between windows. Keep it ASCII — see gotchas |
duration |
Seconds the screen holds. Independent of the device's global ATIME |
lifetime |
Seconds before the screen self-deletes if not refreshed |
thresholds |
green_above / amber_above, in percent remaining |
alert.thresholds |
Alert points, in percent used |
alert.prefix |
Prepended to alert text, e.g. CLAUDE |
alert.sound_rtttl |
Buzzer melody (RTTTL). Omit for silent alerts |
icon |
Base64 8x8 JPEG, inline — nothing to upload to the device |
Alerts fire once per threshold per window, keyed on resets_at in state.json,
and re-arm automatically when a window rolls over.
Drop a module in providers/ exposing NAME, DESCRIPTION, and
fetch(options) returning:
{
"captured_at": 1786600200,
"windows": [
{"label": "5H", "remaining": 83.0, "resets_at": 1786600200},
],
}Return None when you have nothing to report; never raise. The core clamps
values, applies reset rollover, formats countdowns, picks colours and handles
alerting — a provider only has to answer how much is left, and until when.
Labels are yours and are what distinguish your windows from another tool's on a shared screen, so keep them short and unambiguous.
Then add it to providers in config.json. Any extra keys in that entry are
passed to your fetch as options.
Things that cost real debugging time here:
- A LaunchAgent cannot read
~/Documents. It's TCC-protected and launchd doesn't inherit your terminal's grant. It fails silently —launchctl liststill shows the job loaded, and only the exit code (2) and the log revealOperation not permitted. Hence the deploy step to~/.awtrix-ai-usage. - The AWTRIX font has no
·(U+00B7). It renders as a solid 3x3 blob that reads as a missing-glyph box. KeepseparatorASCII; hyphens are fine. - The device gamma-corrects icons but not text colours. With
GAMMA1.9 an icon's#D97757reads back from/api/screenas roughly(182,58,20). The embedded JPEG is pixel-accurate — don't compensate by pre-brightening, or the physical LEDs come out too bright. - Native app toggles (
TIM/DAT/TEMP/HUM/BAT) require a reboot.POST /api/settingsreturnsOKand persists, but/api/loopkeeps listing the app untilPOST /api/reboot. A reboot clears custom apps; the scheduled job restores them within 60s. - Timezone is not in
/api/settings. It lives inDoNotTouch.json, which also holds static-IP settings and the HTTP auth password — don't write it programmatically. Use the web UI, Settings → Time. If your clock is hours off but the minutes tick correctly, this is why; the factory default is CEST. - Long text scrolls, and one pass takes ~5s. A
durationshorter than a pass truncates it. ~/.claude.json→cachedUsageUtilizationis a trap. Right shape, butfetchedAtMsstops updating, so it looks correct and is days stale. There is also noclaude usagesubcommand. The status line is the only live source.
The single most useful tool here — read the device's framebuffer back as ASCII:
IP=192.168.1.42
curl -s -X POST -H "Content-Type: application/json" \
-d '{"name":"aiusage"}' http://$IP/api/switch
python3 - <<EOF
import json, urllib.request
px = json.load(urllib.request.urlopen("http://$IP/api/screen"))
for y in range(8):
print("".join("#" if px[y*32+x] else "." for x in range(32)))
EOFSample it twice with a delay to tell "frozen" from "scrolling". This is how the missing glyph, the gamma shift and the scroll timing were all diagnosed.
MIT — see LICENSE.
