token-larper

v1.23.0

Published

21 hours ago

Token Larper — Multi-Harness AI Coding Usage & Cost Telemetry Dashboard powered by ccusage

0High
0Medium
0Low

claude-code ccusage antigravity codex copilot-cli opencode token-tracker token-usage ai-coding-agents llm-observability cost-telemetry system-tray bun

Token Larper reads the session logs that Claude Code, Codex, Antigravity, GitHub Copilot CLI, OpenCode, and 13 other coding agents already write to your disk, and turns them into a dashboard at localhost:4269. Nothing about your usage leaves your machine. It runs on Windows, macOS, and Linux, and on Windows it also sits in the system tray.

It's built on top of ccusage, which does the log parsing, token counting, and pricing. Token Larper adds the dashboard, the tray icon, project grouping, and the Hall of Larp.

Quick start

Token Larper runs on Bun 1.1 or later. Install it once:

# macOS & Linux
curl -fsSL https://bun.sh/install | bash

# Windows
powershell -c "irm bun.sh/install.ps1 | iex"

Restart your terminal, then run:

bunx token-larper

It starts in the background and opens the dashboard. Stop it with bunx token-larper stop.

A quick tour

The screens below use sample data. No local sessions or project names are included.

| Usage breakdown | Projects | | --- | --- | | Usage chart and token mix | Sessions grouped by project |

| Hall of Larp | Settings | | --- | --- | | Rank and badges | Theme and startup settings |

Features

Private and offline: No API keys and no proxy to set up. Two optional requests leave your machine, and neither sends anything about your usage: an update check that asks npm for the latest version number, and a once-a-day download of OpenRouter's public model price list. Settings → Privacy shows when each last ran, turns the update check off, and has an Offline mode switch that stops both (you can also start with TOKEN_LARPER_OFFLINE=1). Screenshot mode in the same place replaces project names and folders with Project A, Project B, and so on, for screenshots and screen shares.
18 agents, one total: Every supported harness is detected automatically and counted together, with filters per tool, model, session, and project.
Subscription-aware: Verified API costs are kept apart from the estimated "LARP Value", the API price of tokens you used through a flat-rate plan like Claude Pro/Max, Copilot, or Antigravity. Estimates use OpenRouter's current list prices, so new models are priced without waiting for an update.
Model speed: Approximate output tokens per second for each tool and model, and tokens per minute while a tool is working, read from the session files of Claude Code, Codex, OpenCode, Pi, Antigravity, Gemini CLI, and Copilot CLI. See Speed and Tokens per Minute.
Live mode: Press Live in the top bar and the dashboard becomes one screen that updates every second: tokens per minute with a rolling trace, every response on a tape as it lands, tokens by tool and by model, output speed per response, and your active sessions with their context size. See Live mode.
Hall of Larp: Lifetime token burn, 14 achievements, an 11-tier rank ladder with rivals, a day streak in the header, and a 1200×630 share card.
Six styles, your colors: Grove, Terminal, Paper, Brutal, Soft, and Mono each change fonts, corners, spacing, borders, and shadows. Pick a base color and an accent from presets or any custom color, or import a tweakcn/shadcn CSS theme.
Cross-platform: The engine, scrapers, and dashboard behave the same on Windows, macOS (Apple Silicon and Intel), and Linux. The tray icon is Windows-only.
Lightweight install: About 5 MB with its dependencies, on top of Bun. No Electron, no database, and the dashboard ships prebuilt.

Prerequisites

Before setting up Token Larper, ensure your machine meets the following requirements:

1. Operating System

Token Larper runs across all major operating systems:

Windows 10 / Windows 11 (64-bit x64 or ARM64):
- Full web dashboard + native Windows System Tray widget (t. monogram with live hover stats & boot auto-start).
macOS (12.0+ Monterey or later, Apple Silicon M-series or Intel x64):
- Full web dashboard + all 18 harness scrapers. Launches via terminal or background daemon (nohup / LaunchAgent).
Linux (Ubuntu, Debian, Fedora, Arch, etc., x64 or ARM64):
- Full web dashboard + all 18 harness scrapers. Launches via terminal or systemd --user.

2. Bun Runtime (v1.1+)

Token Larper uses Bun for its ultra-fast JavaScript/TypeScript server, bundling, and process management.

