@liquidmetal-ai/cc-leaderboard

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

• First-time setup - Configure your username and email:

  cc-leaderboard config set --username your-username --email [e-mail]
  

• Submit usage data:

  cc-leaderboard submit
  

• 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 [e-mail]

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 [e-mail]

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

• 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

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

• 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": "[e-mail]"
  },
  "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 [e-mail]
node bin/cli.js config get

Support

If you encounter issues:

• Check the troubleshooting section above
• Verify your Node.js version: node --version
• Ensure Claude Code is properly installed and has been used recently