cost-guardian — AI & Infrastructure Cost Tracker

Track, analyze, and optimize the total cost of running your AI agent and infrastructure. Budget alerts, spend forecasts, and concrete optimization recommendations.

Commands

Initialize

python scripts/cost-guardian.py init

Creates config and database in ~/.openclaw/workspace/costs/.

Track a Cost Entry

# Track API spend
python scripts/cost-guardian.py track --provider openai --amount 12.50 --currency USD --period monthly --category api

# Track infrastructure cost
python scripts/cost-guardian.py track --provider hetzner --amount 5.00 --currency EUR --period monthly --category hosting

# Track one-time cost
python scripts/cost-guardian.py track --provider cloudflare --amount 10.00 --currency USD --period once --category domain

# Track electricity
python scripts/cost-guardian.py track --provider electricity --amount 15.00 --currency EUR --period monthly --category power

Scan Token Usage from Gateway Logs

# Scan recent gateway logs for token consumption per model
python scripts/cost-guardian.py scan-tokens

# Scan specific days
python scripts/cost-guardian.py scan-tokens --days 7

Set Budget

# Monthly budget
python scripts/cost-guardian.py budget --monthly 50.00 --currency EUR

# Budget with alert threshold (alert at 80%)
python scripts/cost-guardian.py budget --monthly 50.00 --alert-pct 80

Cost Report

# Current month report
python scripts/cost-guardian.py report

# Weekly report
python scripts/cost-guardian.py report --period week

# JSON output
python scripts/cost-guardian.py report --json

# Specific month
python scripts/cost-guardian.py report --month 2026-02

Optimization Recommendations

# Get optimization suggestions
python scripts/cost-guardian.py optimize

# JSON output
python scripts/cost-guardian.py optimize --json

Forecast Spend

# Forecast next 3 months
python scripts/cost-guardian.py forecast

# Forecast next N months
python scripts/cost-guardian.py forecast --months 6

# JSON output
python scripts/cost-guardian.py forecast --json

Manage Subscriptions

# Add a subscription
python scripts/cost-guardian.py sub add --name "OpenRouter" --amount 20.00 --currency USD --cycle monthly --renews 2026-03-15 --category api

# List subscriptions
python scripts/cost-guardian.py sub list

# Remove a subscription
python scripts/cost-guardian.py sub remove --name "OpenRouter"

# Check upcoming renewals
python scripts/cost-guardian.py sub upcoming --days 14

Status Dashboard

# Quick status overview
python scripts/cost-guardian.py status

# JSON output  
python scripts/cost-guardian.py status --json

Categories

• api — AI model API costs (OpenAI, Anthropic, OpenRouter, etc.)
• hosting — VPS, cloud, domain, DNS
• power — Electricity for homelab
• subscription — SaaS subscriptions
• hardware — One-time hardware purchases
• other — Everything else

Output Modes

All commands support:

• Human-readable (default) — colored terminal output
• JSON (--json) — structured data for programmatic use

Cron Integration

Add to OpenClaw cron for automated cost tracking:

• Daily: scan-tokens to track API usage
• Weekly: report --period week for digest
• Monthly: report + forecast for full analysis
• On-demand: optimize when looking to cut costs

Data Storage

All data stored in ~/.openclaw/workspace/costs/:

• config.json — budget settings, preferences
• costs.db — SQLite database (entries, subscriptions, token scans)

Zero Dependencies

Pure Python 3 stdlib — no pip install needed. Uses sqlite3, json, datetime, pathlib.