ccusage-monitor

A powerful CLI tool for synchronizing Claude AI usage data from local JSONL files to the CCUsage Monitor platform. Track your Claude Code usage, costs, and token consumption with automated background syncing.

🚀 Features

• Automatic Background Sync: Continuously monitors and syncs your Claude usage data
• Smart Duplicate Detection: Prevents duplicate data uploads using intelligent hashing
• Incremental Updates: Only syncs new data since last sync
• Secure API Communication: Uses API key authentication for secure data transfer
• Cross-Platform Support: Works on macOS, Linux, and Windows
• Minimal Resource Usage: Lightweight background process (~30MB RAM)
• Configurable Sync Intervals: Customize how often data syncs (default: 60 seconds)
• Progress Tracking: Real-time sync status and statistics
• Offline Support: Queues data when offline and syncs when connection is restored

📦 Installation

Global Installation (Recommended)

npm install -g ccusage-monitor

Local Installation

npm install ccusage-monitor

Requirements

• Node.js 14.0.0 or higher
• npm 6.0.0 or higher
• Claude Code installed with usage data

🔧 Quick Start

1. Get Your API Key

First, create an account at CCUsage Monitor and generate an API key from your dashboard.

2. Initialize Configuration

ccusage-monitor init --api-key YOUR_API_KEY

This creates a configuration file at ~/.ccusage-monitor/config.json with your settings.

3. Start Syncing

# Start background sync (daemon mode)
ccusage-monitor start

# Or run in foreground for testing
ccusage-monitor start --foreground

That's it! Your Claude usage data will now sync automatically every 60 seconds.

📖 Commands

init - Initialize Configuration

Initialize ccusage-monitor with your API key and preferences.

ccusage-monitor init [options]

