TokenBar

TokenBar

Your Claude Code , Codex , Copilot , Windsurf , Cursor , Gemini , Kiro , GLM , Kimi , Amp … (or any AI) usage limits and when they reset,

on an LED display everywhere: Mac, Windows, Linux, iPhone, Android, Apple Watch and Wear OS.

English · Português

Website & API docs: https://chaconlucas.github.io/tokenbar/

---

Install

The computer collects the numbers. Phones and watches only show what it sends over Wi-Fi, so always start there.

Updates: Mac, Windows and Android show an update button inside the app. The iPhone (and its watch app) updates by running install-ios.sh again, or automatically with --auto. VS Code updates through the Marketplace.

Mac blocked it ("can't be opened", "unidentified developer", "is damaged")?

TokenBar isn't notarized by Apple yet (that needs a paid developer account), so macOS blocks the first launch when the app comes from a browser. Any of these fixes it:

1. Install with the command above. Downloaded from Terminal, the warning doesn't appear.
2. Allow it once: try to open TokenBar → System Settings → Privacy & Security → scroll down → Open Anyway → your Mac password.
3. "Is damaged"? In Terminal: xattr -dr com.apple.quarantine /Applications/TokenBar.app and open it again.

The prompt *"TokenBar wants to use confidential information stored in Claude Code-credentials"* isn't a block: it's the login reading (VS Code panel). Choose Always Allow.

Or ask your AI. Open Claude Code, Codex or any AI with a terminal and say:

Read https://github.com/ChaconLucas/tokenbar/blob/main/INSTALL.md and install TokenBar for me.

INSTALL.md is written for the AI: it asks which devices you have, runs the commands, and only asks for your hands when needed (a permission, the phone, the watch).

---

What it does

Mac

• An LED device window (bigger, smaller or full screen) and a floating Mini that stays on top of everything, full-screen apps included.
• MOSTRAR A % (show the %): BARRA (little LED bars with the % in the menu bar), NOTCH (a black pill around the camera, hover to open) or OS DOIS (both).
• Clicking the menu bar opens a summary with glass buttons (*liquid glass* on macOS 26): device, Mini, Ajustes (settings), refresh, quit.
• Widgets (small, medium, large) and Control Center controls (macOS 26): TokenBar, Claude, Codex, floating and device.
• Ajustes in four tabs: GERAL (language, what to show, colors), IAS (AIs), APARELHOS (phones and watches), SERVIDOR (local API, webhook, server). A Primeiros passos (getting started) guide connects everything step by step.

Windows and Linux — the same LED device, the floating Mini, a 12-dot ring in the system tray and the getting-started guide (app in desktop/, built with Tauri).

iPhone

• Opens in landscape, full screen, screen always on: a desk clock for your limits.
• Widgets on the Home Screen and Lock Screen (presets plus a custom one; "one at a time" switches AI on tap).
• Live Activity on the Lock Screen and in the Dynamic Island (on iPhones that have one), with buttons to switch AI and window.
• Built-in QR scanner (ESCANEAR QR) to pair with the computer, and a notice when an update is out or the free-account app is about to expire.

Apple Watch — app (TODOS / CLAUDE / CODEX, 5H / 7D, or turn the Digital Crown), watch-face complications, and a Smart Stack card (the Live Activity on watchOS 11+, plus widgets that rise when a limit is close or about to reset).

Android and Wear OS — phone in landscape with a home-screen widget, alerts and in-app updates. The Wear OS watch works with or without the phone: alone, type the 6-digit code from the computer (Mac: Ajustes → APARELHOS → WEAR OS SEM CELULAR). Complications on the watch face. Huawei without Google services: the QR scan doesn't work, paste the link instead.

AIs

• Claude Code through the terminal statusline (one click: CONECTAR in Ajustes → IAS), or through its login when you use the VS Code panel.
• Codex: automatic, from the terminal, VS Code or the Codex app.
• GitHub Copilot: opt-in (monthly premium requests, via gh auth token).
• Windsurf: automatic.
• Cursor, Gemini CLI, Kiro: opt-in, using the login each one already saved (Gemini: Workspace / Code Assist accounts only).
• GLM (Z.ai), MiniMax, Kimi Code, OpenRouter, Factory Droid, Amp: paste an API key in Settings → AIs (Mac: stored in the Keychain).
• Any other AI through a small JSON file: docs/providers.md.

Everything else

• Languages: Portuguese and English, with an AUTO / PT / EN switch (AUTO follows the system).
• Windows: 5 hours, 7 days, or both on the same screen. The background fills with usage: 23% lights 23% of the display.
• Alerts when a window passes 80% and 95% and when it resets (the iPhone mirrors them to the watch).
• Customization: a color per AI, text and timer colors, color by usage, red from 85%, round or square dots, brightness.

---

API & developers

• Local API while the app runs (Mac, Windows, Linux): http://localhost:41777/v1/usage, localhost only; real port in ~/.tokenbar/api.json.
• CLI tokenbar: bars in the terminal, tokenbar --prompt for the shell prompt or tmux, tokenbar get claude 5h for scripts. Works without the app too.
• MCP server tokenbar-mcp: Claude Code, Codex or Cursor call check_budget before a long task.
• Webhooks at 80% / 95% / reset (Slack and Discord get a sentence; anything else gets the JSON).
• ~/.tokenbar/snapshot.json to read without the app, and ~/.tokenbar/providers/*.json to add any AI.

curl -s http://localhost:41777/v1/usage

Schemas and examples (curl, JavaScript, Python, starship, tmux, zsh): docs/api.md.

---

How it works

                          Wi-Fi (Bonjour)                       WatchConnectivity / Wear OS

Computer ─────────────────────────────────────► iPhone / Android ─────────────────────► Apple Watch / Wear OS (Mac, Windows, Linux) widgets, Lock Screen, complications │ Claude Code: copy of the statusline (or login) Live Activity │ Codex: ~/.codex/sessions · Windsurf · Copilot · Cursor · Gemini · Kiro · GLM · MiniMax · Kimi · OpenRouter · Droid · Amp │ any AI: ~/.tokenbar/providers/*.json │ └──── PUT ────► server (optional) ◄── GET ──── phones and watches, away from home

1. The computer collects. Claude Code only hands its limits to the *statusline*; TokenBar installs a small script (~/.tokenbar/claude-tee.sh) that saves a copy and runs the statusline you already had, unchanged (with a backup of settings.json). Codex writes its limits into ~/.codex/sessions.
2. It advertises on the local network (_tokenbar._tcp) and only answers devices holding the pairing key.
3. Phones find it on their own on the same W