Agent Budget Controller

---

name: agent-budget-controller

description: "Control LLM API spending per agent. Set daily/weekly/monthly limits with real-time tracking and alerts."

license: "MIT-0"

metadata:

openclaw:

emoji: "💰"

requires:

bins: ["uv", "python3"]

---

# Agent Budget Controller

> **💰 Stop LLM cost overruns before they happen**

Track, limit, and alert on LLM API costs per agent with daily/weekly/monthly budgets.

What It Does

Quick Start

# Initialize
budget init

# Set limits
budget set --daily 3.00 --weekly 15.00 --monthly 50.00
budget set --agent ubik-pm --daily 1.00

# Log usage (manual - see Integration below)
budget log --agent ubik-pm --model "claude-sonnet-4-5" \
  --input-tokens 5000 --output-tokens 1500

# Check status
budget status
budget status --agent ubik-pm

# Check limits (exit code)
budget check  # exit 0=ok, 1=exceeded

Commands

| Command | Purpose |

|---------|---------|

| `init` | Initialize budget tracking |

| `set` | Set budget limits |

| `log` | Log API usage |

| `status` | Show current usage vs limits |

| `check` | Check if limits exceeded (exit code) |

| `report` | Generate detailed period report |

| `agents` | List agents with limits or activity |

| `pricing` | Show/update model pricing |

| `history` | Show recent usage history |

Supported Models

Built-in pricing for:

Custom models:

budget pricing --update --model my-model \
  --input-price 1.50 --output-price 5.00

Integration

OpenClaw Heartbeat

Add to `HEARTBEAT.md`:

## Budget Monitoring

Every 4 hours:
1. Check budget status: `budget status`
2. If any agent >90%, notify Director
3. If any exceeded, escalate immediately

Pre-call Hook (Future)

# In agent wrapper script
budget check --agent $AGENT_NAME || {
  echo "❌ Budget exceeded for $AGENT_NAME"
  exit 1
}

# Call LLM API...
# Log after call
budget log --agent $AGENT_NAME \
  --model "$MODEL" \
  --input-tokens $INPUT_TOKENS \
  --output-tokens $OUTPUT_TOKENS

Cron (Daily Report)

# Send daily report to Telegram
0 9 * * * budget report --period day | \
  openclaw msg --channel telegram --target @director

Alert Levels

| Usage | Level | Symbol | Action |

|-------|-------|--------|--------|

| <70% | OK | ✅ | Continue |

| 70-89% | Warning | ⚠️ | Monitor |

| 90-99% | Critical | 🔴 | Alert Director |

| ≥100% | Exceeded | 🚫 | Block calls |

Data Storage

~/.openclaw/budget/
├── config.json       # Budget limits
├── pricing.json      # Model pricing (optional override)
└── usage.jsonl       # Append-only usage log

**Privacy**: All data stored locally. No network calls.

Examples

See [EXAMPLE.md](./EXAMPLE.md) for complete usage scenarios.

Testing

cd ~/ubik-collective/systems/ubik-pm/skills/agent-budget-controller
python3 tests/test_budget.py

Security

Safe for ClawHub distribution.

License

MIT-0 (public domain equivalent)