Cost Guardian

The only Claude Code cost tool that tells you WHERE you're wasting money and HOW to stop.

Other tools show what you spent. Cost Guardian shows what you wasted, what you got for it, and what you could have saved — with an efficiency score, ROI metrics, and model savings calculator that no other tool has.

Zero setup. No Docker. No Grafana. Just install and go.

What Makes This Different

Every cost tracking tool shows you a number. Cost Guardian gives you intelligence:

Feature	Cost Guardian	ccusage	claude-code-otel	Built-in /cost
Real-time tracking	✅	❌ (post-hoc)	✅	✅
Budget guardrails	✅	❌	❌	❌
Waste detection	✅	❌	❌	❌
Efficiency score	✅	❌	❌	❌
Cost-per-line ROI	✅	❌	❌	❌
Model savings calculator	✅	❌	❌	❌
Anomaly detection	✅	❌	❌	❌
GitHub badge	✅	❌	❌	❌
Per-branch costs	✅	❌	❌	❌
Multi-model comparison	✅	❌	❌	❌
CSV/JSON export	✅	✅	✅	❌
Zero setup	✅	✅	❌ (Docker)	✅

Insights Engine (No Other Tool Has This)

Efficiency Score

Every session gets a score from 0-100 showing how efficiently you're spending:

Efficiency Score: 68/100
██████████████░░░░░░ Good

Wasted: $1.43 of $4.71 (30%)
  14 redundant file reads ($0.82)
  3 failed/empty bash commands ($0.34)
  2 calls were 3x+ more expensive than average ($0.27)

Cost-Per-Line ROI

Know what you're getting for your money:

Cost per line:    $0.03/line
Lines added:      +247
Lines removed:    -89
Cost per commit:  $1.18/commit

Model Savings Calculator

See how much you could save with different models:

Current spend:    $4.71
Cheapest option:  $1.02 (Claude Haiku 4.5)
Potential saving: $3.69 (78% cheaper)

Anomaly Detection

Catches runaway sessions before they drain your limits:

 ANOMALY: 3.2x your average session cost
This session: $14.20 | Average: $4.40
Top driver: Agent ($9.80, 4x)

GitHub Badge

Add your AI development cost to your README:

