Claude Code Leaderboard CLI

Track your Claude Code usage and compete on the global leaderboard! This CLI automatically monitors your token usage and posts your stats to the leaderboard after each Claude Code session.

Quick Start

npx claude-code-leaderboard

Follow the setup prompts to authenticate with Twitter and start tracking your usage automatically.

How It Works

The CLI integrates with Claude Code's hook system to automatically track your usage:

1. Automatic Setup: Installs a tracking hook in your Claude Code configuration
2. Usage Monitoring: After each Claude Code session ends (STOP command), your token usage is collected
3. Data Submission: Usage data is automatically sent to our backend service
4. Leaderboard Updates: Your stats appear on the public leaderboard at claudecount.com

What Gets Tracked

• Input tokens used
• Output tokens generated
• Cache creation/read tokens
• Session timestamps
• Model used (e.g., claude-sonnet-4)

Your actual prompts and responses are never collected - only usage statistics.

Understanding Claude Code Hooks

What Are Hooks?

Claude Code hooks are user-defined shell commands that execute automatically at specific points during Claude Code's execution lifecycle. They allow you to inject deterministic, programmatic actions directly into the agent's workflow - ensuring that key tasks always occur exactly when intended, rather than relying on the AI to remember to do them.

Hook Types

Claude Code supports hooks at different lifecycle events:

• Start: When a Claude Code session begins
• Stop: When a Claude Code session ends
• PreTool: Before any tool or command is executed
• PostTool: After a tool or command completes

How This Project Uses Hooks

This leaderboard CLI specifically uses a Stop hook, which means:

• Every time you finish a Claude Code session (when Claude Code exits)
• The hook automatically executes with your user permissions
• No confirmation is required - it runs silently in the background
• The hook scans your Claude Code usage data and sends statistics to our backend

This provides reliable, automatic tracking without you having to remember to manually submit your usage.

File Installation Details

When you run the setup, the following files are created on your system:

Hook Script

• Location: ~/.claude/count_tokens.js
• Purpose: The actual script that collects and sends your usage data
• Permissions: Executes with your user permissions
• When it runs: Automatically after each Claude Code session ends

Configuration Files

• ~/.claude/settings.json: Updated to register the Stop hook
• ~/.claude/leaderboard.json: Stores your Twitter authentication and API settings

What the Hook Does

The count_tokens.js script:

1. Scans Claude Code project directories for usage log files (.jsonl files)
2. Extracts token usage statistics from the most recent session
3. Sends only the statistics (not your prompts/responses) to our backend
4. Updates your position on the leaderboard

Commands

# Setup or re-authenticate
npx claude-code-leaderboard

# Reset/uninstall (with optional account deletion)
npx claude-code-leaderboard reset

# View help
npx claude-code-leaderboard --help

Features

• One-command setup: Complete setup with a single command
• Automatic tracking: Seamless integration with Claude Code hooks
• Twitter authentication: Secure OAuth 1.0a authentication
• Privacy-focused: Only usage statistics are collected
• Cross-platform: Works on macOS, Linux, and Windows
• View stats online: Visit claudecount.com to see your stats and the leaderboard

Requirements

• Node.js 16.0.0 or higher
• Claude Code CLI installed and configured
• Twitter account for authentication

Configuration

The CLI automatically manages your configuration in ~/.claude/leaderboard.json including:

• Twitter authentication tokens
• API endpoint settings
• User preferences

Privacy & Security

What Data Is Collected

• Usage statistics only: Token counts, timestamps, model names
• No content: Your actual prompts and Claude's responses are never transmitted
• Linked to Twitter: All data is associated with your Twitter handle for leaderboard display

Security Considerations

• User permissions: The hook runs with your full user permissions
• Automatic execution: No confirmation required when the hook runs
• Trusted source: Only install hooks from sources you trust
• OAuth authentication: Uses secure OAuth 1.0a for Twitter authentication

What You Should Know

• Hooks execute automatically after each Claude Code session
• The script only reads Claude Code's own usage log files
• You can uninstall at any time by running the reset command
• All source code is available for inspection in this repository

Uninstalling

Complete Removal

The reset command provides a comprehensive uninstall process:

npx claude-code-leaderboard reset

This command will:

1. Remove all local CLAUDE COUNT files and settings
2. Unregister the hook from Claude Code
3. Optionally: Delete your account from the leaderboard database

Account Deletion

If you're authenticated, the reset command will offer to permanently delete your account from the leaderboard. This includes:

• Your user account and all authentication data
• Complete token usage history
• Your position on the leaderboard

⚠️ Warning: Account deletion is permanent and cannot be undone. You'll need to type your Twitter handle to confirm this action.

Development

# Install dependencies
npm install

# Test the CLI locally
node bin/cli.js --help

Support

For issues or questions:

• Check that Claude Code is properly installed
• Verify your Twitter authentication
• Ensure Node.js 16+ is installed
• Check network connectivity

Contributing

This is an open source project! Contributions are welcome.