🛡️ TokenGuard — API Cost Guardian

Protect your wallet from runaway API costs.

TokenGuard tracks your agent's spending per session, enforces configurable limits, and alerts you before you blow your budget.

Why TokenGuard?

AI agents can rack up serious API costs fast. One runaway loop = hundreds of dollars. TokenGuard gives you:

• Session-based tracking — Costs reset daily (or on demand)
• Hard limits — Actions blocked when budget exceeded
• Pre-flight checks — Verify budget BEFORE expensive calls
• Override controls — Extend limits or bypass when needed
• Full audit trail — Every cost logged with timestamps

Installation

clawhub install tokenguard

Or manually:

mkdir -p ~/.openclaw/workspace/skills/tokenguard
# Copy SKILL.md and scripts/tokenguard.py
chmod +x scripts/tokenguard.py

Quick Start

# Check current status
python3 scripts/tokenguard.py status

# Set a $20 limit
python3 scripts/tokenguard.py set 20

# Before an expensive call, check budget
python3 scripts/tokenguard.py check 5.00

# After the call, log actual cost
python3 scripts/tokenguard.py log 4.23 "Claude Sonnet - code review"

# View spending history
python3 scripts/tokenguard.py history

Commands

Exit Codes

• 0 — Success / within budget
• 1 — Budget exceeded (check command)
• 2 — Limit exceeded after logging

Use exit codes in scripts:

if python3 scripts/tokenguard.py check 10.00; then
    # proceed with expensive operation
else
    echo "Over budget, skipping"
fi

Budget Exceeded Alert

When a check would exceed your limit:

🚫 BUDGET EXCEEDED
╭──────────────────────────────────────────╮
│  Current spent:  $    4.0000            │
│  This action:    $   10.0000            │
│  Would total:    $   14.0000            │
│  Limit:          $   10.00              │
│  Over by:        $    4.0000            │
╰──────────────────────────────────────────╯

💡 Options:
   tokenguard extend 5    # Add to limit
   tokenguard set <amt>   # Set new limit
   tokenguard reset       # Clear session
   tokenguard override    # One-time bypass

Integration Pattern

For agents using paid APIs:

import subprocess
import sys

def check_budget(estimated_cost: float) -> bool:
    """Check if action fits budget."""
    result = subprocess.run(
        ["python3", "scripts/tokenguard.py", "check", str(estimated_cost)],
        capture_output=True
    )
    return result.returncode == 0

def log_cost(amount: float, description: str):
    """Log actual cost after API call."""
    subprocess.run([
        "python3", "scripts/tokenguard.py", "log",
        str(amount), description
    ])

# Before expensive operation
if not check_budget(5.00):
    print("Budget exceeded, asking user...")
    sys.exit(1)

# Make API call
response = call_expensive_api()

# Log actual cost
log_cost(4.23, "GPT-4 code analysis")

Configuration

Environment variables:

Cost Reference

Common API pricing (per 1M tokens):

Rule of thumb: 1000 tokens ≈ 750 words

Storage

Data stored in ~/.tokenguard/ (or TOKENGUARD_DIR):

• limit.json — Current limit configuration
• session.json — Today's spending + entries
• override.flag — One-time bypass flag

Best Practices

1. Set realistic limits — Start with $10-20 for development
2. Check before expensive calls — Always check before big operations
3. Log everything — Even small costs add up
4. Use extend, not reset — Keep audit trail intact
5. Monitor warnings — 80% threshold = time to evaluate

Changelog

v1.0.0

• Initial release
• Core commands: status, set, check, log, reset, history, extend, override
• Environment variable configuration
• JSON export for integrations
• Daily auto-reset

Built by PaxSwarm — a murmuration-class swarm intelligence