![AI Dev Cost](https://img.shields.io/badge/AI_Dev_Cost-$142-2ea44f)

The Problem

Every Claude Code user has been there:

"Why did my session use 80% of my daily limit in 20 minutes?"
"How much did that refactor actually cost me?"
"I wish I knew this feature would cost $15 before I started"

There's no built-in way to see what you're spending as you spend it. Existing solutions require Docker, Grafana, or OpenTelemetry infrastructure. Most developers just... guess.

The Solution

Cost Guardian is a Claude Code plugin that gives you full cost visibility with zero setup:

╔══════════════════════════════════════════════╗
║          COST GUARDIAN - Session Report      ║
╠══════════════════════════════════════════════╣
║  Total Cost:     $2.41                       ║
║  Total Tokens:   12.3K                       ║
║  Duration:       18.2 min                    ║
║  Burn Rate:      $0.13/min                   ║
╠══════════════════════════════════════════════╣
║  Budget:         $5.00 (hard)                ║
║  Used:           ████████████░░░░░░░░  48%   ║
║  Remaining:      $2.59                       ║
║  Time to limit:  ~20 min                     ║
╠══════════════════════════════════════════════╣
║  Per-Tool Breakdown                          ║
╠══════════════════════════════════════════════╣
║  Agent        ███████████████  $1.20 ( 3x)   ║
║  Read         ████████         $0.62 (28x)   ║
║  Edit         █████            $0.34 (12x)   ║
║  Bash         ███              $0.18 ( 8x)   ║
║  Grep         ██               $0.07 (15x)   ║
╚══════════════════════════════════════════════╝

Features

Real-Time Cost Tracking

Every tool call is automatically tracked via hooks. No manual logging. No configuration.

Budget Guardrails

Set spending limits that actually enforce themselves:

Hard mode: Blocks tool calls when budget is exceeded
Soft mode: Warns you but lets work continue
Scopes: per-session, daily, weekly, monthly

Pre-Task Cost Estimation

Before starting work, get a cost prediction:

/cost-estimate add user authentication with OAuth

Cost Estimate: Add user authentication with OAuth

Complexity:    High
Est. Reads:    15-25 files
Est. Edits:    8-12 files
Est. Tools:    60-90 total tool calls

Estimated Cost:
  Sonnet 4.6:  $2.50 - $5.00
  Opus 4.6:    $12.00 - $25.00

Spending Reports

Beautiful ASCII reports with trend analysis:

/cost-report daily

Shows daily spend charts, budget status bars, and week-over-week trends.

Status Line

See your running cost at a glance:

$2.41 | 12.3K tok | ~$0.13/min

Installation

Quick Install

claude plugin marketplace add Manavarya09/cost-guardian
claude plugin install cost-guardian

Manual Install

git clone https://github.com/Manavarya09/cost-guardian.git ~/.claude/plugins/cost-guardian

Then add to your Claude Code settings (~/.claude/settings.json):

{
  "hooks": {
    "SessionStart": [
      {
        "hooks": [{
          "type": "command",
          "command": "bash ~/.claude/plugins/cost-guardian/hooks/session-start.sh"
        }]
      }
    ],
    "PreToolUse": [
      {
        "hooks": [{
          "type": "command",
          "command": "bash ~/.claude/plugins/cost-guardian/hooks/budget-guard.sh"
        }]
      }
    ],
    "PostToolUse": [
      {
        "hooks": [{
          "type": "command",
          "command": "bash ~/.claude/plugins/cost-guardian/hooks/track-usage.sh"
        }]
      }
    ]
  }
}

Usage

Check Current Costs

/cost-guardian

Set a Budget

/cost-guardian budget $10/session        # Hard stop at $10
/cost-guardian budget $25/daily soft     # Soft warning at $25/day
/cost-guardian budget $100/weekly hard   # Hard stop at $100/week

Override a Budget Block

/cost-guardian resume

Get a Cost Estimate

/cost-estimate fix the authentication bug in login.ts
/cost-estimate refactor the entire API layer to use async/await

View Reports

/cost-report              # Current session (with model + expensive call breakdown)
/cost-report daily        # Last 7 days (with averages + projected monthly)
/cost-report weekly       # Last 4 weeks
/cost-report monthly      # Last 30 days
/cost-report branch       # Cost per git branch

Export Data

/cost-guardian export csv ~/costs.csv    # Export all data as CSV
/cost-guardian export json ~/costs.json  # Export all data as JSON

View/Customize Multipliers

/cost-guardian multipliers  # Show current tool estimation multipliers

Cost Insights

/cost-insights              # Full report: efficiency score, waste, ROI, savings, anomalies
/cost-insights waste        # Detailed waste breakdown (redundant reads, failed commands)
/cost-insights roi          # Cost-per-line and cost-per-commit ROI
/cost-insights savings      # Model savings calculator (Opus vs Sonnet vs Haiku)
/cost-insights anomaly      # Anomaly detection — flags runaway sessions
/cost-insights badge        # Generate a GitHub badge for your README

Reset Session Tracking

/cost-guardian reset

How It Works

Cost Guardian uses Claude Code's hook system to intercept tool calls:

PreToolUse hook (budget-guard.sh): Before each tool call, checks your spending against budget limits. Blocks or warns if exceeded.
PostToolUse hook (track-usage.sh): After each tool call, estimates token usage from the tool's input/output and logs it to a local SQLite database.
Skills: Four slash commands (/cost-guardian, /cost-estimate, /cost-report, /cost-insights) that query the database and generate reports.

Token Estimation

Since Claude Code doesn't expose exact per-tool token counts, Cost Guardian estimates them using:

Character count / 4 (industry-standard chars-per-token ratio)
Tool-specific multipliers (Agent calls cost ~3x more than simple reads)
Calibrated against real-world usage data

Estimates are typically within 15-20% of actual costs.

Data Storage

All data stays local in ~/.cost-guardian/:

usage.db — SQLite database with all tracked usage
config.json — Your budget settings and preferences

No data is ever sent externally. No telemetry. No cloud.

Configuration

Default config is created at ~/.cost-guardian/config.json on first run:

{
  "budgets": {
    "session": { "limit": 5.00, "mode": "hard" },
    "daily": { "limit": 25.00, "mode": "soft" },
    "weekly": { "limit": 100.00, "mode": "soft" },
    "monthly": { "limit": 400.00, "mode": "soft" }
  },
  "notifications": {
    "warn_at_percent": [50, 75, 90]
  },
  "tracking": {
    "group_by_branch": true,
    "estimate_multiplier": 1.0
  }
}

Configuration Options

Setting	Description	Default
`budgets.<scope>.limit`	Spending limit in USD	Varies
`budgets.<scope>.mode`	`"hard"` (blocks) or `"soft"` (warns)	`"hard"`
`notifications.warn_at_percent`	Warning thresholds (% of budget)	`[50, 75, 90]`
`tracking.group_by_branch`	Track costs per git branch	`true`
`tracking.estimate_multiplier`	Adjust estimates up/down	`1.0`

Supported Models

Model	Input Cost	Output Cost
Claude Opus 4.6	$15/M tokens	$75/M tokens
Claude Sonnet 4.6	$3/M tokens	$15/M tokens
Claude Haiku 4.5	$0.80/M tokens	$4/M tokens

Pricing auto-detects the active model. Update data/pricing.json to add new models.

Requirements

Claude Code (any version with hook support)
sqlite3 (pre-installed on macOS and most Linux distros)
Node.js (ships with Claude Code)

FAQ

Q: How accurate are the cost estimates? A: Within 15-20% of actual API costs. The estimation uses character-to-token ratios and tool-specific multipliers calibrated against real usage. For exact tracking, Anthropic's OpenTelemetry integration provides precise numbers.

Q: Does this work with Claude Max/Pro subscriptions? A: Yes. While Max/Pro users don't pay per-token, Cost Guardian helps you understand your usage patterns and why you might be hitting rate limits.

Q: Will this slow down my Claude Code sessions? A: No. Hooks run in ~50ms. The SQLite queries are sub-millisecond. You won't notice any difference.

Q: Where is my data stored? A: Everything stays in ~/.cost-guardian/ on your local machine. Nothing is sent anywhere.

Q: Can I export my data? A: The SQLite database at ~/.cost-guardian/usage.db can be queried directly with any SQLite client or imported into spreadsheets/dashboards.

Contributing

Contributions welcome! Areas where help is needed:

~~CSV/JSON export commands~~ (shipped in v2.0)
~~Per-branch cost tracking~~ (shipped in v2.0)
~~Efficiency scoring and waste detection~~ (shipped via /cost-insights)
More accurate token estimation per tool type
Team/shared budget features
Integration with Anthropic's Usage API for exact costs
Dashboard UI (terminal-based)
Slack/Discord notifications on budget warnings
Burn rate alerts (warn when session is consuming budget unusually fast)

License

MIT License. See LICENSE for details.

Stop guessing. Start tracking.

Name		Name	Last commit message	Last commit date
Latest commit History 48 Commits
.claude-plugin		.claude-plugin
.github		.github
data		data
examples		examples
hooks		hooks
scripts		scripts
skills		skills
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
install.sh		install.sh
package.json		package.json

Folders and files

Latest commit

History

Repository files navigation

Cost Guardian

What Makes This Different

Insights Engine (No Other Tool Has This)

Efficiency Score

Cost-Per-Line ROI

Model Savings Calculator

Anomaly Detection

GitHub Badge

The Problem

The Solution

Features

Real-Time Cost Tracking

Budget Guardrails

Pre-Task Cost Estimation

Spending Reports

Status Line

Installation

Quick Install

Manual Install

Usage

Check Current Costs

Set a Budget

Override a Budget Block

Get a Cost Estimate

View Reports

Export Data

View/Customize Multipliers

Cost Insights

Reset Session Tracking

How It Works

Token Estimation

Data Storage

Configuration

Configuration Options

Supported Models

Requirements

FAQ

Contributing

License

About

Topics

Resources

License

Contributing

Uh oh!

Stars

Watchers

Forks

Releases 2

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages