✓ Verified 💻 Development ✓ Enhanced Data

Tokenguard

API cost guardian for AI agents.

Rating: 4.9 (359 reviews)
Downloads: 7,005 downloads
Version: 1.0.0

Overview

API cost guardian for AI agents.

Complete Documentation

View Source →

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

bash

clawhub install tokenguard

Or manually:

bash

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

Quick Start

bash

# 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	Set spending limit (e.g., set 50)
check	Check if estimated cost fits budget
log [desc]	Log a cost after API call
reset	Clear session spending
history	Show all logged entries
extend	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:

bash

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:

text

🚫 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:

python

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

Set realistic limits — Start with $10-20 for development
Check before expensive calls — Always check before big operations
Log everything — Even small costs add up
Use extend, not reset — Keep audit trail intact
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

Installation

Terminal bash


openclaw install tokenguard

Copied!

💻Code Examples

python3 scripts/tokenguard.py history

python3-scriptstokenguardpy-history.txt

## 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:

fi

fi.txt

## Budget Exceeded Alert

When a check would exceed your limit:

tokenguard override # One-time bypass

-tokenguard-override--one-time-bypass.txt

## Integration Pattern

For agents using paid APIs:

example.sh

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

example.sh

# 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

example.sh

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

example.txt

🚫 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

example.py

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 Options

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