token-rats

Strava for AI token burn — sync your Claude Code + Cursor + Codex usage to your Token Rats leaderboard. Run once, watches forever.

Install

npx token-rats login   # one-time auth
npx token-rats sync    # uploads usage, then asks to install a background watcher

After your first successful sync, the CLI asks:

Install background sync? [Y/n]

Say yes once and you’re done. A native OS service (launchd on macOS, systemd --user on Linux) keeps watching your Claude Code, Cursor, and Codex logs and uploads new sessions automatically. No more sync runs, no cron jobs to babysit.

For a stable install across reboots, install globally rather than via npx:

npm install -g token-rats
token-rats sync

Commands

| Command | Description | |---|---| | token-rats login | Open your browser to authenticate (device-code flow). Saves a token to ~/.config/token-rats/token. | | token-rats sync | Discover Claude Code, Cursor, and Codex logs, parse them, upload counts. On first success, prompts to install the background watcher. | | token-rats watch | Run the watcher in your terminal (Ctrl-C to stop). Useful for debugging. | | token-rats watch --install | Install the background watcher (launchd / systemd --user). | | token-rats watch --uninstall | Remove the background watcher. | | token-rats watch --status | Show whether the watcher is installed and running. | | token-rats whoami | Show the currently signed-in account handle. | | token-rats logout | Delete your stored credentials. | | token-rats --version | Print the CLI version. | | token-rats help | Print this help. |

Sync flags

token-rats sync [--dry-run] [--verbose] [--no-daemon] [--api-url <url>]

| Flag | Description | |---|---| | --dry-run | Parse files but do not upload. Prints what would be sent. | | --verbose | Print which files were discovered and how many records each contains. | | --no-daemon | Skip the post-sync prompt to install the background watcher. (TOKEN_RATS_NO_DAEMON=1 does the same globally.) | | --api-url <url> | Override the API base URL (useful for local dev or staging). |

Watch flags

token-rats watch [--install | --uninstall | --status]
token-rats watch [--interval <ms>] [--verbose]

| Flag | Description | |---|---| | --install | Install the background watcher. Idempotent. | | --uninstall | Remove the background watcher. | | --status | Print install + running state and the log path. | | --interval <ms> | Debounce window for file-change uploads. Default: 2000. | | --verbose | Print per-file change events and uploads. |

Background watcher details

• Sources watched: Claude Code (~/.claude/projects/**/*.jsonl), Codex rollouts, and Cursor's per-workspace SQLite cache.
• Cursor polling: every 90s, stat()-first, capped to the 10 most-recently-modified workspaces. Idle CPU is near zero.
• macOS: ~/Library/LaunchAgents/com.tokenrats.watch.plist. Auto-restarts on crash and runs at login.
• Linux: ~/.config/systemd/user/token-rats-watch.service. Auto-restarts on crash. For the watcher to survive logout, run once: sudo loginctl enable-linger $USER. Without it, the watcher resumes at your next login.
• Windows: not yet supported. Use token-rats sync for now.
• Logs: ~/.config/token-rats/logs/watch.log (or ~/Library/Application Support/token-rats/logs/ on macOS).
• Auth expiry: if your session expires, the watcher backs off 10 minutes instead of crashing. Run token-rats login to recover; the watcher picks up on its own.
• Upgrades: when you npm update -g token-rats, just run token-rats sync once — the daemon re-installs against the new binary path automatically.

What data is collected

Token Rats reads usage counts only. It reads:

• Input token count
• Output token count
• Model name
• Session start/end timestamps

It does not read, store, or transmit any prompt or completion content.

The parser source code is in packages/parsers/. You can audit exactly what is extracted before running sync. We literally can't read what you typed.

Data sources

Claude Code

Reads ~/.claude/projects/**/*.jsonl (macOS/Linux) or %USERPROFILE%\.claude\projects\**\*.jsonl (Windows).

Cursor

Reads per-workspace SQLite caches under Cursor/User/workspaceStorage/*/state.vscdb:

• macOS: ~/Library/Application Support/
• Linux: ~/.config/
• Windows: %APPDATA%\

Cursor doesn't store token counts on disk for most sessions, so per-request tokens are estimated from request type. Numbers are comparable across Token Rats users but won't match cursor.com to the token. If the Cursor database isn't found or can't be read, the CLI skips it silently.

Codex

Reads rollout JSONL files under <codex-home>/sessions/YYYY/MM/DD/. <codex-home> defaults to ~/.codex; Snap and Flatpak distros are also probed.

Auth

Authentication uses a device-code flow:

1. token-rats login calls the Token Rats API to get a one-time code and URL.
2. Your browser opens the URL automatically (or you can copy-paste it).
3. You sign in with GitHub on the web.
4. The CLI polls until approved, then saves your token to ~/.config/token-rats/token (mode 0600 — readable only by you).

Requirements

• Node.js ≥ 20
• A Token Rats account (sign up at tokenrats.com)

Privacy

Token Rats is open source. The CLI source is in packages/cli/ and the parsers are in packages/parsers/. You can inspect exactly what is read from your disk and what is sent to the server.

Privacy posture: Token Rats reads usage counts only — never prompts or completions. The parser source is in packages/parsers/. We literally can't read what you typed. The background watcher follows the same rule — it's the same parser code on a timer.