Water Footprint

💧 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:

1. 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%.

2. Datacenter overhead: server energy × PUE 1.2 (cooling, power delivery).

3. 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.

4. 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

• Subagent/background-task transcripts that live in separate files aren't yet included in the per-prompt number (the main-loop tokens dominate in most sessions).
• Per-prompt deltas are computed per session; running the same session in parallel windows could miscount.
• Water intensity varies ~10× by datacenter location and cooling design — tune WATER_WUE_* if you care about a specific region.