claude-carbon 1.5.0 → 1.7.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:
@@ -35,7 +43,7 @@ Same command to install and to update to the latest version (all three run the s
 **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 +63,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 +75,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>
 
@@ -195,7 +202,7 @@ 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:**
 
@@ -289,7 +296,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.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-carbon",
-  "version": "1.5.0",
+  "version": "1.7.0",
   "description": "Track the carbon footprint of your Claude Code sessions",
   "scripts": {
     "diagram": "node docs/render-diagram.mjs",
@@ -21,12 +21,20 @@
   "author": "Gaetan Wittebolle (https://github.com/gwittebolle)",
   "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"