Common questions.
Common fixes.

Yes — for the CLI side. Not for the device. Each CLI (Claude Code, Codex, Gemini) authenticates against its own provider as it normally does. The wall monitor itself never talks to any of them.

The device only talks to the broker on your laptop for usage (plus a public clock and weather service); the broker reads from the CLIs' local on-disk logs. If you don't already have a CLI installed for a given provider, that provider's card will simply not show on the device.

Real, with one caveat. The usage percentages are your provider's own reported quota, fetched live from its usage API — not a local estimate. The token counts are totalled from the CLI logs on the machine running the broker, so they reflect what that machine actually used.

The dollar figure is an estimate: token counts multiplied by a public model-price list. It's a useful sense of scale, not a bill — on a Pro/Max subscription it's a notional list-price value, not money charged to you.

No new API key, and no extra spend. The broker reuses the login your CLI already has. Token totals come from logs already on disk; the limit percentages come from each provider's usage endpoint — a read, not a billable completion. Running the wall monitor doesn't consume tokens or add charges.

The LAN link keeps working with no internet: the device polls the broker over your local network, and your local token totals keep updating.

Internet is needed for three things: the live provider percentages (the broker reads them from each provider's usage API), SNTP (clock), and Open-Meteo (weather + sunrise/sunset for your city). Without it, those three simply hold their last values — the rest of the dashboard carries on.

The screen itself refreshes constantly (the device polls the broker every couple of seconds), but the underlying figures update on their own cadences: token totals from your local logs are near-instant, the provider quota percentages refresh about every 90 seconds, and the spend estimate recomputes about every 5 minutes. It's an ambient gauge, not a millisecond ticker.

Claude Code, Codex CLI and Gemini CLI. Enable one or all three from Settings; a provider whose CLI isn't installed simply doesn't appear. The pairing plugin installs into whichever of the three you use.

The "magic" pairing skill is most polished in Claude Code, but the broker is a standard local server — you can configure a device against it manually (broker URL + key) from any of the supported CLIs, or by hand.

A machine that runs your AI CLI with the tokenmonitor-mcp broker running on it; the device and that machine on the same 2.4 GHz Wi-Fi / reachable LAN (port 8765 between them); and internet for the live percentages, weather and clock. If the broker's machine sleeps, the dashboard freezes; if only the internet drops, your local token totals keep updating while the live percentages and weather hold their last values.

Yes. The battery is optional and only there to ride out a brief power cut. Without it the device behaves identically when powered — it just power-cycles if the wall power drops. If no battery gauge is present the screen shows -- rather than a faked reading.

Each device has its own key, generated at pairing (you can also set a passphrase, which is hashed into the key and itself never stored or sent). It lives in two places:

• The device: in ESP32 NVS, encrypted at rest on production units.
• Your laptop: in a 0600 file under ~/.config/tokenmonitor/devices/ — protected by filesystem permissions, readable only by your user.

This device key is exchanged exactly once, during pairing, over your LAN — authorised by the 6-digit code shown on the device (with a lockout after repeated wrong attempts). After that it never leaves either side again: it's only used locally to sign each request and decrypt config pushes.

Your provider logins are a separate thing entirely. The Anthropic, Codex and Gemini credentials the broker uses to read your usage never reach the device — they stay on your computer, in your own CLI's config, and are only ever sent to each provider directly over HTTPS, exactly as your CLI already does.

Each request the device sends carries X-Tmon-Timestamp, X-Tmon-Nonce and X-Tmon-Signature — an HMAC-SHA256 over the method, path, timestamp and one-time nonce, signed with the device key. The broker rejects a stale timestamp (> 60 s skew) or a reused nonce, so a captured request can't be replayed.

Sensitive control-plane payloads — key rotation and settings pushed to the device — are AES-256-CTR encrypted with the device key. The signature covers the request headers rather than every body, so we don't claim the whole link is confidential; the part that carries secrets is the part that's encrypted, and nothing is exposed beyond your LAN.

The broker parses the token-count fields out of your CLI transcripts to total your usage. It isn't built to read or transmit the prompt and code inside those logs, and it has no endpoint that would send them anywhere. Because it's open source (Apache-2.0) and runs on your own machine, you can verify that for yourself.

Put plainly: the broker runs with your user permissions and can read what you can read — which is exactly why it's open and auditable rather than a black box.

No telemetry, analytics or crash reporting — none. The broker's outbound calls are all functional: each provider's usage API (using the login your CLI already has, to read your real quota), a public model-price list, and GitHub to check for firmware updates. Your prompts and code are never part of any of those.

The device itself only ever contacts your broker on the LAN plus a public clock server and Open-Meteo (weather + sunrise/sunset for your city). It never talks to an AI provider and never carries usage data off your network.

Everything the broker keeps lives under ~/.config/tokenmonitor/: its config (tokenmonitor.toml), one 0600 file per paired device, and a day-cached copy of the public price list. Delete that directory to wipe all device keys and registry state; factory-reset the device (hold the BOOT button ~10 s, confirm on screen) to clear its side. There's no server-side account to close.

Yes. Each device has its own device_id (the last 4 bytes of its MAC — 8 hex characters) and announces itself on mDNS as tmon-<device_id>.local. The configure skill picks them up individually.

The broker can serve any number of devices on the same LAN. Each gets its own key; per-device keys are independent.

One broker reads one machine's usage — the machine it runs on. To track a second laptop, run a broker there too; a device points at one broker at a time, and you can re-point it (broker URL is editable in Settings or via the configure skill). There's no built-in aggregation of two machines into a single combined number.

No — the ESP32-S3 radio is 2.4 GHz only. If your router has band-steering enabled, make sure the 2.4 GHz SSID is visible and your home network isn't 5-only.

Yes, as long as the device and your laptop can reach each other on layer 3. mDNS discovery requires layer-2 reachability (same VLAN or mDNS-reflector configured on your router). If mDNS is blocked, you can still configure the device manually with its IP.

The firmware is proprietary, and updates are distributed only as Ed25519-signed images the device verifies before installing. The broker (tokenmonitor-mcp), the MCP plugin and the documentation are public and Apache-2.0. You can absolutely build your own client against the broker's HTTP API — that's the integration point we support.

OTA, over your LAN, via the broker. When a new release is available, /tokenmonitor:firmware stages it; the device downloads it, verifies an Ed25519-signed manifest on-device, switches the boot slot and reboots. If the new image doesn't come up healthy and check in, the bootloader rolls back automatically, and a version floor blocks downgrades.

Both live on the two side buttons, no tools needed:

• Restart — hold PWR for ~2 s. It just reboots; nothing is erased. This is the first thing to try if it ever acts up. (A short PWR press toggles standby instead.)
• Factory reset — hold BOOT for ~10 s. A confirmation screen appears; tap Erase to wipe Wi-Fi, city, display settings and the broker passphrase and reboot into first-boot setup, or Cancel to back out. The device's identity and update anti-rollback floor are preserved, so it re-pairs cleanly.

After a factory reset, also delete the device's 0600 key file under ~/.config/tokenmonitor/devices/ on the laptop (or just re-run /tokenmonitor:configure) so the broker re-pairs with the fresh passphrase.

The device keeps working — it talks to the broker on your LAN, and the broker and plugin are open source (Apache-2.0). You can keep running, auditing and even forking the server indefinitely, with no account or cloud dependency on us.

The limits, plainly: new firmware releases, signed OTA images, hardware repairs and replacement units depend on us continuing. The software side is yours to keep; the hardware roadmap isn't guaranteed.