Cost Guardian

Real-time budget enforcement, cost tracking, and optimization for Claude Code

Stop burning money on Claude API costs. Cost Guardian is a native Claude Code plugin that tracks your spending in real-time, enforces budgets, and helps you optimize token usage.

Why Cost Guardian?

Existing cost tracking tools are external apps (menu bar apps, CLI tools). Cost Guardian is the first native plugin that uses Claude Code hooks to:

• Warn you BEFORE expensive operations (not after)
• Enforce budgets with configurable strictness
• Track costs per session, project, and task
• Suggest optimizations based on your usage patterns

Average savings: 30-50% on Claude API costs

Quick Start

Installation

# Add the marketplace (if not already added)
/plugin marketplace add cost-guardian/cost-guardian

# Install the plugin
/plugin install cost-guardian

Or install directly from GitHub:

/plugin install https://github.com/Belkins/cost-guardian

First Use

# Set a session budget
/budget set 10

# View current costs anytime
/cost

# Get optimization suggestions
/cost-optimize

Features

1. Real-Time Cost Tracking

See exactly what you're spending as you work:

Cost Guardian: Session progress
  Total: $2.47 / $10.00 (24.7%)
  Tokens: 45,230 input / 8,456 output
  Most expensive: Edit src/app.ts ($0.38)

2. Budget Enforcement

Set limits and choose how strictly they're enforced:

# Warn mode (default)
/budget set 10

# Require confirmation when over budget
/budget set 10 --enforcement confirm

# Hard block when budget exceeded
/budget set 10 --enforcement block

3. Smart Alerts

Get notified at configurable thresholds:

Cost Guardian: BUDGET ALERT - 80% consumed
  Spent: $8.02 / $10.00
  Remaining: $1.98
  Suggestion: Use /cost-optimize for savings tips

4. Pre-Operation Warnings

The killer feature - know costs before they happen:

Cost Guardian: Expensive operation detected
  Tool: Read
  File: node_modules/package/bundle.js (2.4 MB)
  Estimated cost: $0.45

  This would consume 22% of your remaining budget.
  Proceed? [Y/n]

5. Optimization Suggestions

AI-powered recommendations to reduce costs:

/cost-optimize

Cost Guardian: OPTIMIZATION ANALYSIS

1. Redundant Reads Detected (-$0.24 potential)
   - src/utils/helpers.ts read 4 times
   - Suggestion: Reference in subsequent prompts

2. Model Optimization
   - 12 operations used Opus for simple tasks
   - Suggestion: Use Haiku for formatting
   - Potential savings: $0.89

3. Caching Opportunity
   - System prompt repeated 23 times
   - Enable prompt caching for 90% discount
   - Potential savings: $0.67/session

PROJECTED MONTHLY SAVINGS: $45-60

6. Shareable Reports

Show off your efficiency:

# Generate shareable report
/cost-share

# Get a badge for your README
/cost-share --format badge

[![Claude Code Efficiency: A+](https://cost-guardian.dev/badge/user/efficiency.svg)]

Commands

Configuration

Budget Scopes

# Session budget (resets each session)
/budget set 10

# Daily budget (resets at midnight)
/budget set 50 --scope daily

# Monthly budget (resets on 1st)
/budget set 500 --scope monthly

# Project budget (tracks per-project)
/budget set 100 --scope project

Alert Thresholds

Default alerts at 50%, 80%, 95%. Customize:

/budget alert 25,50,75,90

Enforcement Modes

How It Works

Cost Guardian uses Claude Code's native hook system:

┌─────────────────┐     ┌──────────────────┐     ┌─────────────────┐
│  SessionStart   │────▶│  Initialize      │────▶│  Load budgets   │
│     Hook        │     │  tracking        │     │  & pricing      │
└─────────────────┘     └──────────────────┘     └─────────────────┘

┌─────────────────┐     ┌──────────────────┐     ┌─────────────────┐
│  PreToolUse     │────▶│  Estimate cost   │────▶│  Check budget   │
│     Hook        │     │  before exec     │     │  Warn/Block     │
└─────────────────┘     └──────────────────┘     └─────────────────┘

┌─────────────────┐     ┌──────────────────┐     ┌─────────────────┐
│  PostToolUse    │────▶│  Track actual    │────▶│  Update totals  │
│     Hook        │     │  usage           │     │  Check alerts   │
└─────────────────┘     └──────────────────┘     └─────────────────┘

┌─────────────────┐     ┌──────────────────┐     ┌─────────────────┐
│  SessionEnd     │────▶│  Generate        │────▶│  Save history   │
│     Hook        │     │  summary         │     │  Update totals  │
└─────────────────┘     └──────────────────┘     └─────────────────┘

Pricing Data

Current Claude model pricing (updated January 2025):

Tool overheads (automatically included):

• Bash: +245 tokens
• Edit/Write: +700 tokens
• Web Search: $0.01/search

Data Storage

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

~/.claude/cost-guardian/
├── sessions/
│   ├── {session-id}.json    # Per-session data
│   └── current.json         # Active session link
├── budgets.json             # Budget configuration
└── history.json             # Daily/monthly aggregates

Privacy: All data stays on your machine. Sharing via /cost-share is explicit and opt-in.

Efficiency Scoring

Your efficiency score (A+ to F) is based on:

A+ = Top 5%    (>95 score)
A  = Top 15%   (85-94 score)
B  = Top 35%   (70-84 score)
C  = Top 60%   (50-69 score)
D  = Top 85%   (30-49 score)
F  = Bottom 15% (<30 score)

FAQ

Does this slow down Claude Code?

No. Hooks execute in <100ms. Cost estimation uses local calculations, not API calls.

How accurate are the cost estimates?

Estimates are within ~10% of actual costs. PostToolUse tracking captures actual token counts for precise totals.

Can I use this with my team?

Yes! Each team member runs the plugin locally. For team-wide budgets, consider combining with Anthropic's workspace spending limits.

Does it work with API keys or subscriptions?

Both. Cost tracking works regardless of how you're billed. Budget enforcement is most useful for API/pay-per-token usage.

What if I hit my budget mid-task?

Depending on enforcement mode:

• warn: You'll see a warning but can continue
• confirm: Each operation requires confirmation
• block: Operations are blocked; use /budget set <higher> to continue

Contributing

Contributions welcome! See CONTRIBUTING.md for guidelines.

# Clone the repo
git clone https://github.com/Belkins/cost-guardian.git

# Install for development
cd cost-guardian
/plugin install .

# Run tests
./test/run-tests.sh

Roadmap

• Team dashboards (aggregate team costs)
• Webhook notifications (Slack, Discord)
• Cost forecasting (ML-based projections)
• Model auto-routing (automatic Haiku/Sonnet/Opus selection)
• VS Code extension integration

License

MIT License - see LICENSE for details.

Author

Created by Vladyslav Podoliako

• Newsletter: Vlad's Newsletter - AI, startups, and building in public
• Website: vladyslavpodoliako.com

Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions

Save money. Ship faster. Use Cost Guardian.