@piash.tanjin/agent-usage

The open-source companion for Agent Usage, a public leaderboard of AI coding-agent token usage. It reads token counts from your coding tools' local logs and uploads daily totals per tool and model — never prompts, code, file paths or credentials.

npx @piash.tanjin/agent-usage pair <CODE> --server <URL>   # no install needed

Or install it once and use the shorter agentusage command (the unscoped names agentusage/agent-usage on npm belong to other projects):

npm i -g @piash.tanjin/agent-usage
agentusage status

Requires Node.js 22.13 or newer.

Getting started

1. Sign up on the Agent Usage website. Onboarding shows a one-time pairing code, valid for 10 minutes.
2. Pair this machine. The first sync runs right away:

   npx @piash.tanjin/agent-usage pair ABC-123 --server https://your-agent-usage-site

3. Keep it current:

   npx @piash.tanjin/agent-usage watch            # syncs every 5 minutes; Ctrl+C to stop
   npx @piash.tanjin/agent-usage sync             # or sync once, whenever you like

Commands

| Command | What it does | |---|---| | pair [CODE] [--server URL] [--name DEVICE] [--only a,b] | Pair this device with your profile, then sync. Prompts for the code if you leave it out. --only limits which tools are read and is remembered. | | sync | Upload daily token counts now. | | watch [--every MINUTES] | Keep syncing (default every 5 minutes). | | preview | Print exactly what would be uploaded. Nothing is sent. | | status [--period YYYY-MM\|all] | Your local totals by tool and model. No network. | | verify [claude\|codex\|cursor] [--yes] | Prove you own these accounts (see below). | | unpair | Revoke this device's upload credential and delete the local config. |

sync, preview and status also accept --only claude,codex,….

What it reads

| Tool | Local logs | |---|---| | Claude Code | ~/.claude/projects (or $CLAUDE_CONFIG_DIR/projects) | | Codex | ~/.codex/sessions, ~/.codex/archived_sessions (or $CODEX_HOME) | | Pi / OMP | ~/.pi/agent/sessions, ~/.omp/agent/sessions | | OpenCode | ~/.local/share/opencode/opencode.db | | Muse Code | ~/.local/share/muse/sessions (or $MUSE_SESSIONS_DIR) | | Gemini CLI | ~/.gemini/tmp/*/chats |

Tools you don't use are skipped. Counting rules follow CodexBar's local scanners, so streamed or resumed sessions aren't double counted.

Cursor keeps no token logs on disk. Its usage comes only from Cursor itself, through agentusage verify cursor.

What it sends

One record per tool, model and UTC day:

{
  "provider": "claude",
  "model": "claude-sonnet-5-5",
  "date": "2026-09-29",
  "input_tokens": 18230,
  "cached_input_tokens": 96410,
  "output_tokens": 4112,
  "event_id": "c1f0…9a2e",
  "collector_version": "0.3.0"
}

event_id is a hash of device, tool, model and day, so re-syncing a day replaces it instead of adding to it. Run npx @piash.tanjin/agent-usage preview to see your own records before anything is sent.

Verified accounts

Anyone can edit their local logs, so every number on the board is self-reported unless verified. verify proves you own the account behind your usage:

| Account | How | What leaves your machine | |---|---|---| | codex | The server checks OpenAI's signature on Codex's ID token. | Only the signed ID token, which can't be used to act as you. Your access token is never read. | | claude | The server asks Anthropic once who the login belongs to, then discards it. | Your Claude Code login token, once, after you confirm. | | cursor | The server reads your account and Cursor's own token counts from Cursor, then discards the login. | Your Cursor login token, once, after you confirm. |

A verified account can back only one profile. Verified profiles get a badge and skip the 7-day wait before new accounts are ranked.

Files

• ~/.agent-usage/config.json holds the server URL and this device's upload credential (mode 0600). Override the folder with AGENT_USAGE_HOME.

License

MIT