To check if Bun is installed:

bun --version

If you do not have Bun installed:

macOS & Linux:

curl -fsSL https://bun.sh/install | bash

Windows (PowerShell):

powershell -c "irm bun.sh/install.ps1 | iex"

(After installing Bun, restart your terminal so bun is available on your PATH.)

3. Windows PowerShell 5.1+ (Windows Only)

Required only on Windows to draw the DPI-aware notification area system tray icon.
Execution Policy: If your system restricts PowerShell scripts, enable local execution:
```
Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned
```

(On macOS and Linux, the server detects non-Windows platforms automatically and skips the Windows tray initialization).

4. At Least One Supported AI Coding Harness

You should have at least one AI coding harness installed and used on your machine so there are session logs to index (e.g. ~/.claude/ for Claude Code, ~/.local/share/opencode/ for OpenCode, ~/.gemini/ for Gemini/Antigravity, etc.).

Quick Setup & Installation

Option 1: Instant 1-Line Run (Recommended)

With Bun installed, run Token Larper without cloning:

bunx token-larper

It starts in the background, opens the dashboard, and keeps running after you close the terminal. On Windows, quit it from the tray icon. On any platform:

bunx token-larper stop          # stop it
bunx token-larper --foreground  # run in the terminal with logs instead
bunx token-larper --help        # all options

The background server writes its output to server.log in the data folder.

Option 2: Clone from Source

Step 1: Get the Code

Clone the repository (or click Code → Download ZIP on GitHub and extract it):

git clone https://github.com/YarooqH/token-larper.git
cd token-larper

Step 2: Install Dependencies

Install the required packages using Bun:

bun install

Running Token Larper

On Windows

Option A: Silent System Tray (Recommended)

Launches windowless directly into your Windows System Tray without keeping a command prompt open:

bun run tray

Shortcut: You can also simply double-click Start-TokenLarper.vbs in File Explorer!

The Burning t. icon will appear in your notification tray.
Hover over the icon to see your real-time token count and cost estimate.
Left-click the icon for a compact usage popup with an Open dashboard button. Right-click it to sync or configure boot auto-start.

Option B: Terminal Mode (Logs & Development)

bun start          # Standard terminal launch
bun run dev        # Live reload on changes

On macOS & Linux

Option A: Background Daemon

Run the server detached in the background:

nohup bun start > /dev/null 2>&1 &

Option B: Foreground Terminal Mode

bun start          # Standard launch
bun run dev        # Live reload on changes

Opening the Dashboard

Open your browser and navigate to: 👉 http://localhost:4269

(On Windows, left-click the t. tray icon and select Open dashboard, or choose Open Dashboard from its right-click menu.)

Stopping Token Larper

To cleanly stop the server:

From the CLI (All Platforms):
```
bunx token-larper stop   # or, from a clone: bun run stop
```
(Sends a graceful shutdown request to the local API on port 4269. If you changed the port, set PORT the same way first.)
From the Windows Tray: Right-click the t. icon → Select Quit Token Larper.

Uninstalling

Token Larper only reads your agents' logs, so removing it leaves your session history untouched. Do the steps in this order: the Windows startup entry points at the app folder, so turn it off before you delete anything.

1. Turn off startup and stop it

On Windows, if you turned on Start with Windows, turn it off in the dashboard under Settings, or right-click the tray icon and uncheck Start on Windows Boot. Then quit from the tray, or run:

bunx token-larper stop

If you already deleted the app and it still launches at login, remove the startup entry by hand:

reg delete "HKCU\Software\Microsoft\Windows\CurrentVersion\Run" /v TokenLarper /f

On macOS and Linux, stopping it is enough. If you set up your own LaunchAgent or systemd --user unit for it, remove that too.

2. Delete the data folder

This holds settings, caches, the downloaded price list, and server.log:

| OS | Folder | Remove it with | | :--- | :--- | :--- | | Windows | %LOCALAPPDATA%\TokenLarper | Remove-Item -Recurse -Force "$env:LOCALAPPDATA\TokenLarper" | | macOS | ~/Library/Application Support/TokenLarper | rm -rf ~/Library/Application\ Support/TokenLarper | | Linux | ~/.local/share/token-larper | rm -rf "${XDG_DATA_HOME:-$HOME/.local/share}/token-larper" |

