TokenGuard

API cost guardian for AI agents. Track spending, enforce limits, prevent runaway costs. Essential for any agent making paid API calls.

Security Scan

TokenGuard's code and instructions match its stated purpose (local session budgeting, checks, and logging) and it does not request unrelated credentials or network access — but the provided script text is truncated so full verification is incomplete.

Purpose & Capability

The name/description (API cost guardian) aligns with the included code and SKILL.md: the script implements set/check/log/history/reset/extend/override and stores state under ~/.tokenguard (or TOKENGUARD_DIR). No unrelated services, credentials, or system subsystems are requested.

Instruction Scope

Runtime instructions are scoped to running the local Python script and storing/retrieving JSON in its own directory. Integration guidance uses subprocess to call the script (expected). The SKILL.md does not instruct reading other system config, secrets, or sending data to external endpoints.

Install Mechanism

There is no automatic install action (instruction-only). Manual install steps simply copy the SKILL.md and the script; that is low-risk. The package declares a GitHub repository but does not pull remote code during install.

Credentials

No required environment variables or credentials are declared; SKILL.md documents optional env vars (TOKENGUARD_DIR, TOKENGUARD_DEFAULT_LIMIT, TOKENGUARD_WARNING_PCT) used only to configure storage and defaults. No secrets or external API keys are requested.

Persistence & Privilege

The skill writes only to its own directory (~/.tokenguard by default) and does not request always:true or modify other skills. It can be invoked autonomously (platform default), which is normal for skills; note that the 'override' feature allows a one-time bypass and could be invoked programmatically if an agent is permitted to run commands.

Assessment

TokenGuard appears coherent and limited to local budgeting: it reads/writes JSON under ~/.tokenguard and exposes check/log commands you can call from agents or scripts. Before installing, review the complete scripts/tokenguard.py file (the submitted copy was truncated), verify the repository/homepage match the distributed file, and confirm there are no hidden network calls or unexpected file accesses. Use a dedicated non-sensitive directory for TOKENGUARD_DIR, keep file permissions minimal, and be aware that an automated agent with permission to run the script could set the 'override' flag to bypass limits — ensure your agent's policy/control flow prevents unintended overrides.

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