agent-footprint

agent-footprint

A live view of the environmental footprint of your AI coding agents: electricity, water, carbon and mineral/metal depletion from answering your requests, counting both running the servers and a time-share of manufacturing them. Training the models is not included (see What's included). It reads the logs your agents already write, compares the numbers to everyday things (phone charges, glasses of water, km driven) and shows day, week, month and year overviews. The impact model is EcoLogits.

Install

Python 3.10+. From PyPI:

uvx agent-footprint serve            # try it without installing
uv tool install agent-footprint      # or: pipx install agent-footprint

On Python 3.13 or older, add the zstd extra (uv tool install "agent-footprint[zstd]") to also read Codex CLI's compressed archived sessions.

Optionally, open the view automatically whenever you start a coding agent (run from an installed copy, not uvx):

agent-footprint setup                # asks per agent; --yes for all, --status to check, --remove to undo

Usage

agent-footprint serve                # browser dashboard at http://localhost:8765
agent-footprint watch                # terminal view: today, all agents, live
agent-footprint watch --week         # also --month, --year; e.g. --month 2026-09
agent-footprint watch latest         # follow the newest session (or pass a session id)
agent-footprint watch --once         # print a snapshot and exit
agent-footprint open                 # open the terminal view in a split next to this one
agent-footprint info                 # versions, agents and log folders found, history size
agent-footprint config               # create the config file and print its path
agent-footprint update               # upgrade agent-footprint and EcoLogits

watch keys: ←/→ step through Year, Month, Week, Today and active sessions · ↓/↑ previous/next period · y m w d jump to a period · 1–9 Today or an active session · f follow newest · q quit.

Supported agents

✅ works · 🧪 implemented, not yet tried on a real install · ❌ not supported

¹ Copilot logs one prompt size per request, so its input tokens are estimated.

Past sessions are read too, and usage is kept in a local history after agents delete their logs. Only token counts, timestamps, model names and session/project ids are stored; no prompts or responses (session titles are opt-in).

Supported systems

agent-footprint open (and the setup hook) picks the right way to show the view:

² needs allow_remote_control yes in kitty.conf.

How the numbers are computed

Each response's model and token counts go into EcoLogits' LLM inference methodology. Because coding agents re-send large cached contexts, input tokens are also counted, at a small weight relative to output tokens (configurable; set to 0 for pure EcoLogits figures). Treat the results as order-of-magnitude estimates, not measurements.

What's included

Like EcoLogits, this covers inference only: the hardware that answers your requests, from making it to running it.

Training is a large one-off cost that providers don't publish for these models, and how to divide it over every request a model ever serves is an open question, so a per-request share would mostly be guesswork. Training, end-of-life, networking and end-user devices are outside EcoLogits' scope.

More in docs/details.md: log locations, history, the methodology and its assumptions, how figures are kept current, and configuration.

Contributing

See CONTRIBUTING.md.

License

MIT; see LICENSE. EcoLogits is MPL-2.0 and is installed as a dependency, not bundled.