@bifrostlabs/cost-guardian

Real-time token cost tracking and budget enforcement for Claude Code. Uses Claude Code's hook system to monitor spend per session and per day, with configurable budgets and automatic blocking when thresholds are exceeded.

Features

• Automatic cost tracking — hooks into Claude Code's tool lifecycle to track every API call
• Per-session & daily budgets — configurable spend limits with warning and blocking thresholds
• Model-aware pricing — built-in rates for Opus, Sonnet, and Haiku (including cache pricing)
• SQLite persistence — local database tracks usage history across sessions
• Budget bar display — visual budget consumption indicator in session output
• Zero config start — sensible defaults ($20/day, $5/session), customize via JSON config

Quick Start

npm install @bifrostlabs/cost-guardian

Add hooks to your Claude Code settings.json:

{
  "hooks": {
    "SessionStart": [{ "command": "cost-guardian-session-start" }],
    "PreToolUse": [{ "command": "cost-guardian-pre-tool-budget" }],
    "PostToolUse": [{ "command": "cost-guardian-post-tool-tracker" }],
    "SessionEnd": [{ "command": "cost-guardian-session-end" }]
  }
}

Configuration

Config lives at ~/.cost-guardian/config.json (auto-created on first run):

{
  "daily_budget": 20.0,
  "session_budget": 5.0,
  "warn_threshold": 0.8,
  "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 | Budget % that triggers warnings | | block_threshold | 0.95 | Budget % that blocks new tool calls |

API

import {
  calculateCost,
  getPricing,
  sessionCost,
  todayCost,
  loadConfig,
} from "@bifrostlabs/cost-guardian";

// Calculate cost for a specific call
const cost = calculateCost("claude-sonnet-4-5-20250929", 1000, 500);

// Query accumulated costs
const today = todayCost(db);
const session = sessionCost(db, sessionId);

How It Works

1. SessionStart hook initializes a new session record in SQLite
2. PreToolUse hook checks current spend against budget — blocks if over threshold
3. PostToolUse hook records token usage and calculates cost using model-specific rates
4. SessionEnd hook finalizes session totals and displays a summary

License

MIT