Documentation
Getting Started
One command. No sign-up. No auth. Run it in your terminal.
Here's what happens when you run it for the first time:
Your stats are scanned
ccwrapped reads your local Claude Code logs and shows a summary (tokens, cost, sessions) in the terminal.
Stats are synced
Daily totals are uploaded to ccwrapped.dev. No account needed — you get an anonymous profile URL instantly. Syncs are rate-limited to once every 15 minutes.
Your profile opens in the browser
See your stats visualized on the web. Heatmap, model breakdown, cost charts — all there.
Auto-sync is enabled
A hook is silently installed in your Claude Code settings. From now on, stats sync automatically after every Claude Code session.
Claim a username (optional)
Visit your profile and click "Claim with Google" to get a custom URL like ccwrapped.dev/alice.
That's it. You never need to run this again — auto-sync handles everything.
Commands Reference
| Command | Purpose |
|---|---|
| npx ccwrapdev | Scan + sync stats (no auth needed) |
| npx ccwrapdev --local | View local stats (offline) |
| npx ccwrapdev sync | Manual sync to ccwrapped.dev |
| npx ccwrapdev sync --minimal | Sync without model data |
| npx ccwrapdev setup | Re-enable auto-sync hook |
| npx ccwrapdev setup --check | Check auto-sync status |
| npx ccwrapdev setup --disable | Disable auto-sync hook |
| npx ccwrapdev card | Open profile in browser |
| npx ccwrapdev card --copy | Copy profile URL to clipboard |
| npx ccwrapdev status | Show config overview |
| npx ccwrapdev auth --logout | Logout this device (preserves profile) |
| npx ccwrapdev auth --logout --hard | Reset account (wipe token + profile) |
Auto-Sync Setup
Auto-sync adds a hook to ~/.claude/settings.json that runs after every Claude Code session. Your stats are uploaded silently in the background.
Enable auto-sync
Check status
Disable auto-sync
Auto-sync is enabled automatically on your first npx ccwrapdev run. You can verify with npx ccwrapdev setup --check.
Syncs are rate-limited to once every 15 minutes. When you visit your own profile, you'll see whether the next sync is available or how long until it is.
Privacy & Security
ccwrapped reads your Claude Code logs locally, aggregates daily totals, and uploads only the summary. Your code, conversations, and file paths never leave your machine.
What we collect
- Daily token counts
- Session count
- Model split
- Cost estimate
- Tool usage counts
- Files touched count
- Lines written count
What we never see
- Your code
- Your conversations
- File paths
- Project names
For maximum privacy, use npx ccwrapdev sync --minimal to upload only token counts — no model names, no session counts, no project counts.
Local Stats
View your Claude Code stats without uploading anything. Works offline, no authentication required.
Shows a table with token counts and cost for today, last 7 days, and all time. Also shows your model usage breakdown with percentages. No data leaves your machine.
Updating
New users automatically get the latest version on their first run. Existing users with auto-sync enabled need to refresh once to pick up new features and fixes.
Why a refresh is needed
When you first ran npx ccwrapdev setup, it installed a local copy of the CLI to ~/.config/ccwrapped/pkg and wired your auto-sync hook to that exact path. The hook keeps running that pinned copy after every Claude Code session — it doesn't automatically check for newer versions.
To pick up a new release, you have to disable and re-enable auto-sync. That re-runs the install step and grabs the latest published version.
The one-liner
The @latest tag forces npx to bypass any cached older version. After this runs, your local pinned copy is on the latest release and the auto-sync hook will use it from the next Claude Code session onward.
Verify the version
Should print the current published version. Compare with the version on npm — if they match, you're up to date.
What you'll get from updating
- • A full year of historical Claude Code activity on your profile (was capped at 30 days)
- • Stable per-machine identification — no more accidental phantom profiles after a state reset
- • Friendlier error messages and a cleaner recovery path when something goes wrong
Troubleshooting
No Claude Code logs found
ccwrapped looks in ~/.config/claude/projects/ and ~/.claude/projects/ for session transcripts. Make sure you have used Claude Code at least once. If your config is in a custom location, set the CLAUDE_CONFIG_DIR environment variable.
I use multiple machines
ccwrapped detects when a sync comes from a different machine and shows a warning. Both machines can sync to the same profile — data is merged by date.
Auto-sync stopped working
Run npx ccwrapdev setup --check to verify the hook is installed. Then run npx ccwrapdev status to check your last sync time. If you see "Rate limited", the auto-sync hook ran but the server asked it to wait — it will retry on the next session.
I see "Rate limited. Try again in X minutes."
Syncs are limited to once every 15 minutes. The CLI remembers the cooldown so it skips scanning until the limit expires. Just wait and try again — or use npx ccwrapdev --local to view your stats offline in the meantime.
How do I remove my credentials?
Run npx ccwrapdev auth --logout to clear local session data while keeping your sync token and profile linked to this machine — so you can sign back in later. If you want to fully reset (wipe the sync token and create a fresh profile), run npx ccwrapdev auth --logout --hard. To also disable the auto-sync hook, run npx ccwrapdev setup --disable.
I'm seeing 'Invalid sync token' errors
This means your local sync token references a profile that no longer exists on the server (often because the account was deleted or reset on another device). The CLI will detect this on the next interactive run and offer to reset your local state — just answer Y at the prompt. If you're running in CI or a non-interactive shell, run npx ccwrapdev auth --logout --hard manually to reset.
How do I update ccwrapped to the latest version?
Run npx ccwrapdev@latest setup --disable && npx ccwrapdev@latest setup. The auto-sync hook installs a pinned local copy of ccwrapdev under ~/.config/ccwrapped/pkg, so the hook keeps running whatever version was installed at setup time. Disabling and re-enabling triggers a fresh install of the latest published version. See the "Updating" section above for full details.
Ready to get started?
npx ccwrapdevQuestions? Check the GitHub repo.