claude-carbon 1.5.0 → 1.8.0

package/README.md

@@ -6,10 +6,18 @@
 [![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.
+claude-carbon is an open source Claude Code plugin that tracks the carbon footprint of your sessions: a live CO2 estimate in the status line, computed locally from your token usage, next to the session cost.
 
 ![Live CO2 in the Claude Code status line](docs/demo.gif)
 
+## What claude-carbon does
+
+- Adds a live CO2 estimate to the Claude Code status line, next to the session cost
+- Persists each session to a local SQLite database, so history survives the 30-day transcript purge
+- Backfills historical data from existing `~/.claude` transcripts
+- Slash commands: `/carbon-report` (text), `/carbon-card` (PNG), `/carbon-pr` (footprint of a pull request)
+- A README badge with your all-time total, and a public methodology with every factor sourced
+
 **1. Install (or update):**
 
 macOS, Linux, WSL:
@@ -32,10 +40,12 @@ npx claude-carbon
 
 Same command to install and to update to the latest version (all three run the same installer).
 
+> **Installed from Anthropic's community marketplace and the plugin fails to load?** The `co2-tracker@claude-community` entry is pinned to a release from August 2026 that current Claude Code rejects ("Duplicate hooks file detected"). Run `/plugin uninstall co2-tracker@claude-community`, then install with one of the commands above.
+
 **2. Restart Claude Code.** Your CO2 appears in the status line:
 
 ```
-claude-carbon ⌥ main | 🟢 Opus 4.7 ▓▓▓░░░░░░░ 35% | $0.50 · 65g CO₂ | Use 24% ↻13:00
+claude-carbon ⌥ main | 🟢 Opus 5 ▓▓▓░░░░░░░ 35% | $0.50 · 65g CO₂ | Use 24% ↻13:00
 ```
 
 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%).
@@ -55,13 +65,6 @@ Accurate on every plan, including Max 20x.
 - `/carbon-card` - generate shareable PNG report cards (requires `playwright-core`, see [Dependencies](#dependencies))
 - `/carbon-update` - update to the latest version and re-price history (see [Updating](#updating))
 
-## What it does
-
-- Adds a live CO2 estimate to the Claude Code status line, next to the session cost
-- Persists each session to a local SQLite database
-- Backfills historical data from existing `~/.claude` transcripts
-- Two slash commands: `/carbon-report` (text) and `/carbon-card` (PNG)
-
 ## Example report
 
 <p align="center">
@@ -74,6 +77,12 @@ OneDrive-redirected one is honoured) and the folder opens in your file manager,
 card selected on macOS. `CLAUDE_CARBON_EXPORT_DIR` picks another folder;
 `CLAUDE_CARBON_NO_OPEN=1` skips the opening.
 
+From the 1st to the 10th of each month the status line ends with `📊 August wrapped · /carbon-card`:
+the month just closed has its bar on the card, under the running total. Generating a card
+clears it for the month; it goes quiet on its own after the 10th. `CLAUDE_CARBON_CARD_NUDGE_UNTIL_DAY`
+moves the cut-off, `CLAUDE_CARBON_NO_CARD_NUDGE=1` removes the nudge. Nothing is posted anywhere:
+sharing stays a human decision.
+
 <details>
 <summary>Advanced options (CLI)</summary>
 
@@ -149,6 +158,17 @@ The second script merges the block below into `~/.claude/settings.json` (additiv
         ]
       }
     ],
+    "SessionEnd": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "~/code/claude-carbon/scripts/persist-on-exit.sh"
+          }
+        ]
+      }
+    ],
     "SessionStart": [
       {
         "matcher": "",
@@ -164,7 +184,7 @@ The second script merges the block below into `~/.claude/settings.json` (additiv
 }
 ```
 
-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.
+The `Stop` hook records the session after each turn, and `SessionEnd` records it once more as it closes, so a last turn interrupted before `Stop` fired is still counted. The `SessionStart` one re-scans for sessions both 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.
 
@@ -195,14 +215,14 @@ Turning it off is the default: nothing is posted unless you run it. `--dry-run`
 
 ## How it works
 
-![Data flow](docs/data-flow.svg)
+![claude-carbon data flow: Claude Code transcripts and status line JSON to a local SQLite database and a CO2 estimate](docs/data-flow.svg)
 
 **Three data paths, two levels of accuracy:**
 
 | Script               | Trigger                 | Data source           | Subagents    | Cache reads         | Accuracy      |
 | -------------------- | ----------------------- | --------------------- | ------------ | ------------------- | ------------- |
 | `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 |
+| `persist-session.sh` | Stop + SessionEnd hooks | JSONL files           | Included     | Counted (8% energy) | Best estimate |
 | `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.
@@ -213,12 +233,14 @@ Turning it off is the default: nothing is posted unless you run it. `--dry-run`
 
 ### Surviving the 30-day transcript purge
 
-Claude Code deletes JSONL transcripts after about 30 days, so the SQLite database is the durable record. The `Stop` hook captures each session before its transcript ages out, and a once-a-day background re-scan (`SessionStart` hook, `safety-rescan.sh`) catches any session the `Stop` hook missed while its transcript still exists. Because each row stores raw token counts, `recompute.sh` regenerates cost and CO2 from `data/factors.json` + `data/prices.json` at any time, with no transcript needed. When Anthropic changes a price or a factor is revised, edit the config and run:
+Claude Code deletes JSONL transcripts after about 30 days, so the SQLite database is the durable record. The `Stop` and `SessionEnd` hooks capture each session before its transcript ages out, and a once-a-day background re-scan (`SessionStart` hook, `safety-rescan.sh`) catches any session they missed while its transcript still exists, including one whose transcript kept growing after its row was written. Because each row stores raw token counts, `recompute.sh` regenerates cost and CO2 from `data/factors.json` + `data/prices.json` at any time, with no transcript needed. When Anthropic changes a price or a factor is revised, edit the config and run:
 
 ```bash
 bash scripts/recompute.sh
 ```
 
+Sessions recorded since September 2026 are re-derived model by model, exactly. Older sessions without a per-model split keep their stored values; `--include-unsplit` re-derives them at their dominant model, an approximation (see METHODOLOGY.md, "Surviving the 30-day transcript purge").
+
 ## Commands
 
 | Command          | What it does                                        |
@@ -236,7 +258,8 @@ bash scripts/recompute.sh
 | -------------------- | ----------------------------------------------------------------------------------------- |
 | `setup.sh`           | Init database, backfill historical sessions, show total                                   |
 | `statusline.sh`      | Status line script (called automatically by Claude Code)                                  |
-| `persist-session.sh` | Stop hook (saves session data on exit)                                                    |
+| `persist-session.sh` | Stop hook (saves session data after each turn)                                            |
+| `persist-on-exit.sh` | SessionEnd hook (saves the session once more as it closes, in the background)             |
 | `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) |
@@ -250,17 +273,19 @@ Note: backfill now derives project names from the transcript's `cwd` (matching t
 
 ## Badge
 
-`/carbon-badge` prints a ready-to-paste shields.io badge with your measured all-time footprint, clickable back to this repo:
+`/carbon-badge` prints a ready-to-paste shields.io badge with your measured all-time footprint and the month it was taken, clickable to the methodology:
 
-[![Claude Code carbon footprint](https://img.shields.io/badge/claude--carbon-972.0%20kg%20CO2e-2f6f4f)](https://github.com/gwittebolle/claude-carbon)
+[![Claude Code carbon footprint](https://img.shields.io/badge/claude--carbon-1139.2%20kg%20CO2e%2C%202026--09-2f6f4f)](https://github.com/gwittebolle/claude-carbon/blob/main/METHODOLOGY.md)
 
-<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>
+<sub>That badge is live, not a mockup: the author's own total, 1,208 sessions measured between 15 January 2026 and 16 September 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)
+[![Claude Code carbon footprint](https://img.shields.io/badge/claude--carbon-1139.2%20kg%20CO2e%2C%202026--09-2f6f4f)](https://github.com/gwittebolle/claude-carbon/blob/main/METHODOLOGY.md)
 ```
 
-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.
+The badge is a static image built from your local database, so the number is measured, not estimated on the fly, and nothing is sent anywhere. The month in the message says how old the figure is; re-run `/carbon-badge` whenever you want to refresh both.
+
+It is one developer's total, so it belongs in your profile README or a personal project. In a team or organisation repository, reviewers will ask what produced the number and why it links out of the organisation, and they will be right to.
 
 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.
 
@@ -289,7 +314,8 @@ Factors from [Jegham et al. 2025](https://arxiv.org/abs/2505.09598), an arXiv pr
 
 - 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).
+- 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 most of the prefill compute; the factor is the residual. This is an engineering estimate derived from the literature, not Anthropic's 0.1x billing ratio. The decode-phase re-read of the cache grows with context length x generated tokens and is not modelled yet; every session stores that product (`output_context_sum`) so a calibrated term can be applied to history later. See [METHODOLOGY.md](METHODOLOGY.md).
+- Reviewed against the April-September 2026 literature (measurement papers, provider disclosures, the Watershed framework) with a sensitivity run on 30 days of real transcripts: no factor moved, the displayed figure is more likely low than high, next review March 2027. See [Where the estimate stands](METHODOLOGY.md#where-the-estimate-stands-september-2026).
 - 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.
 
@@ -400,86 +426,17 @@ hook and the status line, hook manifests spawned the way Claude Code spawns them
 
 ## Reduce your footprint
 
-Measuring is step one. Here are concrete levers to reduce your AI carbon footprint, ranked by impact.
-
-### Use the right model for the task
-
-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
-{
-  "env": {
-    "CLAUDE_CODE_SUBAGENT_MODEL": "claude-haiku-4-5"
-  }
-}
-```
-
-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)
-
-[RTK](https://github.com/rtk-ai/rtk) is a CLI proxy that filters noise from shell outputs (progress bars, verbose logs, passing tests) before they hit the context window. 60-90% token reduction on CLI commands, zero quality loss.
-
-```bash
-brew install rtk-ai/tap/rtk
-rtk init -g
-```
-
-### Reduce thinking tokens
-
-Claude's extended thinking can use up to 32k hidden tokens per message. Capping it reduces consumption without degrading quality on routine tasks.
-
-```json
-{
-  "env": {
-    "MAX_THINKING_TOKENS": "10000"
-  }
-}
-```
-
-### Compact earlier
-
-By default, Claude Code compacts context at 95% usage. Compacting earlier keeps context cleaner and avoids bloated sessions.
-
-```json
-{
-  "env": {
-    "CLAUDE_AUTOCOMPACT_PCT_OVERRIDE": "50"
-  }
-}
-```
-
-### 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:
-
-```
-Be concise. No preamble, no summaries unless asked.
-```
-
-Output tokens are the most expensive in both cost and energy.
-
-### Combined impact
+Measuring is step one. The levers below are ordered by what the 2026 measurement literature and this tool's own sensitivity run on real transcripts say matters most. None of them comes with a percentage: the emission factors carry a wider uncertainty band than any gain figure would. `/carbon-report` before and after a change, over several sessions, is the measurement that applies to you. The mechanism, the direction and the sources of each lever are in [docs/reduce.md](docs/reduce.md).
 
-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.
+- **Keep the context short when the model generates.** Almost every token of a session is a cache read, and the energy of a generated token grows with the context it is generated in. One session per task, `/clear` when the subject changes, `/btw` for side questions, subagents for exploration and verbose operations.
+- **Compact on your terms.** `/compact <instructions>` at a natural break, `/rewind` when abandoning a path, `/autocompact 150k` to bound the window, `CLAUDE_CODE_DISABLE_1M_CONTEXT=1` on models that run at 1M by default.
+- **Trim what every turn carries.** `/context` shows it. A short `CLAUDE.md` with the rest in skills, unused MCP servers off with `/mcp`, a CLI over an MCP server where both exist.
+- **Do not break the cache mid-session.** Pick the model and the effort level at the start; `/usage` shows the hit ratio and the likely cause of the last miss.
+- **Fewer turns, fewer failed loops.** A spec and a test the agent can run, a deterministic tool over a retry, `/clear` after two failed corrections, no `/loop` left running on an idle session.
+- **Ask the agent only what needs an agent.** An agentic task runs on the order of a thousand times the tokens of a chat exchange. A `--help` costs nothing.
+- **Match reasoning and model to the task.** `/effort low` on routine work, set at session start; Haiku for subagents via `CLAUDE_CODE_SUBAGENT_MODEL`.
 
-| 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**         |
+The same document covers what does not hold up (shell output filters, prompt compressors, adding up percentages), the harness as a lever, and what is out of your hands for now.
 
 ### Related projects
 
@@ -511,4 +468,4 @@ The shareable report cards already carry this attribution in their footer, so re
 
 claude-carbon is free and open source under the [MIT license](LICENSE). Contributions welcome.
 
-Built by [Gaetan Wittebolle](https://github.com/gwittebolle).
+Built by [Gaëtan Wittebolle](https://gaetanwittebolle.com), carbon consultant turned solo builder in Bordeaux, France. Team version: [TokenClimate](https://tokenclimate.com).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-carbon",
-  "version": "1.5.0",
+  "version": "1.8.0",
   "description": "Track the carbon footprint of your Claude Code sessions",
   "scripts": {
     "diagram": "node docs/render-diagram.mjs",
@@ -18,15 +18,23 @@
     "url": "git+https://github.com/gwittebolle/claude-carbon.git"
   },
   "bugs": "https://github.com/gwittebolle/claude-carbon/issues",
-  "author": "Gaetan Wittebolle (https://github.com/gwittebolle)",
+  "author": "Gaëtan Wittebolle <gaetan.wittebolle@gmail.com> (https://gaetanwittebolle.com)",
   "license": "MIT",
   "keywords": [
+    "claude-carbon",
     "carbon-footprint",
+    "carbon-emissions",
+    "co2",
+    "co2-tracker",
     "sustainability",
+    "green-it",
+    "green-ai",
     "claude-code",
+    "claude-code-plugin",
     "claude",
-    "green-it",
-    "co2"
+    "anthropic",
+    "statusline",
+    "llm"
   ],
   "engines": {
     "node": ">=18"