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

# 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)

npm install -g cc-leaderboard

Quick Start

1. First-time setup - Configure your username and email:

   cc-leaderboard config set --username your-username --email [email protected]

2. Submit usage data:

   cc-leaderboard submit

3. Verify it works - Try a dry run first:

   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

# Set username and email (required)
cc-leaderboard config set --username john-doe --email [email protected]

View Configuration

# 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

cc-leaderboard config clear

Usage

Submit Usage Data

Once configured, you can submit usage data:

# 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

# First time: set up your identity
cc-leaderboard config set --username john-doe --email [email protected]

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

{
  "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:

{
  "timestamp": "2025-07-07T15:00:00.000Z",
  "user": {
    "username": "john-doe",
    "email": "[email protected]"
  },
  "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

cc-leaderboard config get

Development

# 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 [email protected]
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