claude-cup

Claude Cup

Claude Cup — worldwide building contest. Visual trophy in your terminal powered by your Value/Token Ratio. 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. Your Value/Token Ratio (V/T) measures meaningful building progress relative to token usage, rewarding useful work instead of raw token consumption.

• Value/Token Ratio (V/T) — your efficiency score: weighted building value × quality multiplier / kilotokens
• Worldwide leaderboard — see your rank among builders all over the world
• 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, Value/Token Ratio, 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.

Value/Token Ratio

Higher is better. V/T compares weighted building value with the tokens used:

• Net edits: 1.4 value each, with rapid edits on the same file deduplicated
• Build and test runs: 2.2 value each
• Git progress: 1.8 value each
• Other successful terminal runs: 0.7 value each
• Agent progress: 0.9 value each
• Research: 0.12 per read and 0.2 per web action, capped at 2.5
• Quality multiplier: +3% per build/test and +4% per git-progress event, capped at +35%
• The final value is divided by kilotokens used, with a minimum denominator of 1

A rolling 7-day weighted average smooths daily variation, with recent days weighted more heavily.

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 Value/Token Ratio from weighted building activity and token usage
4. The leaderboard ranks you against the field based on your rolling 7-day V/T
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.