claude-burn 0.1.1

Compact Claude usage tracking after each Claude task

claude-burn

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)

brew install ghosharkaprava8/claude-burn/claude-burn

Or, two-step:

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

pip / pipx / uv

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

Requires Python 3.11+.

---

Quick start

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:

{
  "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:

[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

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

---

License

MIT — see LICENSE.