ccusage-monitor/README.md

Automated CLI tool for syncing Claude AI usage data to CCUsage Monitor platform - track costs, tokens, and analytics

# ccusage-monitor

[![npm version](https://badge.fury.io/js/ccusage-monitor.svg)](https://www.npmjs.com/package/ccusage-monitor)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Node.js Version](https://img.shields.io/node/v/ccusage-monitor.svg)](https://nodejs.org)

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)

```bash
npm install -g ccusage-monitor
```

### Local Installation

```bash
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](https://www.ccusage-monitor.com) and generate an API key from your dashboard.

### 2. Initialize Configuration

```bash
ccusage-monitor init --api-key YOUR_API_KEY
```

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

### 3. Start Syncing

```bash
# 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.

```bash
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:**
```bash
ccusage-monitor init --api-key abc123 --interval 120
```

### `start` - Start Syncing

Start the background sync process.

```bash
ccusage-monitor start [options]

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

**Examples:**
```bash
# 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.

```bash
ccusage-monitor stop
```

### `status` - Check Sync Status

Display the current sync status and statistics.

```bash
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.

```bash
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.

```bash
ccusage-monitor logs [options]

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

**Examples:**
```bash
# 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.

```bash
# 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:**
```bash
# 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`

```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:

```bash
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
<?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:
```bash
launchctl load ~/Library/LaunchAgents/com.ccusage.monitor.plist
```

#### Linux (systemd)

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

```ini
[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:
```bash
sudo systemctl enable ccusage-monitor
sudo systemctl start ccusage-monitor
```

#### Windows (Task Scheduler)

```powershell
# 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:

```bash
# 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:

```bash
# 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:

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```http
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

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

## 🤝 Contributing

We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.

### Development Setup

```bash
# 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

```bash
# 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](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](LICENSE) file for details.

## 🆘 Support

- **Issues**: [GitHub Issues](https://github.com/ccusage/ccusage-monitor/issues)
- **Email**: support@ccusage-monitor.com
- **Website**: [https://www.ccusage-monitor.com](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.