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: