Tokenboard

A competitive, private leaderboard for AI coding-agent usage among friends and teams.

Install the CLI, join a team with an invite code, and see who's burning the most tokens this week. Tokenboard celebrates high usage as bragging rights — it's a flex, not a cost-cutting tool.

It reads your local coding-agent usage (via ccusage, which already supports Claude Code, Codex, OpenCode, Gemini CLI and more), and pushes only the token counts — never prompts, file paths, or project names — to a shared team board.

Differentiator: unlike global-leaderboard tools (e.g. tokscale), Tokenboard is invite-only and team-scoped — you compete with your friends, not strangers.

Launch criteria (v1 definition of done)

"Done" means friends are using it, not that the code works. v1 ships when:

1. ≥3 friends have run the install script and appear on one shared team board with real, non-zero Spend.
2. The board stays fresh for a week with zero babysitting — background sync keeps working on their machines without manual intervention.
3. Install → first leaderboard view in under ~2 minutes, with no README-spelunking required.
4. At least one team comes back across multiple days — someone reacts to the board in the group chat unprompted (the real retention signal).

Install

One line takes a fresh machine from nothing to installed, initialized, and auto-syncing:

curl -fsSL https://tokenboard.dev/install.sh | sh

It checks for Node 22+ (and tells you how to get it if missing — it won't install Node for you), runs npm i -g @aravindballa/tokenboard, runs tokenboard init to set up your identity, then enables a background Sync schedule that fires ~every 5 minutes.

Background sync

The schedule is managed by tokenboard schedule:

tokenboard schedule enable    # install + start the ~5-min background sync
tokenboard schedule status    # is it installed?
tokenboard schedule disable   # stop + remove it

On macOS this is a launchd LaunchAgent at ~/Library/LaunchAgents/dev.tokenboard.sync.plist; on Linux it's a systemd user timer at ~/.config/systemd/user/dev.tokenboard.sync.timer (fall back to a */5 * * * * cron entry if systemd isn't available).

Because Sync is idempotent and the board also syncs on view, a missed or broken scheduled run self-heals on the next run — nothing to babysit, no data corruption.

How it works

• CLI (tokenboard, TypeScript/Node) — view the leaderboard, create/join teams, and sync usage.
• Sync — ccusage parses local transcripts; the CLI pushes per-day, per-source, per-model figures (ccusage's computed Spend and the raw token counts, plus a device id) to a Convex backend. The board shows ccusage's Spend; the counts are kept so it can be recomputed later if needed.
• Freshness — an OS scheduler (launchd/systemd/cron) syncs ~every 5 min, and the CLI also syncs whenever you run it. Upserts are idempotent and keyed by (user, device, date, source, model), so missed runs self-heal and multiple machines don't clobber each other.

See CONTEXT.md for the project glossary.

Shipping to real users (maintainer steps)

The build bakes a default Convex deployment URL into the bundle (read from CONVEX_URL / .env.local at build time) so the globally-installed CLI works from any directory with no config file. A runtime TOKENBOARD_CONVEX_URL still overrides it, and .env.local is still honored in dev. The currently baked URL is the dev deployment — these steps swap it for prod and publish:

1. Provision prod: npx convex deploy to create the production deployment and get its URL.
2. Rebuild with the prod URL: CONVEX_URL=https://<your-prod>.convex.cloud npm run build so the bundle bakes prod, not dev.
3. Publish: the package is the scoped name @aravindballa/tokenboard; publishConfig.access is set to public, so it installs free for anyone despite being scoped. The prepublishOnly hook rebuilds dist, which re-bakes the Convex URL — so set it on the publish command or you'll ship the dev URL:

   CONVEX_URL=https://<your-prod>.convex.cloud npm publish

4. Host the installer: put install.sh at the curl URL above (e.g. tokenboard.dev/install.sh) or point people at the raw repo file.
5. Each user runs the one-liner, which enables their own schedule. Nothing here activates a schedule on the build/publish machine.