Never get surprised by your Claude bill again. Token + cost tracker with hard limits, alerts, and per-project budgets.

npm i -g claude-budget
claude-budget init

---

💸 The horror story

You hand Claude Code a big refactor. You step away. You come back to a $73 bill for one afternoon, because Claude looped on a hard problem 200 times.

claude-budget prevents this. It tracks every token, every dollar, in real-time — and stops Claude when you hit your limit.

---

⚡ Setup (60 seconds)

# Install
npm i -g claude-budget

# Initialize for current project
claude-budget init

# Set a budget
claude-budget set --daily 5.00 --monthly 100.00 --per-session 2.00

That's it. The hook is automatically wired into your Claude Code settings.

---

📊 What it does

Every time Claude completes a tool call, the hook:

1. Reads the token count from the response
2. Multiplies by the model's per-token cost
3. Adds to running totals (session / day / month / project)
4. Aborts the session if any limit is exceeded
5. Sends an alert at 80% of any limit

$ claude-budget status
╭──────────────────────────────────────────────╮
│  📊 Claude Code Spend                         │
├──────────────────────────────────────────────┤
│  This session:  $0.42 / $2.00   (21%) ▓░░░░ │
│  Today:         $3.18 / $5.00   (64%) ▓▓▓░░ │
│  This month:    $47.20 / $100   (47%) ▓▓░░░ │
│  This project:  $19.40 / $50.00 (39%) ▓▓░░░ │
├──────────────────────────────────────────────┤
│  By model:                                    │
│   claude-opus-4-7:    $2.10                   │
│   claude-sonnet-4-6:  $0.85                   │
│   claude-haiku-4:     $0.23                   │
╰──────────────────────────────────────────────╯

---

🔔 Alerts

Hook into Slack/Discord/Telegram/Email:

# ~/.claude-budget/config.yaml
alerts:
  - threshold: 80%
    channels: [slack]
  - threshold: 95%
    channels: [slack, email]
  - on_hard_stop:
    channels: [slack, email, sms]

channels:
  slack:
    webhook: ${SLACK_WEBHOOK_URL}
  email:
    to: you@example.com
  telegram:
    bot_token: ${TELEGRAM_BOT_TOKEN}
    chat_id: ${TELEGRAM_CHAT_ID}

---

🛡️ Hard stops

When a limit is hit, the hook sends a "REFUSE" signal back to Claude Code, which:

• Prevents the next tool call
• Shows you a clear message
• Logs the stop event
• Leaves the project in a clean state (no half-applied edits)

You can override:

claude-budget override --session    # Allow this session to exceed
claude-budget override --until tomorrow

---

📈 Reports

# Daily summary
claude-budget report --period today

# Detailed breakdown
claude-budget report --since 7d --by project,model

# CSV export
claude-budget report --csv > spend.csv

# Most expensive sessions
claude-budget report --top 10 --sort cost

---

👥 Team Mode

For organizations:

claude-budget team init --org acme-corp
# - Centralizes budgets across all team members
# - Per-user limits
# - Per-project budgets
# - Admin dashboard

Admin dashboard runs at claude-budget dashboard:

Team: acme-corp
─────────────────────────────────────────
  Total this month: $1,847 / $5,000
  Top spenders:
    1. alice@acme.com    $412 / $500   ✓
    2. bob@acme.com      $389 / $500   ✓
    3. carol@acme.com    $521 / $500   ⚠ OVER
─────────────────────────────────────────

---

🧮 Pricing data

The CLI ships with up-to-date Anthropic pricing for all current models. Updates automatically every 24h from the official Anthropic API pricing endpoint.

If you use a custom proxy, set:

pricing_override:
  claude-opus-4-7:
    input_per_million: 15.00
    output_per_million: 75.00

---

🎯 Pro tip

Pair this with claude-code-prompts's model-selector hook to auto-downgrade trivial tasks to Haiku — you'll cut your bill by 40-60% with no quality loss on the easy stuff.

---

📜 License

MIT.

---

Star ⭐ before your next AI bill surprises you.