Skip to content

About

Show remaining AI coding-assistant quota (Claude Code, and more) on an AWTRIX 3 pixel clock

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

awtrix-ai-usage

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.

A Ulanzi pixel clock showing the Claude icon beside a green progress bar of remaining quota

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.

How it works

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.

Two things that stop it lying to you

  1. Reset awareness. Once a window's resets_at passes, 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.
  2. 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.

Known limitation

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.

Requirements

  • 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

Install

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

Then 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.log

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

Setting up the capture

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

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

Usage

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

Configuration

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.

Adding a provider

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.

Gotchas

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 list still shows the job loaded, and only the exit code (2) and the log reveal Operation 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. Keep separator ASCII; hyphens are fine.
  • The device gamma-corrects icons but not text colours. With GAMMA 1.9 an icon's #D97757 reads back from /api/screen as 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/settings returns OK and persists, but /api/loop keeps listing the app until POST /api/reboot. A reboot clears custom apps; the scheduled job restores them within 60s.
  • Timezone is not in /api/settings. It lives in DoNotTouch.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 duration shorter than a pass truncates it.
  • ~/.claude.json → cachedUsageUtilization is a trap. Right shape, but fetchedAtMs stops updating, so it looks correct and is days stale. There is also no claude usage subcommand. The status line is the only live source.

Debugging: dump what the matrix is showing

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)))
EOF

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

Licence

MIT — see LICENSE.

About

Show remaining AI coding-assistant quota (Claude Code, and more) on an AWTRIX 3 pixel clock

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages