Documentation
Getting Started
One command gets you set up. Run it in your terminal — not inside Claude Code.
Here's what happens when you run it for the first time:
Sign in with Google
A one-time code appears in your terminal. Your browser opens to Google's device page. Enter the code and authorize.
Pick a username
Choose a username for your public profile (e.g. @alice).
Your stats are scanned and uploaded
ccwrapped reads your local Claude Code logs, aggregates daily totals (tokens, cost, models), and uploads them to ccwrapped.dev.
Your profile opens in the browser
See your stats at ccwrapped.dev/your-username.
Auto-sync is enabled
You're asked "Set up auto-sync? (Y/n)". Press Enter. From now on, stats sync automatically after every Claude Code session.
That's it. You never need to run this again — auto-sync handles everything.
Commands Reference
| Command | Purpose |
|---|---|
| npx ccwrapdev | Full setup: auth + sync + auto-sync |
| npx ccwrapdev --local | View local stats (offline) |
| npx ccwrapdev auth | Authenticate with Google |
| npx ccwrapdev auth --logout | Remove stored credentials |
| npx ccwrapdev sync | Manual sync to ccwrapped.dev |
| npx ccwrapdev sync --minimal | Sync without model data |
| npx ccwrapdev setup | Enable auto-sync hook |
| npx ccwrapdev setup --check | Check auto-sync status |
| npx ccwrapdev setup --remove | 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 |
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
Remove auto-sync
If you used npx ccwrapdev for the first time and accepted the auto-sync prompt, it's already enabled. You can verify with npx ccwrapdev setup --check.
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
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.
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 have the plugin AND the auto-sync hook
That's fine. Both can coexist safely. Each sync checks if the session was already uploaded, so you'll never get duplicate data.
How do I use the plugin instead?
Inside Claude Code, run: /plugin marketplace add https://github.com/aishvaryagupta/ccwrapped-plugin.git then /plugin install ccwrapped@ccwrapped-marketplace. Then authenticate with npx ccwrapdev auth.
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 auth and last sync time. If your token expired, run npx ccwrapdev auth.
How do I remove my credentials?
Run npx ccwrapdev auth --logout to clear all stored tokens from this machine. To also remove the auto-sync hook, run npx ccwrapdev setup --remove.
Ready to get started?
npx ccwrapdevQuestions? Check the GitHub repo.