Help

Install, connect, customize, and troubleshoot — in about five minutes.

Install

  1. Download the latest DMG.
  2. Drag Token Run into Applications and launch it.
Requirements: macOS 14.0 or later, Apple Silicon or Intel.

If macOS blocks the first launch, open System Settings → Privacy & Security and click Open Anyway.

Connect providers

Token Run reads usage through the sessions you already use with Claude Code, Codex CLI, GitHub Copilot CLI, and Google Antigravity — no API keys. Any of them can run together, and the popover aggregates them. Claude and Codex drive the quota cards; Copilot and Antigravity only feed the runner's speed.

Claude Code

Open the popover, click Connect Claude, and approve the OAuth prompt. Disconnect anytime from Settings → Claude Quota.

Codex CLI

Sign into Codex CLI — Token Run picks it up automatically. Turn it off in Settings → Providers.

GitHub Copilot CLI

Install the Copilot CLI and run it once — Token Run auto-detects ~/.copilot/session-state. As of Copilot CLI 1.0.35, only output tokens are logged (input and cache tokens aren't exposed yet), so the numbers under-count actual usage and there's no quota card. Turn it off in Settings → Providers.

Google Antigravity

Install Antigravity. Conversation files are encrypted on disk, so Token Run uses per-file size growth as an activity proxy — the displayed token numbers aren't real usage, they just drive the runner's speed. No quota card. Turn it off in Settings → Providers.

  • Runner sprite — speeds up with your tokens-per-minute.
  • Token count — today's total.
  • Quota battery — 5-hour quota remaining. Pick Claude, Codex, or off.
  • Reset timer — countdown to the next 5-hour reset.

Toggle each element in Settings → Menu bar.

Speed tiers

  • Resting — no recent activity.
  • Walking — under ~500 tok/min.
  • Running — above ~1,000 tok/min.
  • Sprinting — above ~2,000 tok/min.

Characters

Open Settings → Character and click a runner to switch. Every character adapts to dark and light menu bars.

Custom characters

Add your own runner from Settings → Character → + Add. Drop in a horizontal sprite sheet PNG or a folder of frame PNGs, reorder frames, tune the fps, and save.

Community percentile

When enabled, Token Run shows your weekly bucket (e.g. Top 28% this week) compared to other users. Only an anonymous ID and your daily token total are sent — no account info, no prompt content. Turn off anytime in Settings → Share anonymized usage stats.

Privacy

  • Credentials stay where each CLI keeps them. Token Run only uses them to read quota.
  • Prompts, completions, tool calls, and file paths never leave your device.
  • Token counts and per-provider breakdowns stay local — except the optional daily total used by the community percentile.

Troubleshooting

"Throttling requests…" in the popover

Quota was briefly rate-limited. It refreshes automatically within a minute or two.

Runner stays idle while I'm coding

  • Check that your providers show Installed or Enabled in Settings → Providers.
  • Your tokens-per-minute may be under the walking threshold — the runner reacts to throughput, not presence.
  • Still zeroed out? Disconnect and reconnect the provider.

App won't open — "damaged" or blocked

Open System Settings → Privacy & Security and click Open Anyway.

Custom character doesn't animate

  • All frames must have the same pixel size.
  • Use PNGs — JPEGs lose transparency.
  • Try a lower fps.

Feedback

Email ryanstudio0429@gmail.com.