# 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

```bash
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

```bash
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.