Metadata-Version: 2.4
Name: tokenhoggers
Version: 0.1.0
Summary: Track your AI usage across Claude Code, Cursor, ChatGPT, Gemini, and more
Author: Vikrant Tyagi
License-Expression: MIT
Project-URL: Homepage, https://github.com/AIPeek/token-hoggers
Project-URL: Repository, https://github.com/AIPeek/token-hoggers
Keywords: ai,analytics,leaderboard,claude,cursor,llm
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# Token Hoggers

**Gamified, tool-agnostic AI usage leaderboard.** Track and compete on your AI usage across Claude Code, Cursor, Gemini, ChatGPT, Copilot, and more.

Inspired by [claude_rank](https://github.com/bicro/claude_rank) but tool-agnostic, with an RPG character system built on the **AMI (AI Maturity Index)** framework.

## How It Works

1. **Install the CLI** — `pip install tokenhoggers`
2. **Sign in** — Google OAuth at [tokenhoggers.com](https://web-system42.vercel.app)
3. **Sync** — `tokenhoggers sync` reads your local AI tool stats (counts only, never content)
4. **Compete** — See your rank, level, tier, and RPG stats on the leaderboard

## Privacy-First

We collect **counts and timestamps only**. Never prompt text, code, file paths, or API keys.

| Collected | Never Touched |
|---|---|
| Token counts (in/out) | Prompt/response text |
| Message & session counts | Project/repo names |
| Tool call counts | File paths, code, diffs |
| Model names | API keys, credentials |
| Timestamps | Working directories |

## RPG Character System

Built on the **AMI (AI Maturity Index)** — 4 dimensions that measure how you use AI, not just how much.

```
          MST (Mastery)
             |
   PRC ──────+────── VRS
             |
          END (Endurance)
```

| Stat | Measures |
|---|---|
| **Mastery** | Power-user behavior (tool calls/session, model diversity) |
| **Precision** | Output per effort (efficiency) |
| **Versatility** | Multi-tool range |
| **Endurance** | Consistency (streaks, active days) |

**Tiers:** Bronze → Silver → Gold → Platinum → Diamond

## Supported Tools

| Tool | Data Source | Parser |
|---|---|---|
| Claude Code | `~/.claude/stats-cache.json` | CLI |
| Cursor | `state.vscdb` (SQLite, read-only) | CLI |
| Gemini CLI | `~/.gemini/tmp/*/logs.json` | CLI |
| ChatGPT | Web request counting | Browser Extension |
| Gemini Web | Web request counting | Browser Extension |
| Claude Web | Web request counting | Browser Extension |

## Quick Start

### CLI

```bash
pip install tokenhoggers

# Check what data is available locally
tokenhoggers status

# Sign in at the web app, copy your token, then:
tokenhoggers config --url https://aaxkbwyolbhjgovmcael.supabase.co/functions/v1/sync
tokenhoggers config --token <YOUR_TOKEN>
tokenhoggers sync

# Re-sync all historical data
tokenhoggers sync --force
```

### Desktop App (macOS)

Menu bar app that shows your stats at a glance.

```bash
cd desktop/src-tauri
source ~/.cargo/env
cargo run
```

### Browser Extension

Tracks request counts on ChatGPT, Gemini, and Claude web (never captures content).

```bash
cd extension/icons && python3 generate.py
# Chrome → chrome://extensions → Developer Mode → Load unpacked → select extension/
```

## Architecture

```
collectors/cli/        Python CLI — parses local AI tool stats
web/                   Frontend (vanilla HTML/JS/CSS) — hosted on Vercel
supabase/              Backend — PostgreSQL, Auth, Edge Functions, Realtime
desktop/               Tauri 2.x macOS menu bar app
extension/             Chrome MV3 browser extension
```

## Tech Stack

- **Backend:** Supabase (PostgreSQL + Auth + Edge Functions + Realtime)
- **Frontend:** Vanilla HTML/JS/CSS (Claude Rank-inspired design)
- **CLI:** Python 3.9+
- **Desktop:** Rust / Tauri 2.x
- **Extension:** Chrome MV3

## Contributing

PRs welcome! See [CONTRIBUTING.md](CONTRIBUTING.md).

## License

MIT — see [LICENSE](LICENSE).
