claude-carbon

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.

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:

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

Windows (PowerShell), which needs Git for Windows and two packages first - see Windows:

irm https://raw.githubusercontent.com/gwittebolle/claude-carbon/main/install.ps1 | iex

Or, on any platform with Node.js:

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 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%).

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:

1. stdin (preferred): if Claude Code injects rate_limits.five_hour.used_percentage in the statusline JSON, that value is used straight away.
2. OAuth API fallback: GET https://api.anthropic.com/api/oauth/usage with the bearer token from macOS Keychain, CLAUDE_CODE_OAUTH_TOKEN, or ~/.claude/.credentials.json. Cached 60s in ~/.claude/claude-carbon/oauth-usage.json.

Accurate on every plan, including Max 20x.

3. Use the slash commands:

• /carbon-report - text report with totals, equivalences, top sessions
• /carbon-card - generate shareable PNG report cards (requires playwright-core, see Dependencies)
• /carbon-update - update to the latest version and re-price history (see Updating)

Example report

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.

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.

Advanced options (CLI)

# Since a specific date
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

Custom install directory

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.

Second Claude environment (CLAUDE_CONFIG_DIR)

If you run a second Claude Code environment out of its own config directory, e.g.

alias claude-work="CLAUDE_CONFIG_DIR=~/.claude-work claude"

install claude-carbon into that same directory by passing CLAUDE_CONFIG_DIR to the installer:

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.

Manual install

git clone https://github.com/gwittebolle/claude-carbon.git ~/code/claude-carbon
bash ~/code/claude-carbon/scripts/setup