If you set TOKEN_LARPER_DATA_DIR, delete that folder instead.

3. Remove the app

Ran it with npx or bunx: Nothing was installed globally. The package sits in the npx or Bun cache, and it's fine to leave it there. To get the space back, delete npx's cache folder (~/.npm/_npx, or %LOCALAPPDATA%\npm-cache\_npx on Windows) or run bun pm cache rm. Both clear every cached package, not only this one; the others download again the next time you use them.
Installed it globally: npm uninstall -g token-larper or bun remove -g token-larper.
Cloned from git: Delete the folder. Versions before 1.5.0 kept their data in .cache inside it, so that goes too.

Bun stays installed. If you only installed it for Token Larper, see Bun's uninstall steps.

Supported Harnesses (18 Agents)

Token Larper utilizes ccusage v20+ paired with native deep scanners to automatically detect and index session history across 18 coding environments:

Configuration & Features

Auto-Start on Windows Boot

You can have Token Larper launch silently into the system tray every time you turn on your computer:

Right-click the t. system tray icon.
Click Start on Windows Boot to enable it.
(Optional) Click Auto-Open Browser on Boot if you want your default browser to launch directly to the dashboard upon login.

(This registers a clean user entry under HKCU\Software\Microsoft\Windows\CurrentVersion\Run\TokenLarper running the windowless launcher).

Custom Port

By default, Token Larper runs on port 4269. You can specify a custom port:

macOS & Linux:
```
PORT=5000 bun start
```
Windows (PowerShell):
```
$env:PORT = "5000"; bun start
```

The port is also persisted in settings.json in the data folder (see below).

Data Folder

Caches and settings live outside the app folder, so updates keep them:

Windows: %LOCALAPPDATA%\TokenLarper
macOS: ~/Library/Application Support/TokenLarper
Linux: $XDG_DATA_HOME/token-larper (default ~/.local/share/token-larper)

Set TOKEN_LARPER_DATA_DIR to use another folder. Versions before 1.5.0 kept this data in .cache inside the app; it is copied over on first run.

Updates

When a new version is on npm, the dashboard shows a banner. Update now starts bunx token-larper@latest in the background; the new version replaces the running one on the same port and the dashboard reloads. You can also check from Settings → About, or turn automatic checks off in Settings → Privacy. A copy cloned from git updates with git pull.

Estimated Prices

When ccusage has no price for a model (a brand-new one, or usage through a flat-rate subscription), Token Larper estimates the cost from list prices. It downloads OpenRouter's public model price list once a day, keeps it in the data folder as openrouter-pricing.json, and prices any model on that list from it. Claude models it doesn't list use Anthropic's rates, built into the app. A model with neither has no price and is left out of estimates; nothing is guessed from its name. Only the price list is downloaded; nothing about your usage is sent, and if the download fails the last saved list is used.

Switch Cost to Estimate to see the prices. The Models tab then adds a Model prices section with the price per 1M tokens (input, output, cache write, cache read) of every model you've used, which OpenRouter listing each one matched, where the prices come from, and when the list was last downloaded. The cost card on the Overview links to it with How this is estimated. In Verified mode there are no prices to show, because verified costs never use them.

Estimates do not include OpenRouter's long-context surcharges, and a model name that OpenRouter spells differently may go unpriced. Verified costs from ccusage are never changed. Turn on Offline mode in Settings → Privacy (or set TOKEN_LARPER_OFFLINE=1) to skip the download and use only the saved list (if any) and the built-in rates.

Speed and Tokens per Minute

The Tools, Models, and Sessions tabs show an approximate Speed column: output tokens per second, timed from when a request is sent to when its last token arrives. ccusage only reports totals, so Token Larper reads the timing from each tool's own session files. Hover a value for the median, p90, and number of responses behind it; a value from fewer than 10 responses is dimmed. On the Tools and Models tabs, Speed follows the date range; on the Sessions tab, each session shows its speed over its whole life.

