Toki Monitor

A rabbit that runs as fast as you burn tokens.
macOS menu bar monitor for Claude Code and Codex CLI token usage, powered by toki (tokki = 토끼) — zero CPU at idle, instant queries, always running in the background.

brew tap korjwl1/tap
brew install --cask toki-monitor

🇰🇷 한국어 · Install · Features · How it works · Sponsor

Install

brew tap korjwl1/tap
brew install --cask toki-monitor

This installs toki automatically. Launch the app — the daemon starts on its own.

git clone https://github.com/korjwl1/toki-monitor.git
cd toki-monitor
xcodebuild -project TokiMonitor.xcodeproj -scheme TokiMonitor -configuration Release build

Requires macOS 14+ (Sonoma), Xcode 16+, and toki CLI.

Quick start

# If you installed via Homebrew, just launch:
open /Applications/TokiMonitor.app

# Use Claude Code / Codex as usual — token usage appears instantly.
# Click the rabbit for details. Right-click for settings.

The app auto-starts the toki daemon if it's not running. On first launch, provider settings are synced from toki automatically.

Who is this for?

• See your AI spend at a glance. The rabbit runs while you burn tokens, sleeps (zZ) after a few idle minutes — no window to open, your spend rate is always visible.
• Need more than "total tokens"? Open the dashboard for customizable panels, PromQL queries, time-series charts, and pie charts by project. Drill down by model, time range, or provider.
• Using Claude and Codex together? See both side-by-side — usage bars, rate limits, costs. One click to toggle aggregated vs. per-provider.
• Worried about runaway costs? Set a $/min threshold. The icon turns red when you spend too fast, or orange when usage spikes above your 24-hour average.

Features

Menu bar

Character mode uses a sigmoid speed curve, steepest in the 500–3,000 tok/m range. Switch modes per provider. Right-click for Settings / Quit.

_{The rabbit dozes off (zZ) when you stop using AI for a while.}

Dashboard

Each panel runs its own PromQL query. Identical queries are deduplicated automatically.

• Time series, bar chart, pie chart, stat, gauge, table
• Provider filter via PromQL {provider="..."} — applied per panel
• Project-level token breakdown with smart path recovery
• Time range picker with presets and absolute dates
• Dashboard versioning and annotations
• Shows in Dock when open, hides when closed

Usage monitoring

Reads credentials directly from each CLI's local storage — no extra login required. Claude reads from the macOS Keychain (Claude Code-credentials), Codex from ~/.codex/auth.json. Color-coded bars: green → yellow → orange → red.

Not logged in? The widget shows a prompt instead of hiding — Claude shows "Claude Code login required", Codex shows the codex --login command.

Anomaly detection

• Velocity alert — character gets a hit effect (star burst + shake) when $/min exceeds your threshold
• Historical baseline — character gets a poison effect (purple bubbles + color pulse) when usage exceeds N× your 24-hour average
• Both effects only appear in character mode
• Off by default. Configure in Settings → Notifications.

_{Star burst + shake effect fires when your spending rate crosses the threshold.}

Settings

• Aggregated or per-provider display with independent style overrides
• Widget order (up/down buttons + show/hide per provider)
• HP bar — thin bar above character showing remaining Claude/Codex usage (green → yellow → orange → red)
• Sleep delay (30s / 1m / 1m 30s / 2m)
• Usage alerts (Claude 75%, 90%)
• About page with toki CLI version and Homebrew update check
• Full Korean / English localization
• Liquid Glass on macOS Tahoe

Sync (server mode)

Connect to a toki-sync server to view usage across all your devices.

• Local / server toggle in the dashboard toolbar — switch between local and server-aggregated data
• Server mode queries toki-sync's PromQL proxy via URLSession (no CLI subprocess overhead)
• Device list with last-seen timestamps for all registered devices
• Token refresh — automatic JWT refresh on 401, system notification when re-login is needed
• HTTPS enforced — non-HTTPS server URLs are rejected (localhost exempt for development)

Configure in Settings → Sync — enter the server URL and authenticate via device code flow (opens browser). Credentials are stored in the macOS Keychain, shared with the toki daemon.

How it works

Why toki?

Every other AI usage monitor works the same way: poll files on a timer, reparse everything, show the result, throw it away. Switch time ranges? Rescan. Close the app? Data gone.

toki is different — a Rust daemon that watches AI tool session files via kqueue, event-driven instead of polling. Tokens flow into an embedded time-series database (fjall TSDB) instantly. When nothing happens, CPU usage is literally 0%. The full token history is indexed and queryable at any time range in ~7 ms via PromQL, in ~5 MB of memory.

See docs/strengths.md for the full comparison against polling- and proxy-based monitors.

Architecture

toki (Rust daemon)              Toki Monitor (Swift/SwiftUI)
├─ fjall TSDB                   ├─ Data        // UDS, CLI, Keychain, ServerQueryClient
├─ kqueue file watchers         ├─ Domain      // Aggregation, alerts, SyncManager
├─ PromQL engine                └─ Presentation// Menu bar, dashboard, sync settings
├─ UDS server
└─ sync thread → toki-sync     toki-sync server (optional)
                                ├─ PromQL proxy (VictoriaMetrics)

Local:  Panel query → toki report → Chart
Server: Panel query → URLSession → toki-sync → VM → Chart

Privacy

• All data stays on your machine — no telemetry, no cloud
• Usage APIs read only rate limit status, never prompts or responses
• toki reads session files read-only — never modifies your AI tool data

Supported providers

Adding a provider only requires a toki parser — Toki Monitor picks it up automatically.

Testing

xcodebuild test -scheme TokiMonitor -destination 'platform=macOS'

36 tests, 8 suites: event parsing, report decoding, state transitions, animation mapping, formatting, provider registry, data aggregation.

Contributing

See CONTRIBUTING.md for setup, build commands, and PR guidelines.

Quick path:

1. Fork → feature branch → PR against main
2. For bugs: include macOS version, toki --version, steps to reproduce

Custom animations

Add your own character to the menu bar. Each theme is a folder under Resources/Animations/:

Resources/Animations/
  rabbit/              ← built-in default
    theme.json
    run_00.png
    run_01.png
    ...
  your-character/      ← add your own
    theme.json
    run_00.png ~ run_XX.png
    sleep_00.png ~ sleep_XX.png   (optional)

Frame specs

• Size: 28×18 px (or any size — set in theme.json)
• Format: transparent background PNG, black only (#000000)
• Template: frames are rendered as macOS template images (system tints automatically)
• Naming: run_00.png, run_01.png, ... (sequential, zero-padded)
• Count: any number of frames — detected automatically

theme.json

{
  "id": "your-character",
  "name": "Display Name",
  "nameKo": "한국어 이름",
  "frameSize": [28, 18],
  "canvasSize": [28, 18],
  "hpBar": {
    "widthRatio": 0.7,
    "height": 2,
    "yOffset": 1,
    "xOffset": 0
  },
  "sleep": {
    "mode": "overlay",
    "textOffset": [-7, -1],
    "fontSize": 5,
    "interval": 0.8
  }
}

Themes are discovered at launch. Select in Settings → Menu Bar → Character.

Upcoming

• Gemini CLI support — Google Gemini provider integration
• Multi-device sync — shipped, share usage across machines via toki-sync (server mode in dashboard)
• Usage reports — weekly/monthly summaries with week-over-week and month-over-month comparisons

Sponsor

If Toki Monitor is useful to you, consider sponsoring to support development.

For commercial use in paid products, please sponsor or reach out.

License

FSL-1.1-Apache-2.0 — built by @korjwl1

Part of the toki ecosystem.