ccusage-collector
Advanced tools
A command-line tool for collecting Claude Code usage statistics and syncing them to your self-hosted My Claude Code Usage Dashboard.
This package automatically collects your local Claude Code usage data and syncs it to your dashboard, giving you insights into your AI-assisted development workflow.
npm install -g ccusage-collector
npm install -g pm2
ccusage-collector config
This will prompt you for:
pm2 start ccusage-collector -- start
ccusage-collector status
pm2 status
| Command | Description |
|---|---|
ccusage-collector config | Interactive configuration wizard |
ccusage-collector start | Start scheduled sync (requires configuration) |
ccusage-collector sync | Run single sync operation |
ccusage-collector sync --dry-run | Test data collection without syncing |
ccusage-collector status | Check configuration status |
ccusage-collector test | Test configuration and connection |
ccusage-collector --help | Show help |
Configuration is stored in ~/.ccusage-collector/config.json with user-only file permissions.
ccusage-collector config
Sample Configuration Session:
🔧 ccusage-collector Configuration Wizard
=========================================
? Enter your API Key: ********** (hidden input)
? Enter your dashboard URL (domain only): https://myccusage.example.com
? Enter a custom device name (optional, leave empty to use system name): My MacBook Pro
? Select sync frequency: Every 4 hours
🧪 Testing configuration...
✅ Configuration test passed!
✅ Configuration saved successfully!
💡 Start with PM2:
pm2 start ccusage-collector -- start
# 1. Configure credentials
ccusage-collector config
# 2. Test the configuration
ccusage-collector test
# 3. Start background sync
pm2 start ccusage-collector -- start
# 4. Check status
ccusage-collector status
pm2 status
# View sync logs
pm2 logs ccusage-collector
# Restart sync process
pm2 restart ccusage-collector
# Stop sync process
pm2 stop ccusage-collector
# Run one-time sync
ccusage-collector sync
# Test without syncing
ccusage-collector sync --dry-run
First, deploy your own instance of My Claude Code Usage Dashboard:
Set the API_KEY environment variable in your dashboard deployment:
API_KEY=your-secret-api-key-here
# Install globally
npm install -g ccusage-collector
npm install -g pm2
# Configure
ccusage-collector config
# Start background sync
pm2 start ccusage-collector -- start
The collector:
npx ccusage daily --json to gather usage statisticsThe collector syncs:
# Start background sync
pm2 start ccusage-collector -- start
# Check status
pm2 list # Show all processes
pm2 show ccusage-collector # Show detailed info
pm2 logs ccusage-collector # View logs
pm2 monit # Real-time monitoring
# Control process
pm2 stop ccusage-collector # Stop process
pm2 restart ccusage-collector # Restart process
pm2 delete ccusage-collector # Remove process
# Auto-start on boot
pm2 startup # Generate startup script
pm2 save # Save current process list
❌ Configuration not found
# Run interactive configuration
ccusage-collector config
❌ "ccusage command not found"
npx ccusage --help to verify installation❌ "Authentication failed"
ccusage-collector config to update credentials❌ "Connection refused"
# Check configuration
ccusage-collector status
# Test configuration and connection
ccusage-collector test
# Test data collection only
ccusage-collector sync --dry-run
# View detailed logs
pm2 logs ccusage-collector
git checkout -b feature/amazing-feature)git commit -m 'Add amazing feature')git push origin feature/amazing-feature)# Clone the main repository
git clone https://github.com/i-richardwang/MyCCusage.git
cd MyCCusage/packages/ccusage-collector
# Install dependencies
pnpm install
# Build the package
pnpm build
# Test CLI locally
pnpm cli --help
pnpm cli config
pnpm cli status
# Run type checking
pnpm typecheck
# Run linting
pnpm lint
MIT License - see LICENSE file for details.
FAQs
Local collector for Claude Code usage statistics
The npm package ccusage-collector receives a total of 11 weekly downloads. As such, ccusage-collector popularity was classified as not popular.
We found that ccusage-collector demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
OpenAI rotated macOS signing certificates after a malicious Axios package reached its CI pipeline in a broader software supply chain attack.
Security News
Open source is under attack because of how much value it creates. It has been the foundation of every major software innovation for the last three decades. This is not the time to walk away from it.
Security News
Socket CEO Feross Aboukhadijeh breaks down how North Korea hijacked Axios and what it means for the future of software supply chain security.