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
e...