{"_id":"@aravindballa/tokenboard","_rev":"2-5377fe0a70d44eb8b8f1a7b5b4127636","name":"@aravindballa/tokenboard","dist-tags":{"latest":"0.1.0"},"versions":{"0.0.1":{"name":"@aravindballa/tokenboard","version":"0.0.1","_id":"@aravindballa/tokenboard@0.0.1","maintainers":[{"name":"aravindballadev","email":"bsaaravind@gmail.com"}],"bin":{"tokenboard":"dist/index.js"},"dist":{"shasum":"afdafd7a7b34b2fb3ae119101846dcbbdc6c2fd5","tarball":"https://registry.npmjs.org/@aravindballa/tokenboard/-/tokenboard-0.0.1.tgz","fileCount":3,"integrity":"sha512-GpOax4VVQVzpbzZwBHcbfhk6GGmye7+Xu7ssnqvP04PyVX57JZMiuqESkXkwDC312jkXwbzh8qRxUOWc8c4ZMA==","signatures":[{"sig":"MEUCIQC3n08Wt22MdXNOV1lwt886MbmRSaoFTxIh825omcx2TQIgL39/wRz9H7OMo+zw4RYUQtqbp9dJx6adhD8BTf3Vu+Q=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":23117},"type":"module","engines":{"node":">=22"},"gitHead":"90566949214964510b26c56aa50754574a456997","scripts":{"dev":"tsx src/index.ts","test":"vitest run","build":"tsup","convex":"convex dev","typecheck":"tsc -p tsconfig.json && tsc -p convex/tsconfig.json","test:watch":"vitest","prepublishOnly":"npm run build"},"_npmUser":{"name":"aravindballadev","email":"bsaaravind@gmail.com"},"_npmVersion":"10.9.3","description":"Private token-usage leaderboards for your dev friends","directories":{},"_nodeVersion":"22.18.0","dependencies":{"convex":"^1.17.0","dotenv":"^16.4.5","ccusage":"^20.0.14","commander":"^12.1.0","env-paths":"^3.0.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.19.0","tsup":"^8.3.0","vitest":"^2.1.0","typescript":"^5.6.0","@types/node":"^20.16.0","convex-test":"^0.0.35","@edge-runtime/vm":"^4.0.0"},"_npmOperationalInternal":{"tmp":"tmp/tokenboard_0.0.1_1782138683123_0.20459572489572175","host":"s3://npm-registry-packages-npm-production"}},"0.1.0":{"name":"@aravindballa/tokenboard","version":"0.1.0","description":"Private token-usage leaderboards for your dev friends","type":"module","bin":{"tokenboard":"dist/index.js"},"publishConfig":{"access":"public"},"scripts":{"dev":"tsx src/index.ts","convex":"convex dev","build":"tsup","prepublishOnly":"npm run build","typecheck":"tsc -p tsconfig.json && tsc -p convex/tsconfig.json","test":"vitest run","test:watch":"vitest"},"dependencies":{"ccusage":"^20.0.14","commander":"^12.1.0","convex":"^1.17.0","dotenv":"^16.4.5","env-paths":"^3.0.0"},"devDependencies":{"@edge-runtime/vm":"^4.0.0","@types/node":"^20.16.0","convex-test":"^0.0.35","tsup":"^8.3.0","tsx":"^4.19.0","typescript":"^5.6.0","vitest":"^2.1.0"},"engines":{"node":">=22"},"_id":"@aravindballa/tokenboard@0.1.0","gitHead":"8217e29ffc79aeb1326098a13383985fb37e093a","_nodeVersion":"22.18.0","_npmVersion":"10.9.3","dist":{"integrity":"sha512-X0mdaW7dUev/yzlBQd7NNv+qBj/kBMGBvGndLT+bGvRktej9WwVAUZQsHJm7f8UT01qu0tYXCzJweNI4Z4iU6A==","shasum":"009b14387aa9a399095066dfcb513f88aa14eaee","tarball":"https://registry.npmjs.org/@aravindballa/tokenboard/-/tokenboard-0.1.0.tgz","fileCount":3,"unpackedSize":33114,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQCkNTU0C59QqqmRQNDcGsuRddBJIe0EgEmhvRgJjkw/qgIgerMNc++HhBjSAsd6m2ke+e+GyXittoApPSkjfuLyY3s="}]},"_npmUser":{"name":"aravindballadev","email":"bsaaravind@gmail.com"},"directories":{},"maintainers":[{"name":"aravindballadev","email":"bsaaravind@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/tokenboard_0.1.0_1782196156004_0.7611389130623607"},"_hasShrinkwrap":false}},"time":{"created":"2026-06-22T14:31:22.910Z","modified":"2026-06-23T06:29:16.273Z","0.0.1":"2026-06-22T14:31:23.265Z","0.1.0":"2026-06-23T06:29:16.139Z"},"description":"Private token-usage leaderboards for your dev friends","maintainers":[{"name":"aravindballadev","email":"bsaaravind@gmail.com"}],"readme":"# Tokenboard\n\nA competitive, **private** leaderboard for AI coding-agent usage among friends and teams.\n\nInstall 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.\n\nIt reads your local coding-agent usage (via [ccusage](https://ccusage.com), 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.\n\n> **Differentiator:** unlike global-leaderboard tools (e.g. tokscale), Tokenboard is invite-only and team-scoped — you compete with your friends, not strangers.\n\n## Launch criteria (v1 definition of done)\n\n\"Done\" means friends are *using* it, not that the code works. v1 ships when:\n\n1. **≥3 friends** have run the install script and appear on one shared team board with real, non-zero Spend.\n2. The board **stays fresh for a week with zero babysitting** — background sync keeps working on their machines without manual intervention.\n3. **Install → first leaderboard view in under ~2 minutes**, with no README-spelunking required.\n4. At least one team **comes back across multiple days** — someone reacts to the board in the group chat unprompted (the real retention signal).\n\n## Install\n\nOne line takes a fresh machine from nothing to installed, initialized, and auto-syncing:\n\n```sh\ncurl -fsSL https://tokenboard.dev/install.sh | sh\n```\n\nIt 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.\n\n### Background sync\n\nThe schedule is managed by `tokenboard schedule`:\n\n```sh\ntokenboard schedule enable    # install + start the ~5-min background sync\ntokenboard schedule status    # is it installed?\ntokenboard schedule disable   # stop + remove it\n```\n\nOn 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).\n\nBecause 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.\n\n## How it works\n\n- **CLI** (`tokenboard`, TypeScript/Node) — view the leaderboard, create/join teams, and sync usage.\n- **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](https://convex.dev) backend. The board shows ccusage's Spend; the counts are kept so it can be recomputed later if needed.\n- **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.\n\nSee [`CONTEXT.md`](./CONTEXT.md) for the project glossary.\n\n## Shipping to real users (maintainer steps)\n\nThe 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:\n\n1. **Provision prod:** `npx convex deploy` to create the production deployment and get its URL.\n2. **Rebuild with the prod URL:** `CONVEX_URL=https://<your-prod>.convex.cloud npm run build` so the bundle bakes prod, not dev.\n3. **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:\n   ```sh\n   CONVEX_URL=https://<your-prod>.convex.cloud npm publish\n   ```\n4. **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.\n5. Each user runs the one-liner, which enables their own schedule. Nothing here activates a schedule on the build/publish machine.\n","readmeFilename":"README.md"}