<img src="assets/logo-64.png" align="left" width="52" height="52" alt="">

# thirsty-tokens

How much data-center water has your Claude Code habit evaporated? This reads your
own local transcripts (`~/.claude/projects`) and estimates it, with real-world
comparisons. Nothing leaves your machine.

Four ways to use it: a **CLI**, a **live desktop widget**, an **MCP server**, and a
**browser calculator** (no install).

- **Live web calculator:** https://evanwang810.github.io/thirsty-tokens/
- **Download the desktop app (Windows .exe):** https://github.com/evanwang810/thirsty-tokens/releases/latest

## Install

```bash
git clone https://github.com/evanwang810/thirsty-tokens
cd thirsty-tokens
pip install -e .
```

Needs Python 3.10+. The only dependency is the MCP SDK (for the server); the CLI and
widget are stdlib-only.

## CLI

```bash
thirsty --open          # summary + HTML report, opened in the browser
thirsty --since 7       # last week only
thirsty --no-report     # just the terminal summary
```

Knobs for the skeptical: `--throughput`, `--water-intensity`, `--gpu-watts`.

## Live desktop widget

A little always-on-top pill that re-reads your transcripts every few seconds and
watches the water climb as you work. Drag it anywhere; right-click for the menu.

```bash
thirsty-app            # full pywebview dashboard
thirsty-app --widget   # start as the floating pywebview widget
thirsty-widget         # widget-first shortcut
```

## MCP server

Built on the official MCP SDK. Wire it into Claude Code:

```bash
claude mcp add thirsty --scope user -- python -m thirsty.server
```

Restart Claude Code, then `claude mcp list` should show `thirsty ... Connected`.

Tools: `water_summary`, `water_widget` (returns a compact HTML widget as an embedded
resource), `water_breakdown` (by model and project). Resources: `thirsty://report`,
`thirsty://widget`. There's also a `/water-usage` slash command that runs the CLI and
summarizes it.

## Website

`docs/index.html` is a self-contained calculator hosted on GitHub Pages. Type in a
token count, get the water. It links back here for the auto-tracking tools.

## The model

Water = electricity x water intensity.

- **Electricity**: a B200 (~1 kW) x1.8 node overhead x1.2 PUE, serving ~1,500
  output-equivalent tokens per GPU-second. Lands near 0.4 Wh per 1,000 tokens.
- **Water intensity**: 3.0 L/kWh (on-site cooling ~1.8 + off-site power ~1.2).
- **Token weighting**: output counts full, prefill x0.2, cache reads x0.02.

Order-of-magnitude only, likely off by 3 to 5x either way. It depends on model size,
batch depth, data-center location, and grid mix. Treat it as a gut-check, not a bill.

MIT licensed.