claude-carbon 1.1.2 → 1.5.0

package/README.md

@@ -12,17 +12,25 @@ Track the carbon footprint of your Claude Code sessions.
 
 **1. Install (or update):**
 
+macOS, Linux, WSL:
+
 ```bash
 curl -fsSL https://raw.githubusercontent.com/gwittebolle/claude-carbon/main/install.sh | bash
 ```
 
-Or, if you have Node.js:
+Windows (PowerShell), which needs [Git for Windows](https://git-scm.com/downloads/win) and two packages first - see [Windows](#windows):
+
+```powershell
+irm https://raw.githubusercontent.com/gwittebolle/claude-carbon/main/install.ps1 | iex
+```
+
+Or, on any platform with Node.js:
 
 ```bash
 npx claude-carbon
 ```
 
-Same command to install and to update to the latest version (both run the same installer).
+Same command to install and to update to the latest version (all three run the same installer).
 
 **2. Restart Claude Code.** Your CO2 appears in the status line:
 
@@ -32,7 +40,7 @@ claude-carbon ⌥ main | 🟢 Opus 4.7 ▓▓▓░░░░░░░ 35% | $0.5
 
 Segments, left to right: project + git branch, model + context window %, session cost + CO2, 5h block usage % + reset time. A 🔥 prefix appears when the sustained burn rate would overshoot 100% of the limit by the end of the 5h block (after a 15 min grace window, only once usage reaches 15%).
 
-> **Terminal and IDE only.** claude-carbon runs through the Claude Code status line and shell hooks, which execute in the terminal CLI and IDE extensions. They do not run in the web app (claude.ai/code) or the desktop app, so no CO2 is displayed or recorded there.
+> **Where the CO2 shows up.** The status line is a feature of the Claude Code terminal UI. It is displayed only when you run `claude` in a terminal, including the integrated terminal of VS Code or JetBrains. The IDE extensions' chat panel has no status line at all, so nothing is displayed there even though the hooks still run and your sessions are recorded: `/carbon-report` covers them. If you use the VS Code panel and want the live CO2, open a terminal in VS Code (`` Ctrl+` ``) and run `claude` from there. The web app (claude.ai/code) and the desktop app run neither the status line nor the hooks, so nothing is displayed or recorded there.
 
 **5h quota source.** The percentage comes directly from Anthropic's `/api/oauth/usage` endpoint (the same data Claude Code displays in `/usage`). No heuristic, no token-limit file to seed. Two sources in order:
 
@@ -60,7 +68,11 @@ Accurate on every plan, including Max 20x.
   <img src="docs/example-report-v2.png" alt="Claude Carbon Report" width="540">
 </p>
 
-Generate yours with `/carbon-card` in Claude Code. Exports summary and detailed PNGs to `exports/`.
+Generate yours with `/carbon-card` in Claude Code. The summary and detailed PNGs land in
+`~/Downloads/claude-carbon/` (the Windows Downloads folder follows the system setting, so a
+OneDrive-redirected one is honoured) and the folder opens in your file manager, with the
+card selected on macOS. `CLAUDE_CARBON_EXPORT_DIR` picks another folder;
+`CLAUDE_CARBON_NO_OPEN=1` skips the opening.
 
 <details>
 <summary>Advanced options (CLI)</summary>
@@ -104,7 +116,7 @@ install claude-carbon into that same directory by passing `CLAUDE_CONFIG_DIR` to
 curl -fsSL https://raw.githubusercontent.com/gwittebolle/claude-carbon/main/install.sh | CLAUDE_CONFIG_DIR=~/.claude-work bash
 ```
 
-The status line, the Stop hook, the database and the `/carbon-*` commands all live under that config dir, so each environment tracks its own sessions independently. When `CLAUDE_CONFIG_DIR` is unset everything falls back to `~/.claude` as before.
+The status line, the hooks, the database and the `/carbon-*` commands all live under that config dir, so each environment tracks its own sessions independently. When `CLAUDE_CONFIG_DIR` is unset everything falls back to `~/.claude` as before.
 
 </details>
 
@@ -114,9 +126,10 @@ The status line, the Stop hook, the database and the `/carbon-*` commands all li
 ```bash
 git clone https://github.com/gwittebolle/claude-carbon.git ~/code/claude-carbon
 bash ~/code/claude-carbon/scripts/setup.sh
+bash ~/code/claude-carbon/scripts/configure-settings.sh
 ```
 
-Then add to `~/.claude/settings.json`:
+The second script merges the block below into `~/.claude/settings.json` (additively: an existing status line or third-party hooks are left alone) and symlinks the `/carbon-*` commands. To wire it by hand instead, skip it and add:
 
 ```json
 {
@@ -135,11 +148,24 @@ Then add to `~/.claude/settings.json`:
           }
         ]
       }
