Turn a ~$5 AliExpress clock into a physical AI usage dashboard (Claude, Codex, multi-account). No firmware flashing.
Agent guide
TokenTV puts Claude and Codex usage limits on a ~$5 GeekMagic SmallTV Wi-Fi desk clock (240×240, SD_PRO or Ultra) by uploading pictures to its stock photo album, so the clock keeps its firmware. A computer that stays on reads usage and draws the pictures. Python 3.10+, Pillow, no other runtime deps.
Run without accounts or a clock
python3 -m venv .venv && .venv/bin/pip install -e . # Windows: .venv\Scripts\pip install -e .
.venv/bin/token-tv demo --out token-tv-demo # every face from sample data
.venv/bin/python -B -m unittest discover -s tests
Set up TokenTV for the user
When the user says "Set up TokenTV for me":
- Install:
python3 -m venv .venv && .venv/bin/pip install -e .(Windows:.venv\Scripts\pip install -e .), or, with Node only, usenpx token-tvin place of.venv/bin/token-tvbelow. - Run
.venv/bin/token-tv startin a terminal the user can answer. It finds the Claude, Codex and Grok CLIs that are already signed in, reads each account's email through the official login and asks the user to confirm, looks for the clock on the Wi-Fi (or asks for the IP shown on the clock's screen; pass--device-url <ip>if you know it), saves the config, asks whether to start with the computer (only when it first writes the config) and opens the dashboard at http://127.0.0.1:8787. --only codexlimits it to the tools the user names;--face pixelpicks another face (default arcade).- If it says nothing is signed in, tell the user to sign in to the CLI they use (e.g.
claude, then /login) and run step 2 again. A second account of the same service:.venv/bin/token-tv add codex --email <email>(it gets its own login folder and is signed in there; then restart TokenTV).
Verified on Linux with one SD_PRO clock. Mac and Windows hosts are untested; report what fails. On Windows, run it on the side where the user's claude or codex is signed in: Windows itself with Node is simplest, and WSL stops soon after its last terminal closes.
Change how things look
- Clock faces:
docs/clock-faces.md(one Python function per face, sample data,token-tv demo). - Web dashboard: themes are listed in
THEMESintoken_tv/web/app.jsand styled with[data-theme=<id>]rules intoken_tv/web/style.css. Copy an existing theme's rules to start. - More services:
docs/adding-a-provider.md.
Rules
- Never read, print or copy credential files (
.credentials.json,auth.json, Keychain items) or real config files. Tests usetoken_tv/sample.pyand temporary folders. - Do not publish, push, open issues or create releases on the user's behalf.
- A missing reading is a dash, an old one is marked OLD. Never turn unknown into
0. token-tv setup --yes --<provider>-email ...is non-interactive and never overwrites a config.token-tv doctor --livecontacts providers; ask the user before running it.
Make a clock face
Follow docs/clock-faces.md: write a render function, add it to RENDERERS and STYLES, render
with token-tv demo, and look at the 240×240 result at real size. It then appears in the dashboard's
Gallery as a Local face and can be applied to the clock without any upstream change.