# Claude Code Impact Toolkit

Track the environmental and financial cost of your Claude Code
conversations.

## What it does

A PreCompact hook that runs before each context compaction, capturing:
- Token counts (actual from transcript or heuristic estimate)
- Cache usage breakdown (creation vs. read)
- Energy consumption estimate (Wh)
- CO2 emissions estimate (grams)
- Financial cost estimate (USD)

Data is logged to a JSONL file for analysis over time.

## Install

```bash
# Project-level (recommended)
cd your-project
./path/to/impact-toolkit/install.sh

# Or user-level (applies to all projects)
./path/to/impact-toolkit/install.sh --user
```

Requirements: `bash`, `jq`, `python3`.

## View results

```bash
.claude/hooks/show-impact.sh              # all sessions
.claude/hooks/show-impact.sh <session_id> # specific session
```

## How it works

The hook fires before Claude Code compacts your conversation context.
It reads the conversation transcript, extracts token usage data from
API response metadata, and calculates cost estimates using:

- **Energy**: 0.003 Wh/1K input tokens, 0.015 Wh/1K output tokens
- **PUE**: 1.2 (data center overhead)
- **CO2**: 325g/kWh (US grid average for cloud regions)
- **Cost**: $15/M input tokens, $75/M output tokens

Cache-read tokens are weighted at 10% of full cost (they skip most
computation).

## Limitations

- All numbers are estimates with low to medium confidence.
- Energy-per-token figures are derived from published research on
  comparable models, not official Anthropic data.
- The hook only runs on context compaction, not at conversation end.
  Short conversations that never compact will not be logged.
- See `impact-methodology.md` for the full methodology, uncertainty
  analysis, and non-quantifiable costs.

## Files

```
impact-toolkit/
  install.sh                       # installer
  hooks/pre-compact-snapshot.sh    # PreCompact hook
  hooks/show-impact.sh             # log viewer
  README.md                        # this file
```

## License

MIT. See LICENSE in the repository root.