Options:
  --api-key <key>      Your CCUsage API key (required)
  --server <url>       API server URL (default: https://api.ccusage-monitor.com)
  --interval <seconds> Sync interval in seconds (default: 60)
  --data-dir <path>    Claude data directory (auto-detected by default)

Example:

ccusage-monitor init --api-key abc123 --interval 120

start - Start Syncing

Start the background sync process.

ccusage-monitor start [options]

Options:
  --foreground    Run in foreground instead of background
  --verbose       Enable verbose logging
  --once          Run sync once and exit

Examples:

# Start in background (default)
ccusage-monitor start

# Run in foreground with verbose output
ccusage-monitor start --foreground --verbose

# Run once and exit
ccusage-monitor start --once

stop - Stop Background Sync

Stop the running background sync process.

ccusage-monitor stop

status - Check Sync Status

Display the current sync status and statistics.

ccusage-monitor status

Output example:

Status: Running
PID: 12345
Last sync: 2 minutes ago
Total syncs: 1,234
Sessions synced: 456
Messages synced: 12,345
Next sync: in 58 seconds

sync - Manual Sync

Perform a one-time manual sync.

ccusage-monitor sync [options]

Options:
  --file <path>    Sync specific file only
  --force          Force sync even if no changes detected

logs - View Sync Logs

View and follow sync logs.

ccusage-monitor logs [options]

Options:
  --follow, -f     Follow log output
  --lines <n>      Number of lines to show (default: 50)
  --clear          Clear log file

Examples:

# View last 50 lines
ccusage-monitor logs

# Follow logs in real-time
ccusage-monitor logs --follow

# Show last 100 lines
ccusage-monitor logs --lines 100

config - Manage Configuration

View or modify configuration settings.

# View current configuration
ccusage-monitor config

# View specific setting
ccusage-monitor config get <key>

# Update setting
ccusage-monitor config set <key> <value>

# Reset to defaults
ccusage-monitor config reset

Examples:

# View all settings
ccusage-monitor config

# Update sync interval to 5 minutes
ccusage-monitor config set interval 300

# Change API server
ccusage-monitor config set server https://api.custom-server.com

⚙️ Configuration

Configuration File

Configuration is stored at ~/.ccusage-monitor/config.json

{
  "apiKey": "your-api-key-here",
  "apiUrl": "https://api.ccusage-monitor.com",
  "syncInterval": 60,
  "dataDir": "~/.config/claude/projects",
  "verbose": false,
  "lastSyncTime": "2024-01-01T00:00:00.000Z",
  "syncStats": {
    "totalSyncs": 1234,
    "sessionsSync": 456,
    "messagesSync": 12345,
    "lastError": null
  }
}

Environment Variables

You can also configure ccusage-monitor using environment variables:

export CCUSAGE_API_KEY=your-api-key
export CCUSAGE_API_URL=https://api.ccusage-monitor.com
export CCUSAGE_SYNC_INTERVAL=60
export CCUSAGE_DATA_DIR=/path/to/claude/data
export CCUSAGE_VERBOSE=true

Environment variables take precedence over config file settings.

Data Directory Detection

ccusage-monitor automatically detects Claude data directories:

macOS:

• ~/Library/Application Support/Claude/claude_desktop/projects
• ~/.config/claude/projects
• ~/.claude/projects

Linux:

• ~/.config/claude/projects
• ~/.claude/projects
• ~/.local/share/claude/projects

Windows:

• %APPDATA%\Claude\projects
• %LOCALAPPDATA%\Claude\projects

🔍 How It Works

Data Flow

1. File Discovery: Scans Claude data directories for JSONL files
2. Session Parsing: Extracts conversation sessions and messages
3. Cost Calculation: Computes token usage and costs per model
4. Deduplication: Uses SHA-256 hashing to prevent duplicate uploads
5. Batch Upload: Groups data for efficient API calls
6. Progress Tracking: Updates sync state and statistics

File Patterns

ccusage-monitor monitors these file patterns:

• conversations_*.jsonl
• claude_conversations_*.jsonl
• **/projects/**/conversations.jsonl
• usage_*.jsonl

Data Privacy & Security

• Local Processing: All parsing happens locally on your machine
• Secure Transfer: HTTPS/TLS encryption for all API communication
• Minimal Data: Only usage metadata is synced (no message content)
• User Control: Stop syncing anytime, delete data from dashboard
• API Key Security: Keys are stored locally, never in code or logs

Performance

• Memory Usage: ~30MB RAM (typical)
• CPU Usage: <1% when idle, 2-5% during sync
• Network: Minimal bandwidth usage (compressed JSON)
• File Handling: Efficient streaming for large files

🛠️ Advanced Usage

Running as a System Service

macOS (launchd)

Create a plist file at ~/Library/LaunchAgents/com.ccusage.monitor.plist:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>com.ccusage.monitor</string>
    <key>ProgramArguments</key>
    <array>
        <string>/usr/local/bin/node</string>
        <string>/usr/local/bin/ccusage-monitor</string>
        <string>start</string>
        <string>--foreground</string>
    </array>
    <key>RunAtLoad</key>
    <true/>
    <key>KeepAlive</key>
    <true/>
</dict>
</plist>

Then load it:

launchctl load ~/Library/LaunchAgents/com.ccusage.monitor.plist

Linux (systemd)

Create a service file at /etc/systemd/system/ccusage-monitor.service:

[Unit]
Description=CCUsage Sync Service
After=network.target

[Service]
Type=simple
User=your-username
ExecStart=/usr/bin/ccusage-monitor start --foreground
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target

Enable and start:

sudo systemctl enable ccusage-monitor
sudo systemctl start ccusage-monitor

Windows (Task Scheduler)

# Create scheduled task
schtasks /create /tn "CCUsage Sync" /tr "ccusage-monitor start --foreground" /sc onstart /ru SYSTEM

Custom Data Directory

If your Claude data is in a non-standard location:

# Set custom directory during init
ccusage-monitor init --api-key YOUR_KEY --data-dir /custom/path

# Or update existing config
ccusage-monitor config set dataDir /custom/path

Proxy Configuration

For environments requiring proxy:

# HTTP proxy
export HTTP_PROXY=http://proxy.example.com:8080
export HTTPS_PROXY=http://proxy.example.com:8080

# With authentication
export HTTP_PROXY=http://user:pass@proxy.example.com:8080

Debug Mode

For troubleshooting issues:

# Maximum verbosity
DEBUG=* ccusage-monitor start --foreground --verbose

# Write debug log
DEBUG=* ccusage-monitor start --foreground 2> debug.log

🐛 Troubleshooting

Common Issues

Cannot find Claude data directory

# Manually specify the directory
ccusage-monitor init --data-dir "/path/to/claude/data"

# Verify directory contains JSONL files
ls -la /path/to/claude/data/*.jsonl

Authentication failed

# Verify API key
ccusage-monitor config get apiKey

# Update API key
ccusage-monitor config set apiKey YOUR_NEW_KEY

# Test connection
ccusage-monitor sync --once

Sync not starting

# Check if already running
ccusage-monitor status

# Check for PID file
ls -la ~/.ccusage-monitor/sync.pid

# Force stop and restart
ccusage-monitor stop
rm ~/.ccusage-monitor/sync.pid
ccusage-monitor start --foreground --verbose

High CPU/Memory usage

# Increase sync interval (5 minutes)
ccusage-monitor config set interval 300

# Check for large files
find ~/.config/claude -name "*.jsonl" -size +100M

# Run garbage collection
ccusage-monitor sync --cleanup

Network errors

# Test API connectivity
curl https://api.ccusage-monitor.com/health

# Check DNS
nslookup api.ccusage-monitor.com

# Try with different DNS
echo "nameserver 8.8.8.8" | sudo tee /etc/resolv.conf

Log Files

Logs are stored at:

• macOS/Linux: ~/.ccusage-monitor/sync.log
• Windows: %APPDATA%\ccusage-monitor\sync.log

Log rotation happens automatically at 10MB.

Getting Help

# General help
ccusage-monitor --help

# Command-specific help
ccusage-monitor init --help
ccusage-monitor start --help

# Version info
ccusage-monitor --version

📊 API Reference

Sync Endpoint

POST /api/sync/upload
Content-Type: application/json
X-API-Key: your-api-key

{
  "sessions": [...],
  "metadata": {
    "version": "1.0.0",
    "timestamp": "2024-01-01T00:00:00Z"
  }
}

Response Format

{
  "success": true,
  "synced": {
    "sessions": 10,
    "messages": 245,
    "newSessions": 2,
    "updatedSessions": 8
  },
  "errors": []
}

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

Development Setup

# Clone the repository
git clone https://github.com/ccusage/ccusage-monitor.git
cd ccusage-monitor

# Install dependencies
npm install

# Run tests
npm test

# Run in development mode
npm run dev

# Build for production
npm run build

# Lint code
npm run lint

Testing

# Run all tests
npm test

# Run with coverage
npm run test:coverage

# Run specific test
npm test -- --grep "sync"

# Run in watch mode
npm run test:watch

📝 Changelog

See CHANGELOG.md for a full list of changes.

Recent Updates

• v1.0.0 - Initial release with core sync functionality
• v1.1.0 - Added background daemon mode
• v1.2.0 - Improved duplicate detection
• v1.3.0 - Added Windows support

📄 License

MIT License - see LICENSE file for details.

🆘 Support

• Issues: GitHub Issues
• Email: support@ccusage-monitor.com
• Website: https://www.ccusage-monitor.com

🙏 Acknowledgments

Built with ❤️ by the CCUsage team. Special thanks to all contributors and users who help make this tool better.

Note: This tool is not affiliated with Anthropic or Claude AI. It's an independent project for usage monitoring and analytics.