Claude Code Usage Leaderboard

A beautiful, secure web application and CLI tool for tracking and comparing Claude Code usage across your team.

Features

• GitHub OAuth Authentication with email domain verification
• Beautiful Web Dashboard with real-time leaderboard updates
• Multiple Time Periods: Daily, Weekly, Monthly, and All-Time views
• Simple CLI Tool for easy usage submission
• Secure API Key Management with encrypted storage
• Auto-Submit Capability for hands-free tracking
• Rate Limiting and security best practices
• OpenShift/Kubernetes Ready with easy deployment

Quick Start

For Users

1. Install the CLI

npx cc-leaderboard login

This will open your browser for GitHub authentication.

2. Submit Your Usage

npx cc-leaderboard submit

The CLI automatically reads your Claude Code usage data and submits it to the leaderboard.

3. (Optional) Enable Auto-Submit

npx cc-leaderboard config --auto-submit daily

Then set up a cron job:

# Submit every day at 6 PM
0 18 * * * npx cc-leaderboard submit

For Administrators

Setting up GitHub OAuth

1. Create a GitHub OAuth App

   • Go to https://github.com/settings/developers
   • Click "New OAuth App"
   • Fill in the details:
     • Application name: Claude Code Leaderboard (or your preferred name)
     • Homepage URL:
       • Development: http://localhost:3000
       • Production: https://your-domain.com
     • Authorization callback URL:
       • Development: http://localhost:3000/api/auth/github
       • Production: https://your-domain.com/api/auth/github
   • Click "Register application"
   • Copy the Client ID and generate a Client Secret

2. Configure Environment Variables

cd web
cp .env.example .env

Edit .env and add your GitHub OAuth credentials:

# GitHub OAuth Configuration
NUXT_OAUTH_GITHUB_CLIENT_ID=your_github_client_id
NUXT_OAUTH_GITHUB_CLIENT_SECRET=your_github_client_secret

# JWT Secret for API key generation (change this to a random string)
NUXT_JWT_SECRET=your-secret-key-change-in-production

# Public Configuration
NUXT_PUBLIC_APP_URL=http://localhost:3000
# Optional: Restrict to specific email domain (e.g., @company.com)
# Leave empty to allow all GitHub users
NUXT_PUBLIC_REQUIRED_EMAIL_DOMAIN=@example.com

# Database path (optional)
DATABASE_PATH=./data/leaderboard.db

3. Start the Application

npm install
npm run dev

The app will be available at http://localhost:3000

For production deployment, see DEPLOYMENT.md for detailed instructions.

Architecture

cc-leaderboard/
├── cli/                    # CLI tool (TypeScript)
│   ├── src/
│   │   ├── commands/      # login, submit, config, status
│   │   ├── api-client.ts
│   │   └── config.ts
│   └── package.json
├── web/                   # Nuxt 4 web app
│   ├── app/
│   │   ├── components/   # Vue components
│   │   ├── pages/        # Leaderboard, settings
│   │   └── server/       # API routes, database
│   ├── nuxt.config.ts
│   └── package.json
└── deployment/           # Kubernetes manifests

Tech Stack

Web App

• Nuxt 4 - Vue framework with SSR
• Vue 3 - UI framework
• ShadCN Vue - Beautiful UI components
• Tailwind CSS - Utility-first CSS
• TypeScript - Type safety
• Drizzle ORM - Database ORM
• SQLite - Lightweight database
• Pino - Fast structured logging
• GitHub OAuth - Authentication via nuxt-auth-utils

CLI

• Commander.js - CLI framework
• Chalk - Colored terminal output
• Ora - Loading spinners
• Keytar - Secure credential storage

API Endpoints

Authentication

• GET /api/auth/github - GitHub OAuth flow

User

• GET /api/me - Get current user info

Submissions

• POST /api/submit - Submit usage data

Leaderboard

• GET /api/leaderboard/:period - Get leaderboard (daily, weekly, monthly, all-time)

Security Features

• GitHub OAuth with email domain verification
• JWT-based API keys for CLI authentication
• Rate limiting on all API endpoints
• Input validation with Zod schemas
• HTTPS-only in production
• Secure credential storage with OS keychain
• SQL injection protection with Drizzle ORM

Development

Prerequisites

• Node.js 18+
• npm or pnpm

Setup

# Install dependencies
npm install

# Set up environment variables
cp web/.env.example web/.env
# Edit web/.env with your GitHub OAuth credentials

# Start development server
npm run dev:web

# In another terminal, run CLI in dev mode
npm run dev:cli

Building

# Build web app
npm run build:web

# Build CLI
npm run build:cli

# Build both
npm run build

Publishing the CLI to npm

The CLI package uses semantic-release for automated versioning and publishing based on conventional commits.

Setting up Automated Releases

1. Create an npm access token

   • Go to https://www.npmjs.com/settings/YOUR_USERNAME/tokens
   • Click "Generate New Token" → "Classic Token"
   • Select "Automation" type
   • Copy the token

2. Add the token to GitHub Secrets

   • Go to your repository settings → Secrets and variables → Actions
   • Click "New repository secret"
   • Name: NPM_TOKEN
   • Value: Paste your npm token
   • Click "Add secret"

How it works

Every push to the main branch triggers semantic-release, which:

1. Analyzes commits since the last release using conventional commit format:

   • feat: → Minor version bump (e.g., 1.0.0 → 1.1.0)
   • fix: → Patch version bump (e.g., 1.0.0 → 1.0.1)
   • BREAKING CHANGE: → Major version bump (e.g., 1.0.0 → 2.0.0)
   • chore:, docs:, refactor: → No release

2. Automatically:

   • Determines the next version number
   • Generates CHANGELOG.md
   • Updates package.json
   • Creates a git tag
   • Publishes to npm
   • Creates a GitHub release

Publishing a new version

Simply push commits using conventional commit format:

git commit -m "feat: add new cool feature"
git push origin main

Semantic-release will handle the rest! Users can then use npx cc-leaderboard without installing anything.

License

MIT

Contributing

See CONTRIBUTING.md for development guidelines.

Support

For issues and feature requests, please open an issue on GitHub.