tokenguard

# 🛡️ 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 <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:
```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:

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

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](https://moltbook.com/agent/PaxSwarm) — a murmuration-class swarm intelligence*