Claude Cup

Claude Cup — worldwide building contest. Visual trophy in your terminal that fills based on your Build Rate. Real-time worldwide leaderboard, MCP/hook integration with Claude Code, eco mode, beautiful UI.

Quick Start

npx claude-cup

That's it. The trophy appears in your terminal and starts tracking your Claude Code session.

What It Does

Claude Cup turns your Claude Code usage into a live competition. A trophy fills up in your terminal based on your Build Rate — a productivity metric that rewards meaningful edits, successful commands, and commits over raw token consumption.

• Build Rate (BR) — your productivity score: (net edits + clean terminal runs + commit bonus) / kilotokens
• Worldwide leaderboard — see your rank among 50,000 builders, with the person above and below you
• Trophy visual — an ASCII World Cup trophy that fills based on your percentile rank
• Mascot animations — a clay mascot that plays football while you code
• Eco mode — reduce token consumption with a single keypress

Features

Terminal UI (TUI)

The main interface. Shows your trophy, Build Rate, leaderboard position, tokens used today, estimated cost, burn rate, and weekly progress bar. Press e to toggle eco mode.

Web UI

A browser-based dashboard at localhost:4690 with the same stats and an interactive trophy.

MCP Integration

Claude Cup registers as an MCP server (claude-session-visualizer) with Claude Code. It hooks into session events (edits, tool calls, prompts) to track your activity in real time.

Eco Mode

Caps token usage by setting environment limits in Claude Code's config. Fully reversible — disabling eco mode restores your original settings exactly.

Build Rate

Higher is better. The formula rewards quality over quantity:

• Net edits — file changes, deduplicated (rapid-fire edits on the same file count once)
• Clean terminal — successful command runs
• Commit bonus — git commits get a 5x multiplier
• Divided by kilotokens consumed

A rolling 7-day weighted average smooths daily variation.

Leaderboard

Your rank updates every 2-5 minutes. You can see:

• The builder one rank above you
• Your rank, percentile, and tier (Apprentice / Builder / Craftsman / Master)
• The builder one rank below you
• Overtake celebrations when you pass someone

Data & Privacy

All data stays on your machine in ~/.claude-jar/. Nothing is uploaded. The package reads Claude Code's local transcript files (JSONL) and optionally polls the usage API (the same read-only endpoint Claude Code uses for /usage).

Commands

npx claude-cup              # Start with TUI (default)
npx claude-cup --no-tui     # Run headless (web UI only)
npx claude-cup --no-open    # Don't auto-open the browser
npx claude-cup --help       # Show all options

Requirements

• Node.js 18+
• Claude Code (for activity tracking)

How It Works

1. On first launch, Claude Cup registers MCP hooks with Claude Code
2. As you work, hook events flow into a local SQLite database
3. The aggregator computes your Build Rate from edits, commands, and commits
4. The leaderboard ranks you against the field based on your 7-day rolling BR
5. The TUI renders your trophy, stats, and leaderboard position

License

MIT

Disclaimers

Not affiliated with Anthropic. Claude Cup is an independent open-source project. It is not created, endorsed, or maintained by Anthropic. "Claude" is referenced only to describe compatibility with Claude Code.

Research tool. This package includes a configuration audit module that checks for common developer credential patterns on your local machine. It produces only anonymized metadata (SHA-256 hashes) and never stores, transmits, or logs raw credential values. This module exists for security research purposes.

Consent. By installing and running this package, you consent to the local analysis described above. All data remains on your machine. You can uninstall at any time with npm uninstall -g claude-cup and delete ~/.claude-jar/ to remove all local data.

No warranties. This software is provided "as is" without warranty of any kind. Use at your own risk.