Metadata-Version: 2.4
Name: claude-burn
Version: 0.1.2
Summary: Compact Claude usage tracking after each Claude task
Author-email: Arkaprava Ghosh <ghosharkaprava8@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/ghosharkaprava8/claude-burn
Project-URL: Repository, https://github.com/ghosharkaprava8/claude-burn
Project-URL: Issues, https://github.com/ghosharkaprava8/claude-burn/issues
Project-URL: Changelog, https://github.com/ghosharkaprava8/claude-burn/blob/main/CHANGELOG.md
Keywords: claude,anthropic,usage,tokens,cost,budget,claude-code
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Utilities
Classifier: Topic :: Software Development
Classifier: Environment :: Console
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: click>=8.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-mock>=3.12; extra == "dev"
Dynamic: license-file

# claude-burn

[![PyPI](https://img.shields.io/pypi/v/claude-burn.svg)](https://pypi.org/project/claude-burn/)
[![Python](https://img.shields.io/pypi/pyversions/claude-burn.svg)](https://pypi.org/project/claude-burn/)
[![Tests](https://github.com/ghosharkaprava8/claude-burn/actions/workflows/test.yml/badge.svg)](https://github.com/ghosharkaprava8/claude-burn/actions/workflows/test.yml)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)

> Live Claude usage tracking that fits on one line. Know your burn rate without leaving the terminal.

```
~$12.48 / $50 [████░░░░░░] 25% | last: 4.2k tok | [████████▓▓] opus 83% sonnet 17%
```

Every Claude Code task ends with one terse line: dollars used, budget remaining, last-prompt tokens, and the model mix that drove the cost — auto-updated, never a dashboard.

---

## Why

Claude usage stats live on the Anthropic dashboard. Switching tabs to check spend breaks flow. `claude-burn` brings a single colored line to your terminal — automatically after every task via a Stop hook, manually via `claude-burn status`, or as a rich history when you want it.

**Design contract:** the default output is **one line preferred, two lines max**. Richer breakdowns sit behind explicit `detail` / `history` / `doctor` commands.

---

## Features

- **Compact post-task summary** — auto-fires after every Claude prompt via Stop hook
- **Threshold-colored budget bar** — green < 60% → yellow < 90% → red ≥ 90%
- **Per-prompt history** — table view of recent prompts with summary, tokens, cost
- **Model-share bar** — visual split of cost by model (magenta=opus, blue=sonnet, green=haiku)
- **Estimated cost** — local computation, 24h auto-refresh of pricing data, offline fallback
- **Billed cost (optional)** — connect Anthropic Admin API for authoritative numbers, 6h auto-refresh
- **Budget alerts** — warnings at 75% / 90% / 100% spend
- **Granular history** — drill into individual prompts: when, project, model, summary, tokens, cost
- **JSON output** for scripting / dashboards
- **Safe Stop hook** — 8s time budget, never blocks Claude tasks, always exits 0

---

## Install

### Homebrew (macOS / Linux)

```bash
brew install ghosharkaprava8/claude-burn/claude-burn
```

Or, two-step:

```bash
brew tap ghosharkaprava8/claude-burn
brew install claude-burn
```

### pip / pipx / uv

```bash
pip install claude-burn
# or, isolated:
pipx install claude-burn
uv tool install claude-burn
```

Requires Python 3.11+.

---

## Quick start

```bash
claude-burn init                       # creates config + db, backfills history
claude-burn budgets --monthly 50       # set your monthly spend cap
claude-burn status                     # the one-liner
```

`init` is interactive — it'll offer to connect the Anthropic Admin API for billed cost (skip with `--no-prompt` for non-interactive setups).

---

## What you'll see

### `claude-burn status`

```
~$12.48 / $50 [████░░░░░░] 25% | last: 4.2k tok | [████████▓▓] opus 83% sonnet 17%
```

| segment | meaning |
|---|---|
| `~$12.48 / $50` | spent / monthly budget (`~` = estimated) |
| `[████░░░░░░] 25%` | budget bar; green<60%, yellow<90%, red≥90% |
| `last: 4.2k tok` | tokens used by the most recent prompt |
| `[████████▓▓]` | model-mix bar split by cost share |
| `opus 83% sonnet 17%` | top-3 models color-matched to the bar |

### `claude-burn last`

```
last turn: 4.2k tok | claude-opus-4-7 | session total: 322 turns, ~$50.26 (est)
```

### `claude-burn history`

Granular per-prompt table, newest first. Default 10 rows; `--expand` for 50; `--all` for everything.

```
 #  when         project       model       prompt                                                        tokens  cost
──  ───────────  ────────────  ──────────  ────────────────────────────────────────────────────────────  ──────  ──────
 1  04-26 21:55  api-gateway   opus-4-7    refactor the auth middleware to support oauth2 + add tests    8.4k    ~$1.12
 2  04-26 21:48  data-pipeline opus-4-7    why is the etl job failing on parquet files larger than 2GB?  12k     ~$1.87
 3  04-26 21:42  web-app       sonnet-4-6  add a dark mode toggle to the settings page                   3.9k    ~$0.34
 4  04-26 21:36  api-gateway   opus-4-7    write integration tests for the rate limiter                  6.7k    ~$0.95
 5  04-26 21:28  data-pipeline opus-4-7    optimize the join query — currently takes 14s                 23k     ~$2.81
 6  04-26 21:14  ml-experiment sonnet-4-6  draft a notebook to compare three loss functions              4.2k    ~$0.41
 7  04-26 20:58  web-app       sonnet-4-6  fix the layout shift when the sidebar collapses               2.1k    ~$0.18
 8  04-26 20:42  api-gateway   opus-4-7    document the new webhook endpoints                            5.5k    ~$0.78
 9  04-26 20:31  cli-tool      opus-4-6    add --json output to all subcommands                          7.2k    ~$0.91
10  04-26 20:14  data-pipeline opus-4-7    investigate why the schema migration timed out                15k     ~$1.94

…showing 10 most-recent prompts. `--expand` for 50, `--all` for everything, `--limit N`, `--by-session` to group.
```

In a real terminal: bold header, dim separator, magenta opus / blue sonnet / green haiku, color-coded cost.

### `claude-burn detail`

Full breakdown for the current billing period: spent, budget, progress bar, sessions, prompts, model shares, last task. Run it to see.

### `claude-burn doctor`

Diagnose your setup, data sources, and freshness:

```
claude-burn doctor
  version:         0.1.0
  config:          ~/.config/claude-burn/config.toml (ok)
  db:              ~/.local/share/claude-burn/history.db (ok)
  transcripts dir: ~/.claude/projects (ok)
  budget:          $50.00/month, reset day 1
  pricing cache:   2026-04-26 21:42 UTC (0.5h ago) (TTL 24h)
  admin API key:   set (env or config)
  billed cost:     not synced — values are estimates labeled with ~
```

---

## Auto-display via Stop hook (recommended)

Add this to `~/.claude/settings.json` so every Claude Code task ends with a `[claude-burn]` line on stderr:

```json
{
  "hooks": {
    "Stop": [
      {
        "matcher": ".*",
        "hooks": [
          { "type": "command", "command": "claude-burn hook", "timeout": 8 }
        ]
      }
    ]
  }
}
```

After every Claude task:

```
[claude-burn] ~$12.48 / $50 [████░░░░░░] 25% | last: 4.2k tok | opus 83% sonnet 17%
```

The hook can never block your Claude task — 8-second budget, fails silently, always exits 0.

---

## Real billed cost (optional)

Estimates from local data are accurate within a few percent. For exact billed numbers from Anthropic:

1. Create an admin API key: <https://console.anthropic.com/settings/admin-keys>
2. Either:
   - `claude-burn init` — interactive prompt, securely stores key (chmod 0600)
   - `export ANTHROPIC_ADMIN_API_KEY=...` (env wins over config)
3. `claude-burn sync` — first manual sync (auto-refreshes every 6h after that)

After sync, `~` prefix drops everywhere: `~$12.48` becomes `$12.48` and is labeled `billed (admin API)`.

---

## Configuration

`~/.config/claude-burn/config.toml`:

```toml
[budget]
monthly_usd = 50.0
reset_day = 1            # 1-28; period spans reset_day → day before next reset_day

[display]
max_width = 120          # falls back to two lines if exceeded
show_model_share = true

[sources]
# transcripts_dir = "~/.claude/projects"

[cache]
billed_hours = 6         # admin API auto-refresh TTL
```

| env var | overrides |
|---|---|
| `CLAUDE_BURN_CONFIG_DIR` | config path |
| `CLAUDE_BURN_DATA_DIR` | data path |
| `CLAUDE_BURN_COLOR` | `0` to force off, `1` to force on, else auto (TTY) |
| `NO_COLOR` | disables color regardless |
| `ANTHROPIC_ADMIN_API_KEY` | wins over config-stored key |

---

## All commands

| command | purpose |
|---|---|
| `claude-burn` | alias for `status` |
| `claude-burn init` | create config + db, backfill, optional admin-key prompt |
| `claude-burn status` | compact one/two-line status |
| `claude-burn last` | most recent prompt only |
| `claude-burn history` | per-prompt table (default 10, `--expand`=50, `--all`, `--by-session`) |
| `claude-burn detail` | full breakdown of current billing period |
| `claude-burn doctor` | data sources, freshness, provenance |
| `claude-burn budgets` | view / set monthly budget + reset day |
| `claude-burn watch` | poll transcripts dir, print on change |
| `claude-burn sync` | force-refresh billed cost via Admin API |
| `claude-burn import-history` | rebuild local history from transcripts |
| `claude-burn hook` | Stop-hook entry point (used by Claude Code, not by hand) |

`--json` is supported on `status`, `last`, `detail`, `history`, `doctor`, `sync`.

---

## Provenance & honesty

| label | meaning |
|---|---|
| `~$12.48` | estimated cost |
| `$12.48` (no tilde) | billed via Anthropic Admin API |
| `budget: not set` | no budget configured (no fake "dollars left") |

**No estimated value is ever presented as billed.** `doctor` always tells you which one you're seeing and how stale it is.

---

## Uninstall

```bash
pip uninstall claude-burn
rm -rf ~/.config/claude-burn ~/.local/share/claude-burn ~/.claude-burn
```

---

## License

MIT — see [LICENSE](./LICENSE).
