cost-guardian

Cost Guardian

Real-time token cost tracking and budget enforcement for Claude Code.

See exactly what each session costs. Set daily and session budgets. Get warned before you overspend.

💰 Session: $2.34 | Today: $8.91 / $20.00 (45%)

The Problem

Claude Code doesn't show you what you're spending in real time. You find out at the end of the month when the bill arrives. By then you've burned through $200+ without realizing it.

The Solution

Cost Guardian uses Claude Code's hooks system to:

• Track every API call — input tokens, output tokens, cache reads, cache creation
• Calculate cost in real time — using Anthropic's published pricing for Opus, Sonnet, and Haiku
• Show running totals — session cost, daily cost, and budget percentage after every tool use
• Warn you at 80% — system message when approaching your budget limit
• Block at 95% — prevents further tool use when budget is exhausted
• Store history — SQLite database for querying past sessions and trends

Install

Option 1: Clone (recommended)

git clone https://github.com/bifrost-mcp/cost-guardian.git ~/.claude/tools/cost-guardian

Option 2: npm

npm install -g cost-guardian

If using npm, find the install path for the next step:

echo "$(npm root -g)/cost-guardian"

Configure Hooks

Add the following to your ~/.claude/settings.json. If using npm, replace ~/.claude/tools/cost-guardian with the path from the command above.

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": ".*",
        "hooks": [
          {
            "type": "command",
            "command": "bash ~/.claude/tools/cost-guardian/hooks/scripts/session-start-init.sh"
          }
        ]
      }
    ],
    "PreToolUse": [
      {
        "matcher": ".*",
        "hooks": [
          {
            "type": "command",
            "command": "bash ~/.claude/tools/cost-guardian/hooks/scripts/pre-tool-budget-check.sh"
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": ".*",
        "hooks": [
          {
            "type": "command",
            "command": "bash ~/.claude/tools/cost-guardian/hooks/scripts/post-tool-tracker.sh"
          }
        ]
      }
    ],
    "Stop": [
      {
        "matcher": ".*",
        "hooks": [
          {
            "type": "command",
            "command": "bash ~/.claude/tools/cost-guardian/hooks/scripts/session-end-summary.sh"
          }
        ]
      }
    ]
  }
}

Note: If you already have hooks in your settings.json, merge the arrays — don't replace them. Multiple hooks can coexist under the same event.

That's It

Cost Guardian activates automatically. You'll see cost tracking after your next tool call:

💰 Session: $0.12 | Today: $0.12 / $20.00 (1%)

Check Detailed Stats

Use the /cost command in any session:

=== CURRENT SESSION ===
Session ID: f8053578-cb...
Cost: $2.34
API calls: 47

=== TODAY ===
Total cost: $8.91
API calls: 203

=== THIS WEEK ===
Total cost: $34.67
API calls: 892

=== COST BY MODEL (TODAY) ===
Model              Calls  Cost     Input Tok  Output Tok
claude-opus-4-6    12     $5.23    45,200     8,300
claude-sonnet-4-5  156    $3.12    892,000    134,000
claude-haiku-4-5   35     $0.56    234,000    67,000

=== BUDGET STATUS ===
Daily:   $8.91 / $20.00  ████░░░░░░ 45%  🟢
Session: $2.34 / $5.00   ████░░░░░░ 47%  🟢

Configuration

Edit ~/.cost-guardian/config.json (created automatically on first run):

{
    "daily_budget": 20.00,
    "session_budget": 5.00,
    "warn_threshold": 0.80,
    "block_threshold": 0.95,
    "currency": "USD"
}

Setting	Default	Description
daily_budget	20.00	Maximum daily spend in USD
session_budget	5.00	Maximum per-session spend in USD
warn_threshold	0.80	Show warning at this % of budget
block_threshold	0.95	Block tool use at this % of budget

Budget Enforcement

Budget Used	Behavior
< 80%	Silent — cost shown after each tool call
80-95%	Warning — yellow alert with spend details
> 95%	Blocked — tool use denied with reason

To unblock, increase the budget in ~/.cost-guardian/config.json or wait for the next day (daily budget resets at midnight UTC).

How It Works

Cost Guardian uses Claude Code's hooks system to intercept lifecycle events:

• SessionStart — Initializes session tracking in SQLite
• PostToolUse — Reads the session transcript JSONL, extracts token counts from the last API response, calculates cost using Anthropic's pricing, logs to SQLite, shows running total
• PreToolUse — Checks current spend against budget thresholds, warns or blocks
• Stop — Finalizes session totals and shows summary with model breakdown

Pricing Table

Model	Input	Output	Cache Read	Cache Create
Opus 4.6	$15/M	$75/M	$1.50/M	$18.75/M
Sonnet 4.5	$3/M	$15/M	$0.30/M	$3.75/M
Haiku 4.5	$0.80/M	$4/M	$0.08/M	$1.00/M

Pricing is hardcoded in lib/pricing.sh and easy to update when Anthropic changes rates.

Data Storage

All data is stored locally at ~/.cost-guardian/:

~/.cost-guardian/
├── usage.db      # SQLite database with all usage records
└── config.json   # Your budget configuration

No data is sent anywhere. Everything stays on your machine.

Development

# Run tests
bash tests/run.sh

# Test with a real session (clone method)
# 1. Clone repo
# 2. Add hooks to settings.json pointing to your clone
# 3. Start a Claude Code session — hooks fire automatically

Project Structure

cost-guardian/
├── hooks/
│   ├── hooks.json              # Hook event reference
│   └── scripts/
│       ├── session-start-init.sh
│       ├── post-tool-tracker.sh
│       ├── pre-tool-budget-check.sh
│       └── session-end-summary.sh
├── commands/
│   └── cost.md                 # /cost slash command
├── skills/
│   └── cost-report/
│       └── SKILL.md            # Detailed cost report skill
├── data/
│   └── schema.sql              # SQLite schema
├── lib/
│   ├── pricing.sh              # Model pricing table
│   ├── db.sh                   # SQLite helpers
│   └── format.sh               # Output formatting
├── tests/
│   └── run.sh                  # Test suite
├── LICENSE
├── package.json
└── README.md

Requirements

• Claude Code (with hooks support)
• sqlite3 (pre-installed on macOS/Linux)
• jq (for JSON parsing — brew install jq on macOS)
• bash 4.0+

License

MIT