claude-carbon 1.1.1 → 1.3.0

package/README.md

@@ -3,9 +3,13 @@
 [![GitHub stars](https://img.shields.io/github/stars/gwittebolle/claude-carbon)](https://github.com/gwittebolle/claude-carbon/stargazers)
 [![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)
 [![GitHub release](https://img.shields.io/github/v/release/gwittebolle/claude-carbon)](https://github.com/gwittebolle/claude-carbon/releases)
+[![npm](https://img.shields.io/npm/v/claude-carbon)](https://www.npmjs.com/package/claude-carbon)
+[![CI](https://github.com/gwittebolle/claude-carbon/actions/workflows/ci.yml/badge.svg)](https://github.com/gwittebolle/claude-carbon/actions/workflows/ci.yml)
 
 Track the carbon footprint of your Claude Code sessions.
 
+![Live CO2 in the Claude Code status line](docs/demo.gif)
+
 **1. Install (or update):**
 
 ```bash
@@ -67,6 +71,9 @@ bash ~/code/claude-carbon/scripts/generate-report.sh --since 2026-03-01
 
 # All time
 bash ~/code/claude-carbon/scripts/generate-report.sh --all
+
+# A closed period (--until is an exclusive upper bound: this one stops at June 30th)
+bash ~/code/claude-carbon/scripts/generate-report.sh --since 2026-01-01 --until 2026-07-01
 ```
 
 </details>
@@ -75,9 +82,30 @@ bash ~/code/claude-carbon/scripts/generate-report.sh --all
 <summary>Custom install directory</summary>
 
 ```bash
-CLAUDE_CARBON_DIR=~/my-path/claude-carbon curl -fsSL https://raw.githubusercontent.com/gwittebolle/claude-carbon/main/install.sh | bash
+curl -fsSL https://raw.githubusercontent.com/gwittebolle/claude-carbon/main/install.sh | CLAUDE_CARBON_DIR=~/my-path/claude-carbon bash
 ```
 
+The env var has to sit on the `bash` side of the pipe, not the `curl` side, or the installer never sees it.
+
+</details>
+
+<details>
+<summary>Second Claude environment (CLAUDE_CONFIG_DIR)</summary>
+
+If you run a second Claude Code environment out of its own config directory, e.g.
+
+```bash
+alias claude-work="CLAUDE_CONFIG_DIR=~/.claude-work claude"
+```
+
+install claude-carbon into that same directory by passing `CLAUDE_CONFIG_DIR` to the installer:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/gwittebolle/claude-carbon/main/install.sh | CLAUDE_CONFIG_DIR=~/.claude-work bash
+```
+
+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>
 
 <details>
@@ -86,9 +114,10 @@ CLAUDE_CARBON_DIR=~/my-path/claude-carbon curl -fsSL https://raw.githubuserconte
 ```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
 {
@@ -107,11 +136,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>
@@ -120,9 +162,9 @@ 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) - 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.
 
@@ -171,15 +213,25 @@ bash scripts/recompute.sh
 | `safety-rescan.sh`   | SessionStart hook (throttled background re-scan, catches missed sessions)                 |
 | `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` / `--all`)                                   |
+| `generate-report.sh` | Export PNG report cards (CLI, with `--since` / `--until` / `--all`)                                   |
 
 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>
 
+## 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
+
+```
+~/code/claude-carbon/scripts/statusline.sh --segment
+```
+
+(adjust the path if you installed with `CLAUDE_CARBON_DIR`). The widget receives the same status JSON on stdin and prints just the cost + CO2 pair, e.g. `$0.68 · 35g CO₂`. Segment mode never touches the network. Recording to the local database is unaffected either way: persistence runs from hooks, not from the status line.
+
 ## Emission factors
 
-Factors from [Jegham et al. 2025](https://arxiv.org/abs/2505.09598), a peer-reviewed study measuring energy consumption of LLM inference on AWS infrastructure.
+Factors from [Jegham et al. 2025](https://arxiv.org/abs/2505.09598), an arXiv preprint that estimates the energy consumption of LLM inference on AWS infrastructure from public API performance data (latency, throughput) over inferred hardware configurations.
 
 | Model  | Input (gCO2e/Mtok) | Output (gCO2e/Mtok) | Basis                      |
 | ------ | ------------------ | ------------------- | -------------------------- |
@@ -190,12 +242,14 @@ Factors from [Jegham et al. 2025](https://arxiv.org/abs/2505.09598), a peer-revi
 
 **Important: these are order-of-magnitude estimates, not precise measurements.**
 
-- Sonnet factors are a 3-point least-squares fit to the three measured Claude 3.7 Sonnet per-query energies in Jegham et al. v6 (0.950 / 2.989 / 5.671 Wh), giving a ~21:1 output:input ratio. The value is cross-validated against [EcoLogits](https://ecologits.ai): its independent estimate for Sonnet brackets the same range. Fable, Opus and Haiku are extrapolated (no public data from Anthropic on per-model energy consumption); Opus = 2x Sonnet matches both the current EcoLogits Opus 4.5+ parameter ratio and the Anthropic price ratio (honest band 2x-5x).
+- Sonnet factors are a 3-point least-squares fit to the three Claude 3.7 Sonnet per-query energies estimated in Jegham et al. v6 (0.950 / 2.989 / 5.671 Wh), giving a ~21:1 output:input ratio. The value is consistent with [EcoLogits](https://ecologits.ai): its independent estimate for Sonnet brackets the same range (a wide band, so this is a consistency check, not proof). Fable, Opus and Haiku are extrapolated (no public data from Anthropic on per-model energy consumption); Opus = 2x Sonnet matches both the current EcoLogits Opus 4.5+ parameter ratio and the Anthropic price ratio (honest band 2x-5x).
 - Sessions run on non-Anthropic models (e.g. local models behind `ANTHROPIC_BASE_URL`) are stored with their raw tokens but zero cost/CO2 and excluded from reports - a datacenter factor doesn't apply to them. Add patterns to `exclude_models` in `data/factors.json` to exclude more models by name.
 - Cache read tokens are counted at a reduced factor (default 0.08 of an input token, set in `data/factors.json`). A cached token skips prefill compute but still incurs decode-phase memory reads, so it is cheap but not free. This is an engineering estimate derived from the literature, not Anthropic's 0.1x billing ratio. See [METHODOLOGY.md](METHODOLOGY.md).
 - 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
@@ -239,7 +293,7 @@ Measuring is step one. Here are concrete levers to reduce your AI carbon footpri
 
 ### Use the right model for the task
 
-Output tokens cost ~21x more energy than input tokens (the marginal output:input ratio from Jegham v6). Opus consumes ~2x more than Sonnet per token.
+Output tokens cost ~21x more energy than input tokens (the marginal output:input ratio fit on Jegham v6). Opus is estimated at ~2x Sonnet per token (uncertainty band 2x-5x, see METHODOLOGY.md).
 
 ```json
 {
@@ -249,7 +303,7 @@ Output tokens cost ~21x more energy than input tokens (the marginal output:input
 }
 ```
 
-Use Opus for architecture and planning. Sonnet for daily work. Haiku for subagents (exploration, file reading, reviews). This alone can cut your emissions by 60%.
+Use Opus for architecture and planning. Sonnet for daily work. Haiku for subagents (exploration, file reading, reviews). As an indicative estimate with this tool's factors, this alone can cut your emissions by up to ~60% vs all-Opus.
 
 ### Install RTK (Rust Token Killer)
 
@@ -284,6 +338,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:
@@ -296,18 +360,27 @@ Output tokens are the most expensive in both cost and energy.
 
 ### Combined impact
 
-| Lever                | Estimated reduction     |
-| -------------------- | ----------------------- |
-| Right model per task | -60% vs all-Opus        |
-| RTK                  | -70% on CLI tokens      |
-| Thinking cap at 10k  | -70% on thinking tokens |
-| Haiku subagents      | -80% on exploration     |
-| **All combined**     | **-50 to 70% total**    |
+These reductions are indicative estimates, not measurements on a benchmark workload. The RTK figure comes from RTK's own documentation. The Haiku rows follow from this tool's own factors (Haiku = 0.5x Sonnet = 0.25x Opus per token): -50% when your subagents would otherwise run Sonnet, -75% when they would run Opus. They inherit the 0.5x extrapolation, the widest uncertainty band in the tool (see METHODOLOGY.md); if most of your usage is already Haiku, your absolute total rides on that band, so read it as an order of magnitude.
+
+| Lever                | Estimated reduction          |
+| -------------------- | ---------------------------- |
+| Right model per task | -60% vs all-Opus             |
+| RTK                  | -70% on CLI tokens           |
+| Thinking cap at 10k  | -70% on thinking tokens      |
+| 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
-- [Jegham et al. - How Hungry is AI?](https://arxiv.org/abs/2505.09598) - per-model energy measurements
+- [Jegham et al. - How Hungry is AI?](https://arxiv.org/abs/2505.09598) - per-model energy estimates
 - [UCL/UNESCO - 90% AI energy reduction](https://www.ucl.ac.uk/news/2025/jul/practical-changes-could-reduce-ai-energy-demand-90) - frugal AI approaches
 - [GreenIT.fr - AI impacts 2025-2030](https://www.greenit.fr/impacts-ia-monde-2025-2030-rapport/) - French data
 
@@ -315,6 +388,14 @@ Output tokens are the most expensive in both cost and energy.
 
 Every Claude Code session uses real compute, real energy, real emissions. The number is small per query, but it adds up. Making it visible is the first step to owning it.
 
+## Citing
+
+If claude-carbon's numbers or methodology end up in your article, talk or product, a citation is appreciated. GitHub's "Cite this repository" button generates BibTeX/APA from [CITATION.cff](CITATION.cff). Short form:
+
+> Wittebolle, G. (2026). claude-carbon: carbon footprint tracker for Claude Code sessions. https://github.com/gwittebolle/claude-carbon
+
+The shareable report cards already carry this attribution in their footer, so reposting a card as-is credits the tool.
+
 ## Open source
 
 claude-carbon is free and open source under the [MIT license](LICENSE). Contributions welcome.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-carbon",
-  "version": "1.1.1",
+  "version": "1.3.0",
   "description": "Track the carbon footprint of your Claude Code sessions",
   "bin": {
     "claude-carbon": "bin/claude-carbon.js"