agent-footprint 0.1.0__tar.gz

agent_footprint-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,56 @@
+# Publishes to PyPI when a version tag (v0.1.0, ...) is pushed. Uses trusted publishing: PyPI has a
+# pending/registered publisher for this repo, workflow release.yml and environment pypi, so no token
+# is stored. Uploads with `uv publish` instead of twine, which rejects the Metadata 2.5 hatchling writes.
+name: release
+
+on:
+  push:
+    tags: ["v*"]
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - uses: astral-sh/setup-uv@v6
+      - run: uv run python -m pytest
+
+  build:
+    needs: test
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - uses: astral-sh/setup-uv@v6
+      - name: Tag matches the version in pyproject.toml
+        run: |
+          version=$(uv version --short)
+          if [ "v$version" != "$GITHUB_REF_NAME" ]; then
+            echo "::error::tag $GITHUB_REF_NAME does not match pyproject.toml version $version"
+            exit 1
+          fi
+      - run: uv build
+      - name: Smoke-test the wheel
+        run: uv run --no-project --isolated --with dist/*.whl agent-footprint --help
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/project/agent-footprint/
+    permissions:
+      id-token: write   # OIDC token for trusted publishing
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: astral-sh/setup-uv@v6
+      - run: uv publish --trusted-publishing always dist/*

agent_footprint-0.1.0/.gitignore

@@ -0,0 +1,9 @@
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.venv/
+dist/
+build/
+*.egg-info/
+*.log
+*.swp

agent_footprint-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Steven Warmelink
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

agent_footprint-0.1.0/PKG-INFO

@@ -0,0 +1,134 @@
+Metadata-Version: 2.5
+Name: agent-footprint
+Version: 0.1.0
+Summary: Live environmental footprint (energy, water, carbon) of AI coding agents: Claude Code, Codex CLI, Gemini CLI, OpenCode, Mistral Vibe and GitHub Copilot, computed with EcoLogits.
+Project-URL: Homepage, https://github.com/warmelinks/agent-footprint
+Project-URL: Methodology, https://ecologits.ai/latest/methodology/llm_inference/
+Author: Steven Warmelink
+License-Expression: MIT
+License-File: LICENSE
+Keywords: carbon,claude-code,codex,ecologits,gemini-cli,github-copilot,llm,mistral-vibe,opencode,sustainability
+Classifier: Environment :: Console
+Classifier: Environment :: Web Environment
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering
+Requires-Python: >=3.10
+Requires-Dist: ecologits<1,>=0.11
+Provides-Extra: zstd
+Requires-Dist: zstandard>=0.22; (python_version < '3.14') and extra == 'zstd'
+Description-Content-Type: text/markdown
+
+# agent-footprint
+
+A live view of the environmental footprint of your AI coding agents: electricity, water, carbon and
+mineral/metal depletion, across the full life cycle (running the servers plus a time-share of
+manufacturing them). 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](https://ecologits.ai).
+
+## Install
+
+Python 3.10+. Until it is on PyPI, install from a checkout of this repository:
+
+```bash
+uv tool install --editable ".[zstd]"
+```
+
+Once published:
+
+```bash
+uvx agent-footprint serve            # try it without installing
+uv tool install agent-footprint      # or: pipx install agent-footprint
+```
+
+Optionally, open the view automatically whenever you start a coding agent (run from an installed
+copy, not `uvx`):
+
+```bash
+agent-footprint setup                # asks per agent; --yes for all, --status to check, --remove to undo
+```
+
+## Usage
+
+```bash
+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
+
+| Agent | Reads usage | Opens view on session start (`setup`) |
+|---|:-:|:-:|
+| Claude Code (CLI, VS Code, JetBrains) | ✅ | ✅ |
+| Codex CLI (and its IDE extensions) | 🧪 | 🧪 |
+| Gemini CLI | 🧪 | 🧪 |
+| OpenCode | 🧪 | 🧪 |
+| Mistral Vibe | ✅ | ❌ |
+| GitHub Copilot, VS Code chat¹ | ✅ | ❌ |
+| Copilot CLI, Cursor, Windsurf, Cline / Roo Code, Continue, Aider | ❌ | ❌ |
+
+¹ 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
+
+| System | Works | Notes |
+|---|:-:|---|
+| Linux | ✅ | |
+| WSL | ✅ | Also reads agents installed on the Windows side; run `setup` in Windows for their hooks |
+| Windows | ✅ | PowerShell, cmd, Windows Terminal, VS Code |
+| macOS | 🧪 | No Mac tested yet; iTerm2/Terminal ask once for Automation permission |
+
+`agent-footprint open` (and the `setup` hook) picks the right way to show the view:
+
+| Terminal | Opens | Tried |
+|---|---|:-:|
+| Terminator | split pane | ✅ |
+| tmux, zellij, kitty², WezTerm, iTerm2, Windows Terminal | split pane | 🧪 |
+| GNOME Terminal, Konsole, macOS Terminal | new tab or window | 🧪 |
+| IDE terminals and anything else | browser dashboard | ✅ |
+
+² 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](https://ecologits.ai/latest/methodology/llm_inference/). 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.
+
+More in [docs/details.md](docs/details.md): log locations, history, the methodology and its
+assumptions, how figures are kept current, and configuration.
+
+## Development
+
+```bash
+uv sync --extra zstd
+uv run python -m pytest
+```
+
+To add an agent, subclass `FileSource` in `src/agent_footprint/sources/base.py` (see the existing
+sources) and register it in `sources/__init__.py`.
+
+## License
+
+MIT; see `LICENSE`. EcoLogits is MPL-2.0 and is installed as a dependency, not bundled.

agent_footprint-0.1.0/README.md

@@ -0,0 +1,111 @@
+# agent-footprint
+
+A live view of the environmental footprint of your AI coding agents: electricity, water, carbon and
+mineral/metal depletion, across the full life cycle (running the servers plus a time-share of
+manufacturing them). 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](https://ecologits.ai).
+
+## Install
+
+Python 3.10+. Until it is on PyPI, install from a checkout of this repository:
+
+```bash
+uv tool install --editable ".[zstd]"
+```
+
+Once published:
+
+```bash
+uvx agent-footprint serve            # try it without installing
+uv tool install agent-footprint      # or: pipx install agent-footprint
+```
+
+Optionally, open the view automatically whenever you start a coding agent (run from an installed
+copy, not `uvx`):
+
+```bash
+agent-footprint setup                # asks per agent; --yes for all, --status to check, --remove to undo
+```
+
+## Usage
+
+```bash
+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
+
+| Agent | Reads usage | Opens view on session start (`setup`) |
+|---|:-:|:-:|
+| Claude Code (CLI, VS Code, JetBrains) | ✅ | ✅ |
+| Codex CLI (and its IDE extensions) | 🧪 | 🧪 |
+| Gemini CLI | 🧪 | 🧪 |
+| OpenCode | 🧪 | 🧪 |
+| Mistral Vibe | ✅ | ❌ |
+| GitHub Copilot, VS Code chat¹ | ✅ | ❌ |
+| Copilot CLI, Cursor, Windsurf, Cline / Roo Code, Continue, Aider | ❌ | ❌ |
+
+¹ 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
+
+| System | Works | Notes |
+|---|:-:|---|
+| Linux | ✅ | |
+| WSL | ✅ | Also reads agents installed on the Windows side; run `setup` in Windows for their hooks |
+| Windows | ✅ | PowerShell, cmd, Windows Terminal, VS Code |
+| macOS | 🧪 | No Mac tested yet; iTerm2/Terminal ask once for Automation permission |
+
+`agent-footprint open` (and the `setup` hook) picks the right way to show the view:
+
+| Terminal | Opens | Tried |
+|---|---|:-:|
+| Terminator | split pane | ✅ |
+| tmux, zellij, kitty², WezTerm, iTerm2, Windows Terminal | split pane | 🧪 |
+| GNOME Terminal, Konsole, macOS Terminal | new tab or window | 🧪 |
+| IDE terminals and anything else | browser dashboard | ✅ |
+
+² 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](https://ecologits.ai/latest/methodology/llm_inference/). 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.
+
+More in [docs/details.md](docs/details.md): log locations, history, the methodology and its
+assumptions, how figures are kept current, and configuration.
+
+## Development
+
+```bash
+uv sync --extra zstd
+uv run python -m pytest
+```
+
+To add an agent, subclass `FileSource` in `src/agent_footprint/sources/base.py` (see the existing
+sources) and register it in `sources/__init__.py`.
+
+## License
+
+MIT; see `LICENSE`. EcoLogits is MPL-2.0 and is installed as a dependency, not bundled.

agent_footprint-0.1.0/docs/details.md

@@ -0,0 +1,182 @@
+# agent-footprint: details
+
+Reference material behind the [README](../README.md).
+
+## Opening the view automatically
+
+Python packages can't run anything at install time, so this is a separate step. Run it from an
+installed copy, not through `uvx`: the hooks call the program that set them up. `setup` adds a
+session-start hook to Claude Code, Codex CLI and Gemini CLI, and a small plugin to OpenCode (not to
+Vibe yet: its sessions are read, but nothing opens when one starts). Each one
+runs `agent-footprint open`, which opens the terminal view next to the agent:
+
+| Terminal | What opens |
+|---|---|
+| tmux, zellij, Terminator, kitty¹, WezTerm, iTerm2, Windows Terminal (native or WSL) | a split pane |
+| GNOME Terminal, Konsole, macOS Terminal | a new tab or window |
+| anything else (e.g. an IDE's terminal) | the browser dashboard, started once; it stops by itself 15 minutes after its last browser tab closes |
+
+¹ kitty needs `allow_remote_control yes` in `kitty.conf`.
+
+Inside an IDE (VS Code, JetBrains), including an agent extension's hooks, the browser dashboard
+opens: the terminal the IDE was started from isn't the one you're working in. tmux started in the
+IDE's terminal is split as usual.
+
+**macOS:** the first time the view opens in iTerm2 or Terminal, macOS asks whether agent-footprint
+may control that app. Run `agent-footprint open` there once by hand to answer it (or allow it under
+System Settings › Privacy & Security › Automation); from a hook, the question may go unseen. kitty's
+and WezTerm's command-line tools are also found inside their app bundles. Install with `uv tool
+install` (or pipx on a Python ≥ 3.10): the Python that comes with macOS is 3.9.
+
+Only one terminal view opens at a time, however many sessions you start. Set `"launch"` in the config
+to force a terminal (`"terminal": "wezterm"`), to turn off the browser fallback, or to resize the split.
+`setup` only changes its own entries in each agent's config file, and backs up the file
+(`*.agent-footprint.bak`) the first time. `setup --status` (and `info`) reports a hook whose program
+no longer exists, e.g. after its virtualenv was deleted; running `setup` again repairs it.
+
+`setup` also asks whether to name sessions after their first prompt (off by default; see [What is stored](#history-is-kept-after-agents-purge-their-logs)).
+
+## Where logs are read
+
+| Agent | Where it reads | Notes |
+|---|---|---|
+| Claude Code | `~/.claude/projects/*/<session>.jsonl` and subagent logs | Responses deduplicated by request id |
+| Codex CLI | `~/.codex/sessions/**/rollout-*.jsonl` and `archived_sessions/` | Compressed `.jsonl.zst` with the `zstd` extra or Python 3.14+ |
+| Gemini CLI | `~/.gemini/tmp/*/chats/session-*.jsonl` (and legacy `.json`) | Subagent chats counted under their parent session |
+| OpenCode | `~/.local/share/opencode/opencode.db` (and legacy `storage/`) | Read-only; child sessions counted under their parent |
+| Mistral Vibe | `~/.vibe/logs/session/*/meta.json` (or `save_dir` in its `config.toml`) | Vibe logs running token totals per session (updated after each turn), not per response: each increase is recorded when seen, so a session read afterwards counts at its last activity |
+| GitHub Copilot (VS Code chat) | VS Code's `workspaceStorage/*/chatSessions/` and `globalStorage/emptyWindowChatSessions/` (Code and Code - Insiders) | Output tokens and model calls are exact; Copilot logs one prompt size per request, so input tokens are estimated (see below). The model "Auto" picked is used |
+
+No hooks or plugins are needed in the agents just for reading, and past sessions work too. The
+Claude Code and Codex extensions for VS Code and JetBrains write the same logs, so they are counted.
+
+**Logs in other places.** An agent can have several log folders, and all of them are read:
+
+- **Environment variables:** default locations follow each agent's own variables: `CLAUDE_CONFIG_DIR`,
+  `CODEX_HOME`, `GEMINI_CLI_HOME`, `XDG_DATA_HOME`, `OPENCODE_DB` and `VIBE_HOME`.
+- **Hooks:** with `setup` hooks installed, every session start reports its transcript path, so a
+  folder used through an alias or a per-project variable is picked up automatically.
+- **WSL:** agents installed on the Windows side are found in each Windows user profile on `C:`
+  (add other drives with `"path"`).
+- **Config:** `"path"` under `"sources"` takes one folder or a list, for anything else
+  (e.g. a synced folder from another machine).
+
+Records are keyed by agent and request id, so a folder reached twice is never counted twice.
+`agent-footprint info` lists every folder in use.
+
+**Windows** works natively (PowerShell, cmd, Windows Terminal, VS Code's terminal) and under WSL.
+Files go to the same places under your user folder: `~\.config\agent-footprint`,
+`~\.local\share\agent-footprint` and `~\.cache\agent-footprint`. WSL reads the Windows-side agents'
+logs too, but `setup` there only installs hooks in the WSL-side agents; run `setup` in Windows for the
+others.
+
+**Adding an agent:** subclass `FileSource` in `src/agent_footprint/sources/base.py`. Implement
+`default_root()`, `units()` (its log files) and `parse_line()` (one JSON line to usage records with
+model and token counts), then register it in `sources/__init__.py` and add a fixture test.
+
+## History is kept after agents purge their logs
+
+Claude Code deletes transcripts after `cleanupPeriodDays` (30 days by default), and Gemini CLI after
+`general.sessionRetention.maxAge` (also 30 days by default). Each time agent-footprint runs, it copies
+new usage records into `~/.local/share/agent-footprint/history.sqlite` (`$XDG_DATA_HOME`), and they
+stay there after the source logs are gone. That is what makes month and year views possible.
+(Version 0.1.0 kept it in `~/.cache`; it is moved automatically.)
+
+**What is stored:** token counts, timestamps, model names, and each session's id and project folder
+name. No prompt or response content, with one opt-in exception: with `"store_titles": true` (or
+`agent-footprint setup --titles on`), sessions are named after the first 90 characters of their first
+prompt, and those titles are stored. Turning it off erases stored titles.
+
+- A stored response takes about 320 bytes including indexes: around 15 MB a year at 4,000 responses a month.
+- `serve` and `watch` sync continuously. To capture history when neither runs, add
+  `agent-footprint sync` to cron or to an agent's session-start hook at least every few weeks.
+- Only files that changed since the last sync are read, and only from where reading stopped.
+
+## How the numbers are computed
+
+Each response's model and token counts go into the
+[EcoLogits LLM inference methodology](https://ecologits.ai/latest/methodology/llm_inference/), using
+EcoLogits' model size estimates, provider datacenter defaults (PUE, WUE, location) and
+electricity mixes. The tests check the results against EcoLogits' own API.
+
+- **Model size:** most providers don't publish parameter counts. EcoLogits estimates a range, which is
+  the main source of the low–high spread.
+- **Model names:** Bedrock, Vertex and OpenRouter ids, dated snapshots and `[1m]` suffixes are
+  normalised. A model EcoLogits doesn't know yet is estimated as the closest known model of the same
+  family. The dashboard lists every such substitution, and also says when a request had no model in
+  the log, ran on Bedrock or Vertex (the model maker's datacenter defaults are used), or ran locally
+  (e.g. Ollama through OpenCode; estimated as if served from a datacenter).
+- **Input tokens:** EcoLogits counts only generated tokens. Agent sessions re-send large cached
+  contexts on every request, so input tokens are added as weighted "output-token equivalents" (new
+  input ×0.05, cache reads ×0.005). Set the weights to 0 in the config for pure EcoLogits figures.
+- **Not counted:** requests an agent doesn't log (for example, title generation), sessions that ran on
+  other machines (cloud or SSH sessions), networking, and your own device.
+
+- **GitHub Copilot's input tokens** are estimated: it logs the prompt size of the last model call of each
+  request only. The calls in a request are taken to grow linearly from the previous request's prompt
+  to that one, and only the growth counts as new input; the rest as cache reads. The dashboard says so
+  whenever Copilot is in view.
+
+Treat the results as order-of-magnitude estimates, not measurements.
+
+### Why input tokens are weighted
+
+EcoLogits counts only generated (output) tokens. Coding agents re-send their whole context on every
+request, mostly as cache reads: in a typical month of Claude Code use that is ~1,300M cache-read
+tokens against ~6M output tokens. Reading context isn't free (the model still runs over it), but
+per token it is much cheaper than generating:
+
+- Prefill processes all input tokens in parallel and is compute-bound, while generation produces one
+  token at a time and is memory-bandwidth-bound. So prefill energy per token is a small fraction of
+  decode energy.
+- A cache read skips recomputing the cached part and mostly costs memory traffic, so it is cheaper again.
+
+The weights (new input ×0.05, cache writes ×0.05, cache reads ×0.005 output-token equivalents) are a
+**judgement, not a measurement**. API prices put the ratios higher: input costs about 0.2× output,
+and cache reads 0.1× input. Prices reflect cost and margin, not just energy, so they are an upper
+reference. The choice matters: for the history above, EcoLogits' own method gives 8–14 kg CO₂e;
+the default weights give 16–28 kg; price ratios would give 43–73 kg. The dashboard shows the
+EcoLogits-only figure next to the assumption, and setting all weights to 0 in the config reproduces
+EcoLogits exactly.
+
+**One person's day.** Each indicator is also shown as a share of one person's daily footprint:
+
+- **Electricity and greenhouse gases:** electricity generated per person and greenhouse-gas emissions
+  per person (incl. land use) for the world, from Our World in Data (Ember; Jones et al.). Set
+  `"compare_country"` (an ISO code such as `"NLD"` or `"DEU"`) to add your country's average.
+- **Water:** full water footprints (Mekonnen & Hoekstra), including rainwater taken up by crops. An
+  agent's water is cooling and power-plant water only, so its share is a lower bound. A national
+  water figure is shown only where a sourced one is on file (currently the Netherlands).
+- **Carbon budget:** a 1.5 °C-compatible budget of 2.5 t per person per year (~6.85 kg/day).
+
+Past 100%, the share is shown in person-days. Sources are listed in the dashboard.
+
+## Keeping the figures up to date
+
+| Figures | Kept current by |
+|---|---|
+| Models, datacenters, electricity grids (EcoLogits) | Dependabot proposes each EcoLogits release; CI tests it and it is merged when green; a weekly job tests the newest release |
+| Electricity and greenhouse gases per person (world and countries) | `scripts/update_factors.py` refetches Our World in Data monthly and opens a pull request for review (changes over 25% are flagged) |
+| Everyday comparisons, water footprints, the 1.5 °C budget | each figure has an `as_of` year and a review interval; a yearly job opens an issue listing those due (`scripts/stale_factors.py`) |
+
+Users get new figures through releases. `serve` and `watch` check PyPI at most once a day and show a
+notice when newer EcoLogits data or a newer agent-footprint is available (turn off with
+`"auto_update_check": false`). `agent-footprint update` upgrades both in the tool's own environment
+(`uv tool`, `pipx` or `pip`); for a source checkout, `git pull` brings new figures.
+
+## Configuration
+
+```bash
+agent-footprint config               # creates ~/.config/agent-footprint/config.json and prints its path
+agent-footprint info                 # versions, agents found, history size, update status
+```
+
+The config holds the grid zone (ISO-3 code, e.g. `"FRA"`), datacenter PUE/WUE, batch size, hardware
+lifetime, input-token weights, per-provider overrides, which agents to read (and where), the
+country to compare with, session titles, and what `agent-footprint open` does. Both views pick up
+changes live. A setting that can't be used (a typo, an unknown country code, a value of the wrong
+type, or a file that isn't valid JSON) is reported by `info`, the dashboard and `watch`, and the
+default is used instead.
+
+The dashboard only answers requests addressed to `localhost`, so other web pages can't read it.
+`serve --host 0.0.0.0` makes it reachable from other machines, without authentication.

agent_footprint-0.1.0/docs/next-steps.md

@@ -0,0 +1,133 @@
+# Next steps
+
+State as of 2026-10-11: everything is committed on `master` and pushed to `github.com/warmelinks/agent-footprint`.
+Tests pass: 77 passed, 2 skipped on Linux; 76 passed, 3 skipped under Windows Python 3.13
+(`uv run python -m pytest`, which installs the `dev` group). Skips are platform-specific tests.
+
+The review of 2026-10-11 (privacy, history location, hooks, ports, config, dashboard access,
+syncing, Windows) is done except for the items under "Open from the review" below.
+
+## Before publishing
+
+- [ ] **Repository and package name.** `pyproject.toml`, the README and the dashboard link to
+      `github.com/warmelinks/agent-footprint`. Check that `agent-footprint` is free on
+      PyPI, create the GitHub repo, and update the links if the name differs.
+- [ ] **Commit author email.** The commits use `steven@soundappraisal.eu` from the local git config;
+      decide which address to use publicly before pushing.
+- [ ] **GitHub settings** the workflows rely on:
+  - "Allow auto-merge", plus a branch protection rule on `master` that requires the CI checks (`automerge.yml`).
+  - A PyPI trusted publisher for `release.yml` (environment `pypi`).
+  - Labels `ecologits` and `data`, used by the scheduled jobs.
+- [ ] **First release:** tag `v0.1.0`; `release.yml` builds and publishes.
+
+## Verification still missing
+
+- [ ] **Codex CLI, Gemini CLI and OpenCode readers** were built from those tools' source code (checked
+      2026-10-10) and tested on fixture logs, but never on real installs. Try each with real sessions.
+- [ ] **Session-start hooks** for Codex, Gemini and OpenCode: format checked against source, not run
+      in the real agents. Codex may ask to trust the hook once.
+- [ ] **Terminal launchers:** only Terminator (WSL) was seen live; the tmux, zellij, kitty, WezTerm,
+      iTerm2, Windows Terminal, GNOME Terminal, Konsole and macOS Terminal commands are untested.
+- [x] **Local setup:** `setup` has been run for Claude Code on both WSL and Windows (the old
+      `open_split.sh` hook is gone); session titles are switched on in both configs.
+
+## Windows / VS Code checks (run Claude Code natively in Windows for these)
+
+Native Windows support was built and tested from WSL on 2026-10-11: the test suite passes under
+Windows Python 3.13, and `info`, `watch --once`, `serve` (Host check, busy port) and `open`'s browser
+fallback were run natively. What only a native session can check:
+
+- [x] **Install:** `uv tool install --editable` of the WSL checkout (`\\wsl.localhost\Ubuntu\...`) works;
+      `agent-footprint` is on PATH. Not yet tried: a checkout on a Windows drive.
+- [x] **Hook from the VS Code extension:** Claude Code's SessionStart hook runs the bare
+      `agent-footprint open --hook --agent claude` and opens the browser dashboard (`hook.log`).
+      An empty console window that came with it is fixed (f110e58).
+- [ ] **Hook from the CLI** in Windows Terminal, and which shell runs hooks there (Git Bash, cmd,
+      PowerShell). A double-quoted absolute path (used when `agent-footprint` isn't on PATH) would not run
+      in PowerShell.
+- [x] **Hook input:** the Windows log folder was learned from the hook (`roots.json`).
+- [ ] **Windows Terminal split:** from a Claude Code session in Windows Terminal, `agent-footprint open`
+      should split the pane (`wt.exe -w 0 split-pane`) and run `watch` there.
+- [ ] **watch keys** in Windows Terminal, conhost (cmd.exe window) and VS Code's terminal: arrows, y m w d,
+      1–9, q; colours and box characters render; resizing redraws.
+- [ ] **VS Code fallback:** the dashboard starts once and the browser opens (seen). Still to see: it
+      stops 15 minutes after the last tab closes (`serve.log`), and no window appears since f110e58.
+- [ ] **Locked files:** `setup` while Claude Code is running (settings.json open); syncing while sessions
+      are being written; two Claude Code windows starting at once (`roots.json`, pid file).
+- [ ] **Codex, Gemini CLI, OpenCode on Windows**, if installed: their log locations and hooks.
+- [x] **Mistral Vibe and GitHub Copilot (VS Code chat)** update live in `watch` and the dashboard
+      (checked 2026-10-11). Neither has a session-start hook in `setup` yet; the Copilot CLI is unsupported.
+- [ ] **CI:** the `windows-latest` jobs pass once the repository is on GitHub.
+
+## macOS checks (no Mac available yet)
+
+Reviewed by reading the code on 2026-10-11; the `macos-latest` CI jobs will run the unit tests.
+Only a Mac can check:
+
+- [ ] **iTerm2:** `agent-footprint open` splits the agent's own session (targeted through
+      `ITERM_SESSION_ID`), also with several iTerm windows open; the Automation prompt appears once.
+- [ ] **Terminal.app:** a new window opens with `watch`; the same Automation prompt.
+- [ ] **kitty / WezTerm** without their CLIs on PATH: found in `/Applications/*.app/Contents/MacOS/`.
+- [ ] **Claude Code from VS Code** started from iTerm (`code .`): the hook opens the browser, not an iTerm split.
+- [ ] **Copilot:** chats found under `~/Library/Application Support/Code/User`.
+- [ ] **watch keys** in iTerm2 and Terminal.app.
+
+## Figures reviewed
+
+Reviewed 2026-10-11; `python scripts/stale_factors.py` reports nothing due until 2027.
+- EU household electricity: 3,600 → 3,525 kWh/year (Eurostat 2024), so a day is now 9.7 kWh.
+- Petrol car: 170 → 162 g/km (DESNZ 2026).
+- Transatlantic flight: still ~0.8 t (DESNZ 2026 with radiative forcing and well-to-tank). The source text now shows the calculation.
+- Water footprints and the 1.5 °C budget: no newer edition exists, so only `as_of` was bumped.
+
+## Open from the review
+
+- [ ] **`agent-footprint update` on an "externally managed" Python** (Debian/Ubuntu system Python,
+      Homebrew; PEP 668): the `pip install` path fails. Detect it and point to `uv tool` or `pipx`.
+- [ ] **One watch view at a time, machine-wide:** a second terminal window or tmux session never gets a
+      pane. Document it, or make it per terminal window.
+- [ ] **Headline figure:** label the dashboard's main numbers as "EcoLogits + input-token extension"
+      (both figures are already shown under "What's behind these numbers?").
+- [ ] **Titles erased while switched off** don't come back when they are switched on again (parser state
+      marks them "found, not kept"). Option: when titles are on, re-read the title from logs that still
+      exist. The WSL history has titles for 15 of 152 sessions because of this.
+- [ ] **Code quality:** type hints; a table-driven rewrite of `model.resolve_model` with more cases;
+      split `watch.py` (rendering vs input); `logging` instead of `print` in `serve`; a ruff config.
+
+## More agents
+
+- [ ] **Session-start hooks for Vibe and Copilot**, so the view opens with them too (their sessions are
+      read already). Vibe has some kind of hooks (its stats count hook-denied tool calls): check its docs.
+- [ ] **Copilot CLI:** not supported; no session data on the maintainer's machine. Look at what it
+      writes after a real session (`~/.copilot/`).
+- [ ] **Cursor, Windsurf, Cline / Roo Code, Continue, Aider:** need real sessions to build and test against.
+
+## Known limitations / ideas
+
+- **The input-token weights** (×0.05 new input and cache writes, ×0.005 cache reads) are a judgement and
+  roughly double totals versus EcoLogits alone (see README, "Why input tokens are weighted").
+  Measured prefill/cache energy data would let this be grounded better.
+- **Remote and cloud sessions** (claude.ai/code, SSH hosts) aren't counted. Options: an rsync mirror as
+  an extra source, or an OTLP receiver in `serve` (agents can export usage via OpenTelemetry).
+- **Under WSL**, Windows-side agents are read, but `setup` only installs hooks in the WSL-side agent
+  configs; Windows-side hooks need `setup` run in Windows.
+- **National water footprints** exist only for the Netherlands; other countries show world only.
+- **Mistral Vibe** logs running totals per session only: timing is per turn while a view runs, but a
+  session first read afterwards counts in full at its last activity.
+- **GitHub Copilot's input tokens are estimated** (one prompt size per request is logged); output tokens
+  and model calls are exact. Its "Auto" model may be one EcoLogits doesn't know (e.g. Microsoft's
+  `mai-*`), estimated as the closest model of that maker and size.
+- **Inside an IDE** the browser opens rather than a split; zellij run in an IDE's terminal therefore
+  gets the browser too (its variables look the same as inherited ones).
+
+## Where things are
+
+| Area | Files |
+|---|---|
+| Impact model (EcoLogits wrapper, model-name resolution, baselines) | `src/agent_footprint/model.py` |
+| Agent log readers and folder discovery | `src/agent_footprint/sources/` (claude, codex, gemini, opencode, vibe, copilot) |
+| History store (kept after agents purge logs) | `src/agent_footprint/store.py`, `~/.local/share/agent-footprint/history.sqlite` |
+| Periods and aggregation | `periods.py`, `summary.py`, `views.py` |
+| Dashboard and terminal | `server.py` + `web/index.html`, `watch.py` |
+| Hooks and launching | `hooks.py` (`setup`), `launch.py` (`open`) |
+| Figure upkeep | `scripts/update_factors.py`, `scripts/stale_factors.py`, `.github/workflows/` |