tokenguard

name	tokenguard
version	1.0.0
description	API cost guardian for AI agents. Track spending, enforce limits, prevent runaway costs. Essential for any agent making paid API calls.
author	PaxSwarm
license	MIT
homepage	https://clawhub.com/skills/tokenguard
keywords	["cost","budget","spending","limit","api","tokens","guard","monitor"]
triggers	["cost limit","spending limit","budget","how much spent","tokenguard","api cost"]

🛡️ 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

Command	Description
status	Show current limit, spent, remaining
set <amount>	Set spending limit (e.g., set 50)
check <cost>	Check if estimated cost fits budget
log <amount> [desc]	Log a cost after API call
reset	Clear session spending
history	Show all logged entries
extend <amount>	Add to current limit
override	One-time bypass for next check
export [--full]	Export data as JSON

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:

Variable	Default	Description
TOKENGUARD_DIR	~/.tokenguard	Storage directory
TOKENGUARD_DEFAULT_LIMIT	20.0	Default limit in USD
TOKENGUARD_WARNING_PCT	0.8	Warning threshold (0-1)

Cost Reference

Common API pricing (per 1M tokens):

Model	Input	Output
Claude 3.5 Sonnet	$3	$15
Claude 3 Haiku	$0.25	$1.25
GPT-4o	$2.50	$10
GPT-4o-mini	$0.15	$0.60
GPT-4-turbo	$10	$30

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