Speed over time on the Tools and Models tabs draws one line per tool or per model, per day, week, or month, so you can compare them as models and versions change. Switch between Average (all output tokens over all response time, the same as the Speed column) and Median (the middle response's speed), or to Table for the exact numbers. Values from fewer than 10 responses are dimmed. The Models chart shows the 7 models with the most responses in the range; pick a tool to compare only its models.

Speed includes waiting for the first token, and that wait grows with the size of the context. A request with a 500K-token context can spend most of its time before any output appears, so Speed reads lower than a model's own generation speed and lower than providers' published figures. Treat it as how fast responses reach you, not a benchmark.

| Tool | Where the timing comes from | | --- | --- | | OpenCode, Pi, Antigravity | The tool records when each request was sent and finished. OpenCode also records when the first output arrived, so its hover text adds the typical wait for it, and time spent running tools between model calls is left out. | | Claude Code, Codex, Gemini CLI | Inferred from the log line before each response (the prompt or a tool result) and the response's last line. | | Copilot CLI | Per request only with OpenTelemetry file export on (COPILOT_OTEL_ENABLED=true, COPILOT_OTEL_EXPORTER_TYPE=file). Without it, Copilot gets Tokens/min but no Speed. |

Responses under 20 output tokens are left out of Speed, since they are almost all wait. Tokens/min on the Tools tab divides all of a tool's tokens, cache reads included, by the time it was working; gaps of more than 2 minutes between responses don't count. Other tools show a dash.

The first read of the session files runs in the background and can take a few seconds per gigabyte. Results are saved per file in throughput-cache.json in the data folder, so later reads only open files that changed.

Live mode

Press Live in the top bar (or open http://localhost:4269/#live) to swap the dashboard for a single live screen. Press it again, or Esc, to go back. The full-screen button next to the time span fills the monitor.

Tokens per minute: the last 60 seconds, with the 5-minute average and how much of the prompt came from cache. The trace under it is the same rolling minute over the last 15 or 60 minutes, stacked by tool; hover it to read each tool at that moment.
The tape: every response as a tick at the moment its last token landed. Taller ticks wrote more output; hover one for its model, output and speed.
Output, Speed, Requests, Burn rate: output tokens per minute, the median response's tok/s over 5 minutes, requests per minute, and the last 5 minutes' pace in dollars per hour at API list prices.
By tool and By model: tokens in the time span, what each is burning right now, its speed and cost.
Output speed: each response as a dot, with the 5-minute median as a line.
Sessions: sessions that answered in the last 15 minutes, with tokens per minute now, context size (the latest prompt, cache included), speed, and cost over the last hour. Responses lists the newest 14.

Live mode follows the session files of Claude Code, Codex, Pi, Gemini CLI, and Copilot CLI (with OpenTelemetry file export on) as they are written, reading only what was added since its last read, about once a second. Antigravity keeps each conversation in a SQLite database, so Live mode reads the steps added since its last read instead. It stops 30 seconds after you leave Live mode.

What Live mode can't see

Claude chats. Chats on claude.ai and in the Claude app aren't saved on your computer, so they never appear. Only the Code tab in the Claude app counts, since it runs Claude Code.
Some tools. OpenCode and the tools only ccusage reads (Amp, Droid, Goose and the rest) aren't followed live. They show up in the dashboard after a sync.
Responses in progress. A response counts when its last token is logged, so a long one lands all at once and tokens per minute comes in bursts.
More than an hour back. Only the last hour is kept, read again from the session files when Token Larper starts.
What you actually pay. Costs and the burn rate use API list prices, even on a subscription. A model with no known price adds $0.
Pure generation speed. Speed includes the wait for the first token. Antigravity records times to the second, so its short steps read rough. Antigravity's thinking tokens count toward speed but, as in ccusage's totals, not toward token counts.

Tokens include cache reads, the same as everywhere else in the dashboard, so they run far above what the model writes. The same list is on the Live screen: press Limitations in its header.

Headless Server Mode

If running on a remote headless server or Docker container, you can explicitly disable the tray icon (automatically disabled on macOS/Linux):

NO_TRAY=1 bun start

Comparison with Alternatives

Hall of Larp (Rank & Gamification)

Token Larper includes a dedicated Stats tab designed to celebrate your token burn. It opens on your day streak, with the last seven days, and the same streak sits in the header and in the tray popup:

11 Lifetime Tiers: Progress from Newcomer (0 tokens) to Legend (100B tokens), shown as a single rank row with your progress to the next tier.
Rival Leaderboards: Compete against quirky procedural AI rivals as your token count climbs.
14 Achievements: Unlock badges for late-night hacking sessions, burning $100+ in a single day, or harnessing 5+ different agents.
Shareable Rank Card: Generate and export a 1200×630 PNG badge to share on X/Twitter or Discord. Project paths and names are strictly sanitized and never included.

Troubleshooting & FAQ

1. How do I monitor Claude Code token usage and spend locally?

Token Larper automatically scans ~/.claude/ for Claude Code session files and SQLite databases. It displays daily, weekly, and monthly token burns (input, output, cache creation, cache read) alongside verified costs without requiring Anthropic API keys.

2. Can I track tokens across multiple tools like Antigravity, Claude Code, and Codex in one place?

Yes. Token Larper detects and aggregates usage across 18 supported coding harnesses simultaneously, allowing you to see your cross-agent total spend and filter by specific tools.

3. Why track local agent logs instead of using a reverse proxy like LiteLLM?

Many modern coding agents (Claude Code, GitHub Copilot CLI, Antigravity) use OAuth subscriptions rather than raw pay-per-token API keys. Proxies cannot intercept or track these subscription agents without TLS decryption and custom protocol reverse-engineering. Token Larper solves this by reading the session logs the agents write directly to your local drive.

4. `'bun' is not recognized as an internal or external command`

Cause: Bun was installed, but the current terminal session doesn't have %USERPROFILE%\.bun\bin in its PATH.
Fix: Close and reopen your terminal, or manually add it for your session:
```
$env:PATH += ";$env:USERPROFILE\.bun\bin"
```

5. `cannot be loaded because running scripts is disabled on this system`

Cause: Windows PowerShell default execution policy is preventing local scripts from running.

Fix: Open PowerShell as your standard user and run:

Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned

6. The system tray icon is not visible

Cause: Windows may have placed the icon inside the "hidden notification icons" overflow menu (the ^ arrow on the taskbar).
Fix: Click the ^ arrow next to your Windows clock, find the Burning t. icon, and drag it onto your main taskbar to keep it permanently visible.

7. No tokens or sessions are showing up in the dashboard

Cause: Either no coding agents have been executed yet, or their logs are located in non-standard directories.
Fix:
1. Run a quick session with one of your tools (e.g., claude or antigravity).
2. Right-click the system tray icon and click Sync Harnesses Now (ccusage), or click the Sync Now button in the top right of the dashboard.

8. Port 4269 is already in use

Fix: Token Larper might already be running in the background. Stop it using:
```
bun run stop
```
Or change the port:
```
$env:PORT = "4500"
bun start
```

Project Architecture

tokenlarper/
├── Start-TokenLarper.vbs      # Windowless silent launcher for Windows
├── package.json              # Scripts & dependencies
├── scripts/
│   ├── run-server.ps1        # PowerShell background watchdog & port resolver
│   ├── launch-silent.vbs     # VBS helper for boot auto-start
│   ├── tray-host.ps1         # Native DPI-aware Windows Forms system tray host
│   └── launch-on-default-desktop.ps1 # WinSta0\Default desktop trampoline
├── src/
│   ├── server.ts             # Bun HTTP & WebSocket server + client bundler
│   ├── ccusage.ts            # 18-harness telemetry reader & cost calculation engine
│   ├── tray/                 # System tray lifecycle management & IPC (windows.ts)
│   ├── startup.ts            # Windows registry boot integration
│   ├── projects.ts           # Workspace & Git repository deduplication
│   ├── types.ts              # TypeScript interfaces & data contracts
│   └── client/               # React 19 Frontend Dashboard
│       ├── App.tsx           # Layout, navigation, date ranges, and global state
│       ├── charts.tsx        # Stacked SVG bar & trend charts
│       ├── views/            # Overview, Tools, Models, Sessions, Projects, Stats
│       └── styles.css        # Custom responsive CSS design system (Dark/Light)

Acknowledgments & Credits

Token Larper is built directly on top of the work of the open-source community:

ccusage — The core telemetry engine powering local session scraping, token counting, and cost calculations across AI coding harnesses.
Bun — Fast all-in-one JavaScript runtime and bundler.
Lucide Icons — Clean and consistent iconography for the web dashboard.