claude-carbon

claude-carbon puts an estimated CO2 figure on every Claude Code answer: grams at the end of the line that closes each turn, and the session total, next to its API-price cost, pinned under the prompt. /carbon-panel adds a pixel molecule coloured by how this session compares with your usual one and, in the desktop app, your history as warming stripes. Everything is computed locally from token counts.

What it does

• Per answer. In the terminal the figure sits at the right end of the ✻ Worked for 38s line, such as 16 gCO₂. An unusual answer turns to the warning colour and shows its ratio to your median, 230 gCO₂ · 14× your median. Unusual means above the 97th percentile of your last 200 answers, over three times their median and at least 10 g: about one answer in 27, and none before 50 answers are recorded.
• Subagents. A foreground subagent counts in the answer that started it. A background one counts in the session total only, never in an answer or in your median.
• Session total. This session: 142 gCO₂ · $3.41 under the prompt. The dollar figure is what the same requests would cost at Anthropic’s pay-as-you-go API prices, not what a Pro or Max plan bills you.
• /carbon-panel in the terminal turns on the band above the prompt: a molecule of 13 by 4 cells beside the session’s CO2, answers, a coloured dot per subagent, model, context fill and API-price value. Run it again to clear the band.
• /carbon-panel in the desktop app opens a side pane. Under the molecule, a block for this session, then your usage over the last 7 or 30 days, 12 months, everything or two dates you type: tiles for CO2, change against the previous period, sessions, API-price value and a car equivalent, then one stripe per day, week or month. A gear turns on a split by project and a breakdown by kind of token with energy and CO2. A button puts /carbon-card in an empty prompt without sending it.
• The molecule’s colour compares this session with the median of your past sessions, in eight steps from dark blue (under an eighth of it) to dark red (over eight times it). Before 10 sessions are recorded it compares with a fixed reference of 0.5 kg. It hops while Claude works, faster as it reddens.

In the desktop app’s Code tab, where the turn line is not drawn, only unusual answers get a line under the answer. Turn the per-answer figure off with showPerTurn in /config, and the pinned total with showSessionTotal.

Install

Needs Claude Code 2.1.287 or later. The recorded history also needs jq and sqlite3, plus Git for Windows on Windows.

claude plugin marketplace add gwittebolle/claude-carbon
claude plugin install claude-carbon@claude-carbon

Restart Claude Code. The figures appear from the next answer; type /carbon-panel for the molecule.

The plugin alone gives the mod and the /carbon-* commands but, the README says, no database and no status line: nothing is recorded, so the pane has the live session and no history. The author’s installer sets up both, backfills the sessions whose transcripts are still on disk (about 30 days) and installs its own copy of the mod. Use one route or the other, since the plugin on top of the installer runs the hooks twice.

curl -fsSL https://raw.githubusercontent.com/gwittebolle/claude-carbon/main/install.sh | bash

On Windows the README gives irm https://raw.githubusercontent.com/gwittebolle/claude-carbon/main/install.ps1 | iex, after installing Git for Windows, jq and SQLite with winget. npx claude-carbon runs the same installer anywhere Node.js is installed. The installer’s status line adds model, context, cost and CO2 to the terminal:

How it works

Where the figures come from

For every model request, the mod reads the token counts and the model from turn.step and applies one formula: input and cache writes at the model’s input factor, cache reads at 0.08 of it, output at the output factor. Factors are in grams of CO2e per million tokens:

Model	Input and cache writes	Cache reads	Output
Fable	156	12.5	3,304
Opus	78	6.2	1,652
Sonnet	39	3.1	826
Haiku	10	0.8	207

One Opus request that re-reads 100,000 cached tokens and writes 1,000 comes to about 2.3 g: 0.6 g for the re-read, 1.7 g for the writing. In the author’s own sessions, cache reads are about 98% of the tokens and 60% of the CO2, and output is under 1% of the tokens and 30% of the CO2.

The factors come from Jegham et al. 2025, an arXiv preprint that estimates LLM inference energy on AWS from public API latency and throughput. Only Sonnet is fitted to that data, from three per-query estimates for Claude 3.7 Sonnet. The rest are extrapolations, because Anthropic publishes no per-model energy figures: Opus at twice Sonnet (the author gives two to five times as the plausible band), Haiku at a quarter, Fable at twice Opus. Energy, data-centre overhead included, becomes CO2 at the AWS US East grid average of 287 g per kWh, the low end of the range; the US average is about 380. The 0.08 for cache reads is an engineering estimate, and the extra cost of re-reading a long cache while generating is not modelled yet.

The author calls the results order-of-magnitude estimates, not measurements, and after reviewing the 2026 literature judges the displayed figure more likely low than high. The factors and prices are plain JSON in the plugin’s data/ folder, and the README and METHODOLOGY.md source each one. Models other than Claude, such as a local model behind ANTHROPIC_BASE_URL, count as zero. For scale, the author’s own badge reads 1,139 kg CO2e for 1,208 sessions between January and September 2026.

What it reads and sends

The mod reads token counts and model names, never the text of prompts or answers. Its tool.call hook watches only the Agent tool, to see when a subagent is sent to the background. Besides its own factor and price files, it reads sessions-history.tsv, which the bash hooks write after each answer next to the database in ~/.claude/claude-carbon/, and a daily update flag. It keeps your last 200 answer figures and the pane’s choices in its plugin store. It writes no database, starts no process, makes no network call and spends no tokens. Sending the /carbon-card the button prepares is a normal model turn.

The plugin carries more than the mod. Its Stop, SessionEnd and SessionStart command hooks parse your local transcripts into the SQLite database, and the daily check asks GitHub for the latest release tag. The installer’s status line can query Anthropic’s usage endpoint with your Claude Code OAuth token for the five-hour quota, cached for 60 seconds, when Claude Code does not pass that number in. /carbon-pr posts a comment on your pull request through gh only when you run it.

Limitations

• Text is in French when the first locale variable set (CLAUDE_CARBON_LOCALE, LC_ALL, LC_MESSAGES, LANG) starts with fr, and in English otherwise. With none set, common in the desktop app and on Windows, the language setting decides, and French is the fallback. Set language to English or CLAUDE_CARBON_LOCALE to en to avoid it.
• Draws in the terminal and the desktop app’s Code tab only. The period, tiles and stripes are desktop-only; the terminal band shows the current session.
• A turn line first drawn later, such as one only ctrl+o reveals, or one from a resumed transcript, gets no figure.
• Your answer median starts from zero with each install: figures recorded by another install of the mod do not carry over.
• The chat and Cowork tabs of the Claude app run on Anthropic’s servers, so nothing reaches your machine to count.