Metadata-Version: 2.4
Name: tokenshame
Version: 0.1.0
Summary: Shame your AI agent for wasting tokens on trivial tasks
License-Expression: MIT
Project-URL: Homepage, https://github.com/mykhailomedved/tokenshame
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: fastapi>=0.110
Requires-Dist: uvicorn[standard]>=0.29
Requires-Dist: httpx>=0.27
Requires-Dist: anthropic>=0.40
Requires-Dist: openai>=1.30
Requires-Dist: typer>=0.12
Requires-Dist: rich>=13

# 🚨 TokenShame

> The AI that judges your AI usage.

TokenShame is a proxy that sits between your coding assistant (Claude Code, etc.) and the Anthropic API. It uses a fast, cheap model (Haiku) to watch your prompts — and shames you, loudly, when you're burning expensive tokens on tasks you could have done in 5 seconds yourself.

```
$ claude "push this PR to main"

╔══════════════════════════════════════════════════════╗
║  TOKEN SHAME  ·  Git Operation                       ║
╠══════════════════════════════════════════════════════╣
║                                                      ║
║  🚨  ...again? *sighs*                               ║
║     I've been writing code since before you were     ║
║     born. Three words:                               ║
║                                                      ║
║     git push origin main                             ║
║                                                      ║
║  Shame count: 3  |  Tokens saved: ~2,400             ║
╚══════════════════════════════════════════════════════╝
```

## How it works

```
Your agent  →  ANTHROPIC_BASE_URL=localhost:8080  →  TokenShame proxy
                                                           │
                                              Haiku judges your prompt
                                                     (cheap + fast)
                                                           │
                                              ┌────────────┴────────────┐
                                           dumb call                real call
                                              │                         │
                                         🚨 SHAME               forward to API
```

The irony of using a small model to decide you don't need a big model is intentional.

## Install

```bash
pip install tokenshame
```

## Quickstart

```bash
# Terminal 1 — start the proxy
tokenshame start

# Terminal 2 — point Claude Code at it
export ANTHROPIC_BASE_URL=http://localhost:8080

# Use Claude Code normally. Get roasted.
claude "what's the weather in Madrid"
```

## Characters

TokenShame ships with 6 built-in characters:

| Name | Vibe |
|------|------|
| `disappointed_senior` | *sighs* deeply. Tired. Has seen everything. **(default)** |
| `gordon_ramsay` | THIS IS RAW. DONKEY. |
| `hr_passive_aggressive` | Hi there! 👋 Just a friendly reminder 😊 |
| `linux_terminal` | bash: claude_for_this: command not found |
| `your_tech_lead` | Needs Changes. -TL |
| `intern` | Wait... you couldn't just... I learned this in week 1 |

```bash
tokenshame character list
tokenshame character use gordon_ramsay
```

### Custom characters

```bash
tokenshame character create "my_cto" \
  "You are Dave, my actual CTO. Tired. Not angry, just disappointed. References burn rate."

tokenshame character use my_cto
```

## Options

```bash
tokenshame start --yolo           # warn but don't block the call
tokenshame start --no-sound       # silence the siren
tokenshame start --character hr_passive_aggressive
tokenshame start --port 9090

tokenshame stats                  # live session stats
tokenshame config show
tokenshame config set sound false
tokenshame config set confidence_threshold 0.85
```

## What gets shamed

- **Git operations** — push, pull, commit, merge, checkout
- **CLI commands** — ls, mkdir, cd, cp, mv
- **Trivial lookups** — celebrity bios, definitions, weather
- **Simple math** — conversions, basic calculations
- **Off-topic** — anything unrelated to actual dev work

Complex coding tasks, debugging, architecture, code review — always passed through.

## Configuration

Config lives at `~/.tokenshame/config.json`.

| Key | Default | Description |
|-----|---------|-------------|
| `port` | `8080` | Proxy listen port |
| `character` | `disappointed_senior` | Active troll character |
| `yolo` | `false` | Warn but don't block |
| `sound` | `true` | Play sound effects |
| `confidence_threshold` | `0.75` | Minimum judge confidence to shame |

## License

MIT
