A portable Agent Skill that estimates the water, energy, and CO2 footprint of your own AI coding usage from local transcripts. It measures both Claude Code and OpenAI Codex, attributes each to its real datacenter grid, and reports a combined total with a per-agent breakdown. Nothing leaves your machine; no paid API. Runs under Claude Code and Codex.
Example output (synthetic data). Generate your own with --svg.
You: what's the footprint of all my AI coding agents?
(runs the skill)
BY AGENT
Claude 159 kWh · 290 L · 50 kg CO2e [anthropic-indiana]
Codex 50 kWh · 92 L · 16 kg CO2e [openai-azure]
WATER: ~382 L (230 – 682 L) ~2.5 bathtubs · 6 showers
ENERGY: ~209 kWh (157 – 293 kWh)
CO2: ~66 kg CO2e (45 – 101 kg) ~1 tree-seedling · 267 km driven
OFFSET: ~$0.20 avoidance · ~$1.2 nature-based · ~$20 permanent removal · +$0.4 water
Claude 76% · Codex 24% of energy
Most AI-footprint tools get four things wrong; this one doesn't:
- De-duplication. Resumed/compacted sessions repeat the same assistant
message across files. Counting them inflates tokens ~3–4×. This dedups by
(message.id, requestId). - Per-model energy. Opus, Sonnet, and Haiku are weighted separately.
- Location-based factors. Off-site electricity (the dominant term for both water and carbon) uses the factors for Anthropic's actual grid (Project Rainier / Indiana Michigan Power: ~1.6 L/kWh, ~235 gCO2e/kWh), not the generic US-average that overstates them.
- Water and carbon don't move together. The default grid is ~88% nuclear, so carbon reads low (below US average) while water stays moderate (nuclear still evaporates cooling water). Tools using one US-average factor miss this.
- Two agents, two grids. It measures Claude Code and OpenAI Codex and puts
each on its real infrastructure (Claude on Anthropic's nuclear-heavy Indiana
grid, Codex/gpt-5.x on Azure/ERCOT), then combines them with a per-agent
breakdown. Codex's reasoning tokens are counted (logged inside
output_tokens). - Honest offset cost. It shows what compensation would cost across all three credit tiers. A "$0.55 offset" buys avoidance (removes nothing you emitted); only permanent removal (~100× pricier) truly cancels it.
It always reports low/central/high bands and is explicit about the accuracy floor.
Claude Code (skills live under ~/.claude/skills):
git clone https://github.com/abreparentesis/ai-footprint.git ~/.claude/skills/ai-footprintOpenAI Codex (skills live under ~/.codex/skills):
git clone https://github.com/abreparentesis/ai-footprint.git ~/.codex/skills/ai-footprintThen ask the agent about your footprint, or run the script directly (see below).
The bundled AGENTS.md documents the skill for Codex; the script is plain Python
3 with no dependencies, so it also runs standalone from a clone anywhere.
Ask the agent about your footprint, or run the script directly. By default it measures every agent with local data (Claude Code + Codex) and reports a combined total plus a per-agent breakdown:
python3 scripts/estimate_footprint.py # all agents, all time
python3 scripts/estimate_footprint.py --agent codex # just OpenAI Codex
python3 scripts/estimate_footprint.py --days 30 # a window
python3 scripts/estimate_footprint.py --svg # also write an infographic (ai-footprint.svg)
python3 scripts/estimate_footprint.py --grid us-average # Claude grid sensitivity
python3 scripts/estimate_footprint.py --json # machine-readablePython 3, standard library only. Works on macOS/Linux/Windows. Reads
~/.claude/projects (Claude Code) and ~/.codex/sessions (Codex).
--svg writes a brief, self-contained two-panel card (water + CO₂) with the
central figure, the low–high range, and three everyday comparisons each
(bathtubs, showers, tree-seedlings, km driven, …). It's a single SVG with no
fonts or network, themes for light/dark automatically, and carries the same
caveats as the numbers, safe to drop into a README, slide, or chat.
Every report shows what offsetting would cost, a read-only estimate (no
purchase, no wallet, no consent needed). Carbon prices diverge 100× by credit
quality, so all three tiers are always shown: avoidance ($3/t, removes
nothing already emitted), nature-based removal ($18/t, real but impermanent, decades), and permanent removal ($300/t, biochar/DAC locking CO₂ away for
centuries, the only tier that genuinely cancels an emission). Water uses the BEF
Water Restoration Certificate price ($4 / 1,000 gal). Indicative 2026 prices;
see methodology §11.
Show a live footprint in Claude Code's status line. Note: statusLine is a
terminal/TUI feature, the desktop app does not render command status lines,
so this only appears when you run the claude CLI in a terminal. Point
settings.json at the bundled script:
{ "statusLine": { "type": "command", "command": "/abs/path/ai-footprint/scripts/statusline.py", "padding": 0 } }It prints a one-liner like 🌿 1,048 L · 175 kg CO₂e · ~$53 to offset (30d). The
status line itself is instant: it reads a small cache file and never scans on
the hot path. A detached background job (statusline_refresh.py) recomputes the
rolling 30-day footprint at most every 15 minutes. Any failure degrades to a
minimal label, so it can't break your status line.
These are estimates, not meter readings. Both water and carbon are dominated by the electricity term and depend on the grid mix; per-token energy on undisclosed hardware is the largest residual uncertainty. Carbon includes embodied hardware (~+20%); water's chip-fab Scope 3 is omitted (biases water slightly low). Inference only (training is separate and amortized). Full constants, citations, and the uncertainty discussion are in references/methodology.md.
MIT. Built on published research (Jegham et al. 2025; Li & Ren / "Making AI Less
Thirsty"; Epoch AI; IPCC AR5; Google/NVIDIA hardware LCAs), AWS and Microsoft Azure
sustainability disclosures, EPA eGRID and the EEI/Climatiq utility carbon factors,
and the dedup approach used by ccusage. See the methodology file for full credit.