Setup
Track your Claude Code usage
claudeusage reads your local Claude Code usage and turns it into a public profile and leaderboard. Here is everything you need to get started.
npx claudeusage-syncGet started
Install and run the CLI
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.Approve the device
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.
Re-sync any time
Later runs reuse the saved token and upload only new data since the last sync — no browser step:
npx claudeusage-sync
Flags and commands
Useful flags and commands for npx claudeusage-sync:
--dry-run | Show what would be uploaded without sending it |
--since=2026-06-01 | Re-scan from a specific date |
doctor | Diagnose what the CLI sees in your local logs |
status | Show your last sync time |
unlink / logout | Remove the local token |
Switch accounts or re-authenticate
The 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.
Preserve old local history
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-runWhat becomes public
Your 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.
Understand your usage
Read the usage guides for token definitions, cost estimates, multi-machine setup, and privacy. Agents can read the same material at llms.txt.
FAQ
- How do I track my Claude Code usage?
- Run npx claudeusage-sync (Node 22 or newer, no global install). On first run your browser opens to approve the device; the CLI then scans ~/.claude/projects/ and uploads your aggregate totals — billed tokens, API-equivalent cost, and active hours — to your public claudeusage profile.
- Is my Claude Code data private?
- Only aggregate numbers are uploaded. Prompts, responses, code, file paths, project names, email, and device details never leave your machine, and the sync CLI is open source so you can audit exactly what it sends.
- How do I sync new Claude Code usage later?
- Run npx claudeusage-sync again. Later runs reuse the saved token and upload only new data since the last sync — no browser step. Use --dry-run to preview what would be sent, --since=DATE to re-scan from a date, and status to see your last sync time.
- What happens if my local Claude Code logs rotate or get deleted?
- Once a successful sync has uploaded aggregate day buckets, those totals stay in your claudeusage history even if the local logs later rotate or disappear. The CLI can only read logs that still exist, so sync before they rotate.
- What shows up on my public claudeusage profile?
- 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.
- Is the claudeusage sync CLI open source?
- Yes. claudeusage-sync is MIT-licensed and public on GitHub, so you can audit exactly what it reads and uploads.
Open source
The sync CLI is MIT-licensed and public, so you can audit exactly what it does.