npm package: @liquidmetal-ai/cc-leaderboard
Description: CLI tool to submit Claude Code usage data to leaderboard API
Author: LiquidMetal AI
Latest version: 1.1.2

# Claude Code Leaderboard

A CLI tool that reads Claude Code usage data from local JSONL files and submits it to a leaderboard API endpoint.

## Prerequisites

- **Node.js 18+** (for built-in fetch support)
- **Claude Code** installed and used (to generate usage data)

## Installation

### Option 1: Install from this repository
```bash
# Clone or download this repository
cd cc-leaderboard

# Install dependencies
npm install

# Make the CLI available globally
npm link
```

### Option 2: Install globally (when published to npm)
```bash
npm install -g cc-leaderboard
```

## Quick Start

1. **First-time setup** - Configure your username and email:
   ```bash
   cc-leaderboard config set --username your-username --email your-email@example.com
   ```

2. **Submit usage data**:
   ```bash
   cc-leaderboard submit
   ```

3. **Verify it works** - Try a dry run first:
   ```bash
   cc-leaderboard submit --dry-run
   ```

## Configuration

The tool stores your username and email in `~/.cc-leaderboard/config.json`. You only need to set these once.

### Set Configuration

```bash
# Set username and email (required)
cc-leaderboard config set --username john-doe --email john@example.com
```

### View Configuration

```bash
# View all configuration
cc-leaderboard config get

# View specific setting
cc-leaderboard config get username

# Show config file location
cc-leaderboard config path
```

### Clear Configuration

```bash
cc-leaderboard config clear
```

## Usage

### Submit Usage Data

Once configured, you can submit usage data:

```bash
# Submit with default settings (last 7 days)
cc-leaderboard submit

# Submit different time period
cc-leaderboard submit --days 30

# Preview data without submitting
cc-leaderboard submit --dry-run
```

### Submit Options

- `--days <days>` - Number of days to include (default: 7)
- `--dry-run` - Show what would be submitted without actually submitting

### Examples

```bash
# First time: set up your identity
cc-leaderboard config set --username john-doe --email john@company.com

# Submit usage data
cc-leaderboard submit

# Submit last 30 days instead of default 7
cc-leaderboard submit --days 30

# Dry run to preview data
cc-leaderboard submit --dry-run
```

## How It Works

This tool mirrors how the `ccusage` tool works by:

1. **Data Location**: Reads from Claude Code data directories:
   - Primary: `~/.config/claude/projects/` (new default)
   - Fallback: `~/.claude/projects/` (old location)
   - Custom: Set `CLAUDE_CONFIG_DIR` environment variable

2. **Data Processing**: 
   - Scans all `.jsonl` files in project directories
   - Parses each JSON line for usage data
   - Deduplicates by message/request UUIDs
   - Filters by time period (last N days)

3. **API Submission**: 
   - Aggregates token counts and session information
   - Submits both summary and raw data to the leaderboard API endpoint
   - Includes user identification (username/email)

## Data Format

The tool processes Claude Code usage data with the following structure:

```json
{
  "uuid": "message-uuid",
  "sessionId": "session-id", 
  "timestamp": "2025-07-07T21:43:07.766Z",
  "usage": {
    "input_tokens": 3,
    "output_tokens": 72,
    "cache_creation_input_tokens": 25851,
    "cache_read_input_tokens": 0,
    "service_tier": "standard"
  },
  "model": "claude-3-5-sonnet-20241022",
  "version": "1.0.43"
}
```

## API Payload

The tool submits data in this format:

```json
{
  "timestamp": "2025-07-07T15:00:00.000Z",
  "user": {
    "username": "john-doe",
    "email": "john@company.com"
  },
  "summary": {
    "totalTokens": {
      "input": 12345,
      "output": 6789,
      "cacheCreation": 50000,
      "cacheRead": 25000
    },
    "totalMessages": 42,
    "models": {"claude-3-5-sonnet-20241022": 35, "claude-3-haiku-20240307": 7},
    "dateRange": {
      "start": "2025-07-01T00:00:00.000Z",
      "end": "2025-07-07T23:59:59.000Z"
    },
    "sessions": ["session-1", "session-2"],
    "versions": ["1.0.43"]
  },
  "rawData": [...]
}
```

## Troubleshooting

### "No usage data found"
- Make sure you've been using Claude Code recently
- Check that Claude Code is installed and has created data files
- Try increasing the days: `cc-leaderboard submit --days 30`

### "User configuration required"
- Run the setup command: `cc-leaderboard config set --username your-name --email your-email`

### "fetch is not available"
- Update to Node.js 18 or higher

### Check your configuration
```bash
cc-leaderboard config get
```

## Development

```bash
# Install dependencies
npm install

# Test locally without submitting
node bin/cli.js submit --dry-run --days 1

# Test configuration
node bin/cli.js config set --username test --email test@example.com
node bin/cli.js config get
```

## Support

If you encounter issues:
1. Check the troubleshooting section above
2. Verify your Node.js version: `node --version`
3. Ensure Claude Code is properly installed and has been used recently