docs
❯How it works
claudeusage reads your local Claude Code usage and turns it into a public profile and leaderboard. Here is everything you need to get started.
Only aggregate numbers are uploaded — never prompts, code, or files. The tool that syncs your usage is open source and auditable: claudeusage-sync.
docs
claudeusage reads your local Claude Code usage and turns it into a public profile and leaderboard. Here is everything you need to get started.
You need Node 22 or newer. Run the sync command — no global install required:
npx claudeusage-syncOn first run, your browser opens to approve the device. After you approve, the CLI saves a long-lived sync token locally, scans ~/.claude/projects/, and uploads your aggregate totals.
If the browser does not open automatically, the terminal prints the exact approval link. Open that link, sign in, start the free trial if prompted, and approve the device. The approval tab opens your dashboard with a syncing spinner while the CLI uploads your aggregate history.
Later runs reuse the saved token and upload only new data since the last sync — no browser step:
npx claudeusage-syncUseful flags and commands:
--dry-run — show what would be uploaded without sending it--since=2026-06-01 — re-scan from a specific datedoctor — diagnose what the CLI sees in your local logsstatus — show your last sync timeunlink / logout — remove the local tokenThe website session and the CLI sync token are separate. To sign into the website as a different user, use the sign out button in the dashboard header, then sign in again with Google or GitHub.
To make the CLI authorize a different claudeusage account, remove the local sync token and run the sync command again:
npx claudeusage-sync logoutnpx claudeusage-syncThe second command opens the browser approval flow again. Approve the device while signed into the account you want the local Claude Code logs to sync into.
claudeusage can only upload the Claude Code logs that still exist on your machine. Once a successful sync has uploaded aggregate day buckets, those totals stay in your claudeusage history even if local logs later rotate or disappear.
If you want to confirm what will be sent before uploading, run:
npx claudeusage-sync --dry-runYour profile shows API-equivalent cost, active hours, billed tokens, session counts, model mix, and a day-level activity grid. The leaderboard ranks everyone by cost, hours, or tokens. Prompts, file paths, project names, email, and device details are never uploaded or shown — see the privacy page.
The sync CLI is MIT-licensed and public, so you can audit exactly what it does.
claudeusage-sync on GitHub