💧 water-footprint — fresh-water cost of your Claude Code prompts
A Claude Code plugin that estimates how many liters of fresh water each prompt consumed, based on which model answered, how many tokens it used, and standard datacenter water-use metrics.
After every response you'll see:
💧 This prompt: ~28.4 mL fresh water (8.35 Wh) · session: 0.21 L · lifetime: 3.40 L ≈ 6.8 half-liter bottles
And /water-report gives a full breakdown by model, plus lifetime totals across all sessions on your machine.
/water-viz renders an ASCII visualization right in the terminal — a glass filling with the water your session consumed, equivalence gauges (seconds of a shower, fraction of a toilet flush, cups of tea), per-model bars, and lifetime totals. Great for showing people what a "small" AI session actually drinks. (Prefer something shareable? scripts/water.js --html writes an animated HTML page instead.)
Install
From GitHub:
/plugin marketplace add nlok5923/water-script
/plugin install water-footprint@water-script
Or from a local clone:
/plugin marketplace add /path/to/water-script
/plugin install water-footprint@water-script
Requires Node.js (any recent version; the script has zero dependencies).
How it works
Claude Code writes a transcript of every session, including the exact token usage and model ID of every API call — so no guessing about tokens. A Stop hook fires after each response, parses the transcript, and:
-
Energy per token, tiered by model size (Wh per 1,000 output tokens):
| Tier | Models | Wh / 1k output tokens |
|---|
| small | Haiku-class | 0.4 |
| medium | Sonnet-class | 1.4 |
| large | Opus / Fable / Mythos-class | 3.5 |
Input tokens are cheap (prefill is parallel): counted at 10% of an output token. Cache writes at 12.5%, cache reads at 1.2%.
-
Datacenter overhead: server energy × PUE 1.2 (cooling, power delivery).
-
Energy → water via water-use effectiveness (WUE):
- on-site evaporative cooling: ~1.0 L/kWh (modern hyperscale)
- off-site water consumed generating the electricity: ~2.4 L/kWh (US grid average)
So roughly 3.4 mL of fresh water per Wh of server energy.
-
Reasoning effort: extended-thinking tokens already show up as output tokens, so effort is mostly captured automatically. A small residual multiplier (low 0.9× / medium 1.0× / high 1.1×) is applied via WATER_EFFORT.
Anchors for the numbers
- Google's 2025 environmental disclosure: a median Gemini text prompt ≈ 0.24 Wh energy and 0.26 mL on-site water — consistent with our small/medium tiers at typical response lengths.
- Li et al. 2023, "Making AI Less Thirsty": the WUE on-site + off-site framework and L/kWh ranges.
- Sam Altman (2025): an average ChatGPT query ≈ 0.32 mL water — same order of magnitude.
These are order-of-magnitude estimates, not measurements. Anthropic doesn't publish per-model energy figures, datacenter locations and cooling vary enormously (a dry-cooled DC on a clean grid can be 10× lower than an evaporatively cooled one on a thermal grid), and frontier-model compute per token is not public.
Tuning the assumptions
Every constant is overridable with environment variables (set them in your shell, or in settings.json env):
| Variable | Default | Meaning |
|---|
WATER_WH_SMALL / WATER_WH_MEDIUM / WATER_WH_LARGE | 0.4 / 1.4 / 3.5 | Wh per 1k output tokens by tier |
WATER_INPUT_FRACTION | 0.1 | input-token energy vs output token |
WATER_CACHE_WRITE_FRACTION | 0.125 | cache-write token energy |
WATER_CACHE_READ_FRACTION | 0.012 | cache-read token energy |
WATER_PUE | 1.2 | datacenter power overhead |
WATER_WUE_ONSITE | 1.0 | L/kWh, datacenter cooling |
WATER_WUE_OFFSITE | 2.4 | L/kWh, electricity generation |
WATER_EFFORT | medium | low / medium / high |
What's in the box
water-script/
├── .claude-plugin/marketplace.json # makes this repo installable as a marketplace
└── water-footprint/ # the plugin
├── .claude-plugin/plugin.json
├── hooks/hooks.json # Stop hook → per-prompt readout
├── scripts/water.js # zero-dependency estimator (hook + report + html modes)
├── skills/water-report/SKILL.md # /water-report command
└── skills/water-viz/SKILL.md # /water-viz animated visual report
State (session deltas + lifetime totals) lives in ~/.claude/water-footprint/. Delete that directory to reset the counters.
Known limitations