+    ],
+    "SessionStart": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "~/code/claude-carbon/scripts/safety-rescan.sh"
+          }
+        ]
+      }
     ]
   }
 }
 ```
 
+The `Stop` hook records the session that just ended. The `SessionStart` one re-scans for sessions that hook missed (crash, kill) and drives the daily update check the status line reads; without it you are never told a new version exists.
+
 Restart Claude Code.
 
 </details>
@@ -148,15 +174,28 @@ Restart Claude Code.
 
 claude-carbon measures one developer's sessions, locally. If the question comes from your CTO, a client RFP or a CSR committee, the same methodology exists as a hosted layer:
 
-- [Free calculator and per-model factor sheets](https://tokenclimate.com/calculator) - the exact versioned factors of this repo, browsable.
-- [Bilan IA](https://tokenclimate.com/bilan/en?ref=github) - a self-serve, shareable report of your organisation's real Claude usage (cost, CO2e, water, energy), generated in minutes from an Anthropic admin key. The key is never stored; the methodology annex is citation-ready.
-- [TokenClimate](https://tokenclimate.com) - hosted team dashboards. Both sides share this repo's golden vectors, verified weekly in CI.
+- [Free calculator](https://tokenclimate.com/en/calculator?ref=github) and [per-model factor sheets](https://tokenclimate.com/en/models?ref=github) - the exact versioned factors of this repo, browsable.
+- [AI usage report](https://tokenclimate.com/bilan/en?ref=github) - a self-serve, shareable report of your organisation's real Claude usage (cost, CO2e, water, energy), generated in minutes from an Anthropic admin key. The key is never stored; the methodology annex is citation-ready.
+- [TokenClimate](https://tokenclimate.com/en?ref=github) - hosted team dashboards. Both sides share this repo's golden vectors, verified weekly in CI.
 
 The only places the OSS points there are a one-line footer in `/carbon-report` and a small credit on the `/carbon-card` PNGs. No status-line promo, no email capture: nothing leaves your machine.
 
+### PR dev footprint (/carbon-pr)
+
+The number reviewers rarely see is what the PR cost to develop: your local Claude Code sessions while building the branch. `/carbon-pr` (or `scripts/generate-pr-report.sh`) sums the recorded sessions of the current branch and posts one sticky comment on its open PR, through your own `gh` auth. Run it after your push; running it again updates the same comment in place.
+
+```
+**Claude Code carbon report** · developing this PR
+124 g CO2e · $3.00 · 180k tokens · 1.5M cache reads · 2 sessions
+```
+
+How the sessions are attributed: the Stop hook stores each session's git branch (read from the transcript), and the report selects `project + branch`. Sessions recorded before this column existed carry no branch; `scripts/backfill.sh` repairs them while their transcripts are still on disk (about 30 days). Sessions started from a subdirectory of the repo are stored under the subdirectory's name and stay out of the sum. A session that ends on another branch than it started is attributed to where it finished.
+
+Turning it off is the default: nothing is posted unless you run it. `--dry-run` previews the comment, `--pr <number>` targets a specific PR, and deleting the comment on GitHub is the full cleanup.
+
 ## How it works
 
-![Data flow](docs/data-flow.png)
+![Data flow](docs/data-flow.svg)
 
 **Three data paths, two levels of accuracy:**
 
@@ -164,13 +203,13 @@ The only places the OSS points there are a one-line footer in `/carbon-report` a
 | -------------------- | ----------------------- | --------------------- | ------------ | ------------------- | ------------- |
 | `backfill.sh`        | Manual / setup          | JSONL files           | Included     | Counted (8% energy) | Best estimate |
 | `persist-session.sh` | Stop hook (session end) | JSONL files           | Included     | Counted (8% energy) | Best estimate |
-| `statusline.sh`      | Every turn (live)       | `context_window` JSON | Not included | Included (approx)   | Approximate   |
+| `statusline.sh`      | Every turn (live)       | `carbon.db` row       | Included     | Counted (8% energy) | One turn late |
 
 **backfill** and **persist-session** parse the raw JSONL transcripts (main session + subagent files), applying per-model emission factors. They deduplicate assistant messages by `(message.id, requestId)`, so resumed and compacted sessions are not double-counted (this matches `ccusage`; without it the token sum inflates roughly 3x). Each session stores its raw token breakdown (input, cache write, cache read, output), which feeds the SQLite database used by reports.
 
-**Cost** is the theoretical API list value (pay-as-you-go), not your subscription price: input, output, cache write (1.25x input), and cache read (0.1x input) at current Anthropic rates, set in `data/prices.json`. On deduplicated data it matches `ccusage`.
+**Cost** is the theoretical API list value (pay-as-you-go), not your subscription price: input, output, cache write, and cache read (0.1x input) at current Anthropic rates, set in `data/prices.json`. Cache writes are billed per TTL tier, 1.25x input for the 5-minute tier and 2x for the 1-hour one; each session's split is read from its transcript rather than assumed (Claude Code writes at the 1-hour tier). On deduplicated data it matches `ccusage`.
 
-**statusline** reads `context_window.total_input_tokens` from Claude Code at each turn. This value represents the current context size (not a cumulative total), includes cache reads, and does not account for subagent tokens. It's an indicative live display, not a data source for reports.
+**statusline** reads this session's row from `carbon.db` at each turn, so the CO2 it shows is the session total on the same basis as the reports, one turn behind at most. Before that row exists (first turn, or no database yet) it falls back to an estimate from `context_window.total_input_tokens`, which is the size of the current context rather than a running total: subagents are invisible to it and every compaction sends it back down. Either way the status line displays, it never feeds the reports.
 
 ### Surviving the 30-day transcript purge
 
@@ -186,6 +225,8 @@ bash scripts/recompute.sh
 | ---------------- | --------------------------------------------------- |
 | `/carbon-report` | Text report with totals, equivalences, top sessions |
 | `/carbon-card`   | Generate shareable PNG report cards                 |
+| `/carbon-badge`  | Shields.io badge of your total footprint for your READMEs |
+| `/carbon-pr`     | Post the dev footprint of the current branch on its PR |
 | `/carbon-update` | Update to the latest version and re-price history   |
 
 <details>
@@ -200,11 +241,29 @@ bash scripts/recompute.sh
 | `backfill.sh`        | Re-parse all historical JSONL transcripts (incl. subagents)                               |
 | `recompute.sh`       | Re-derive cost/CO2 from stored tokens after a price/factor change (no transcripts needed) |
 | `generate-report.sh` | Export PNG report cards (CLI, with `--since` / `--until` / `--all`)                                   |
+| `generate-badge.sh`  | Print the shields.io badge markdown + URL (CLI)                                           |
+| `generate-pr-report.sh` | Post the branch's dev footprint on its PR (CLI, `--dry-run` / `--pr`)                  |
 
 Note: backfill now derives project names from the transcript's `cwd` (matching the live hook). Sessions backfilled before this change keep their old, possibly truncated names; delete those rows and re-run `backfill.sh` to normalize them.
 
 </details>
 
+## Badge
+
+`/carbon-badge` prints a ready-to-paste shields.io badge with your measured all-time footprint, clickable back to this repo:
+
+[![Claude Code carbon footprint](https://img.shields.io/badge/claude--carbon-972.0%20kg%20CO2e-2f6f4f)](https://github.com/gwittebolle/claude-carbon)
+
+<sub>That badge is live, not a mockup: the author's own total, 1,025 sessions measured between 15 January 2026 and 20 August 2026. It is one developer's footprint, not the project's.</sub>
+
+```markdown
+[![Claude Code carbon footprint](https://img.shields.io/badge/claude--carbon-972.0%20kg%20CO2e-2f6f4f)](https://github.com/gwittebolle/claude-carbon)
+```
+
+The badge is a static image built from your local database, so the number is measured, not estimated on the fly. Re-run `/carbon-badge` whenever you want to refresh it.
+
+Numbers follow the locale the report uses (`fr` prints `12,4 kg`, `us` and the world default print `12.4 kg`); `CLAUDE_CARBON_LOCALE` forces a set.
+
 ## Using with ccstatusline
 
 Claude Code accepts a single `statusLine` command, so claude-carbon's full status line and [ccstatusline](https://github.com/sirmalloc/ccstatusline) cannot run side by side. If ccstatusline drives your status line, embed the CO2 segment instead: in the ccstatusline TUI, add a `Custom Command` widget pointing to
@@ -234,6 +293,8 @@ Factors from [Jegham et al. 2025](https://arxiv.org/abs/2505.09598), an arXiv pr
 - Carbon intensity uses the AWS region grid (location-based, 0.287 kgCO2e/kWh), not real-time grid data. This sits at the low end of the location-based range; the US national average is ~380 g/kWh.
 - Anthropic does not publish Scope 1, 2, or 3 emissions. These estimates are independent and based on academic research, not provider data.
 
+Report equivalences follow your locale, since a car and a kWh differ by ~2x between countries: ADEME/SNCF factors on a French or undetected locale, EPA ones in miles on a US locale, world-average ones otherwise (200 gCO2/km by car, 8.7 g per smartphone charge). Force a set with `CLAUDE_CARBON_LOCALE` (`fr`, `us`, `world`, or any locale string). The factors live in `data/factors.json` under `equivalences`.
+
 Factors are editable in `data/factors.json`. See [METHODOLOGY.md](METHODOLOGY.md) for the full scientific basis, formula, and equivalences.
 
 ### Golden vectors
@@ -260,9 +321,9 @@ curl -fsSL https://raw.githubusercontent.com/gwittebolle/claude-carbon/main/inst
 - `sqlite3` - local database
 - `git` - branch detection in status line (optional)
 - `curl` - 5h quota usage via Anthropic's `/api/oauth/usage` endpoint (optional, 60s cache)
-- `playwright-core` + Chromium - PNG export for `/carbon-card` (optional)
+- `node` + `playwright-core` + Chromium - PNG export for `/carbon-card` (optional)
 
-`jq` and `sqlite3` are pre-installed on macOS. On Linux: `apt install jq sqlite3`.
+`jq` and `sqlite3` are pre-installed on macOS. On Linux: `apt install jq sqlite3`. On Windows, see below.
 
 To use `/carbon-card`, install Playwright and its Chromium browser:
 
@@ -271,6 +332,72 @@ npm install -g playwright-core
 npx playwright install chromium
 ```
 
+## Windows
+
+claude-carbon is bash, and stays bash on Windows. That is deliberate rather than a
+shortcut: on native Windows, Claude Code runs status line and hook commands through
+the bash that ships with [Git for Windows](https://git-scm.com/downloads/win), falling
+back to PowerShell only when Git Bash is absent
+([status line docs](https://code.claude.com/docs/en/statusline#windows-configuration),
+[hooks docs](https://code.claude.com/docs/en/hooks)). The plugin speaks the shell its
+host already spawns.
+
+**Native Windows.** Install Git for Windows, plus the two commands it does not ship:
+
+```powershell
+winget install Git.Git --source winget
+winget install jqlang.jq --source winget
+winget install SQLite.SQLite --source winget
+```
+
+Then, in the same terminal:
+
+```powershell
+irm https://raw.githubusercontent.com/gwittebolle/claude-carbon/main/install.ps1 | iex
+```
+
+Everything else the plugin needs - `bash`, `awk`, `sed`, `grep`, `date`, `curl`,
+`git`, `cygpath` - comes with Git for Windows.
+
+**WSL 2.** Nothing special: run the `curl | bash` installer inside your distribution.
+Claude Code, its transcripts and claude-carbon all live on the Linux side. This is
+the path to pick if your projects are already in WSL. VS Code reaches it through the
+Remote - WSL extension.
+
+**Marketplace install.** `/plugin install claude-carbon@claude-carbon` behaves the
+same as on macOS, once Git for Windows, `jq` and `sqlite3` are present.
+
+### Windows specifics
+
+- **Git Bash is required.** Without it Claude Code routes commands to PowerShell,
+  which cannot run a `.sh` file. `claude doctor` tells you which shell it picked. If
+  Git is installed somewhere unusual, point Claude Code at it in `settings.json`:
+  `{"env": {"CLAUDE_CODE_GIT_BASH_PATH": "C:\\Program Files\\Git\\bin\\bash.exe"}}`.
+- **Paths in `settings.json` use forward slashes** (`C:/Users/you/code/claude-carbon/...`).
+  Git Bash eats unquoted backslashes, and the command then fails with no visible error.
+  The installer writes them correctly; only hand-edits need the care.
+- **Slash commands are copied, not symlinked.** Git Bash cannot create a real symlink
+  without Developer Mode, so `/carbon-report` and friends are copied into
+  `~/.claude/commands/` and refreshed on every update.
+- **Sandboxing is not available** on native Windows (a Claude Code limitation, not
+  this plugin's). Use WSL 2 if you need it.
+- **`/carbon-card` additionally needs Node.js**: `winget install OpenJS.NodeJS --source winget`.
+- **Behind a TLS-inspecting proxy or antivirus**, the clone fails with
+  `SSL certificate problem: unable to get local issuer certificate`. Git for Windows
+  checks certificates against its own bundled CA list, which does not know the root
+  such tools re-sign traffic with; the Windows certificate store does. Switch git to
+  it (verification stays on) and rerun the installer:
+  `git config --global http.sslBackend schannel`. The installer prints this hint
+  when it detects the case. The same interception is why `winget` needs
+  `--source winget` on those machines: the Microsoft Store source fails its
+  certificate check and, without an explicit source, winget aborts instead of
+  falling back.
+
+CI runs the full test suite on `windows-latest` under Git Bash, alongside Ubuntu,
+plus two Windows-only suites: `tests/run-windows-e2e.sh` (native paths through the Stop
+hook and the status line, hook manifests spawned the way Claude Code spawns them) and
+`tests/run-install-ps1-tests.ps1`.
+
 ## Reduce your footprint
 
 Measuring is step one. Here are concrete levers to reduce your AI carbon footprint, ranked by impact.
@@ -322,6 +449,16 @@ By default, Claude Code compacts context at 95% usage. Compacting earlier keeps
 }
 ```
 
+### Disconnect unused MCP servers
+
+Every connected MCP server ships its full tool schemas into the context window with every request, whether the session uses them or not. Most of that overhead is served from prompt cache after the first turn, and cache reads carry a much lower energy factor (see METHODOLOGY.md), so the saving per turn is modest; the gain comes from repetition across every turn of every session.
+
+```bash
+claude mcp list
+```
+
+Keep the servers the project actually uses, remove the rest with `claude mcp remove <name>`.
+
 ### Write concise instructions
 
 Add to your project's CLAUDE.md:
@@ -344,6 +481,13 @@ These reductions are indicative estimates, not measurements on a benchmark workl
 | Haiku subagents      | -75% vs Opus, -50% vs Sonnet |
 | **All combined**     | **-50 to 70% total**         |
 
+### Related projects
+
+- [EcoLogits](https://ecologits.ai) - Python library estimating the footprint of GenAI API calls across providers.
+- [CodeCarbon](https://github.com/mlco2/codecarbon) - measures the emissions of compute you run yourself (training, local inference).
+- [ImpactIA](https://github.com/SNCFdevelopers/ImpactIA) - AI impact calculator and guide by SNCF, Wavestone and Resilio.
+- [green-claude](https://github.com/Institut-du-Numerique-Responsable/green-claude) - Claude Code skill that steers generated code toward eco-design rules (RGESN, GR491).
+
 ### Further reading
 
 - [IEA - Energy and AI (2025)](https://www.iea.org/reports/energy-and-ai/) - data center projections

package/bin/claude-carbon.js

@@ -6,11 +6,45 @@
 "use strict";
 
 const { spawnSync } = require("node:child_process");
-const { mkdtempSync, writeFileSync } = require("node:fs");
+const { existsSync, mkdtempSync, writeFileSync } = require("node:fs");
 const { tmpdir } = require("node:os");
 const { join } = require("node:path");
 const pkg = require("../package.json");
 
+// The installer, the hooks and the status line are all bash. On macOS and Linux
+// that is simply "bash"; on Windows it is the bash.exe that ships with Git for
+// Windows, which is also the shell Claude Code itself spawns for hooks and the
+// status line. Returns null when nothing usable is found.
+function findBash() {
+  if (process.platform !== "win32") return "bash";
+
+  const candidates = [
+    // Same variable Claude Code reads, so a user who already pointed Claude Code
+    // at a non-default Git install does not have to say it twice.
+    process.env.CLAUDE_CODE_GIT_BASH_PATH,
+    join(process.env.ProgramFiles || "C:\\Program Files", "Git", "bin", "bash.exe"),
+    join(process.env["ProgramFiles(x86)"] || "C:\\Program Files (x86)", "Git", "bin", "bash.exe"),
+    join(process.env.LOCALAPPDATA || "", "Programs", "Git", "bin", "bash.exe"),
+  ].filter(Boolean);
+
+  for (const candidate of candidates) {
+    if (existsSync(candidate)) return candidate;
+  }
+
+  // Last resort: ask PATH. C:\Windows\System32\bash.exe is excluded on purpose —
+  // that one is the WSL launcher, and running the installer through it would set
+  // claude-carbon up inside the Linux distribution instead of on Windows.
+  const where = spawnSync("where.exe", ["bash"], { encoding: "utf8" });
+  if (where.status === 0 && where.stdout) {
+    for (const line of where.stdout.split(/\r?\n/)) {
+      const path = line.trim();
+      if (path && !/\\System32\\/i.test(path) && existsSync(path)) return path;
+    }
+  }
+
+  return null;
+}
+
 const INSTALL_URL =
   process.env.CLAUDE_CARBON_INSTALL_URL ||
   "https://raw.githubusercontent.com/gwittebolle/claude-carbon/main/install.sh";
@@ -46,9 +80,14 @@ if (arg !== undefined && arg !== "--dry-run") {
 }
 
 async function main() {
-  if (process.platform === "win32") {
+  const bash = findBash();
+  if (!bash) {
     console.error(
-      "claude-carbon needs bash (macOS or Linux); Windows is not supported yet.",
+      "claude-carbon runs on bash. On Windows that means Git for Windows, which\n" +
+        "Claude Code also uses for its own Bash tool.\n\n" +
+        "  Install it:  winget install Git.Git\n" +
+        "  Or, if it is already installed somewhere unusual, point at it:\n" +
+        '    set CLAUDE_CODE_GIT_BASH_PATH="C:\\Program Files\\Git\\bin\\bash.exe"',
     );
     process.exit(1);
   }
@@ -73,9 +112,9 @@ async function main() {
     process.exit(0);
   }
 
-  const { status, error } = spawnSync("bash", [file], { stdio: "inherit" });
+  const { status, error } = spawnSync(bash, [file], { stdio: "inherit" });
   if (error) {
-    console.error(`Could not run bash: ${error.message}`);
+    console.error(`Could not run ${bash}: ${error.message}`);
     process.exit(1);
   }
   process.exit(status ?? 1);

package/package.json

@@ -1,7 +1,11 @@
 {
   "name": "claude-carbon",
-  "version": "1.1.2",
+  "version": "1.5.0",
   "description": "Track the carbon footprint of your Claude Code sessions",
+  "scripts": {
+    "diagram": "node docs/render-diagram.mjs",
+    "diagram:png": "node docs/render-diagram.mjs --png"
+  },
   "bin": {
     "claude-carbon": "bin/claude-carbon.js"
   },