# Agent Budget Governance

> Trust-based budget system for multi-agent teams — daily token limits with automatic midnight resets, yellow/red/demotion thresholds, audit logging, and mesh privilege revocation. Use when running multiple AI agents that share API budgets and need spend controls. Works with any OpenClaw multi-agent setup.

- Skill: `dvcrn/agent-budget-governance` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add dvcrn/agent-budget-governance`
- Raw SKILL.md: https://api.skillmd.com/api/skills/dvcrn/agent-budget-governance/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: dvcrn (https://skillmd.com/u/dvcrn)
- Updated: 2026-09-08
- Page: https://skillmd.com/skills/dvcrn/agent-budget-governance

---


# Agent Budget Governance

Prevent runaway API spending in multi-agent systems. Each agent gets a daily output token budget. Exceed it and you get warnings. Keep exceeding it and you lose mesh spawn privileges.

## How It Works

```
Agent completes task → tokens logged to BUDGET.json
                          ↓
Heartbeat runs budget_audit.py
                          ↓
├── Under 80%: ✅ Green — business as usual
├── 80-100%: 🟡 Yellow — warning logged
├── 100-200%: 🔴 Red — alert to orchestrator
└── 200%+ or 3 consecutive days over: ⛔ Demotion — mesh privileges revoked
```

## Budget File Format

Each agent has `agents/<name>/BUDGET.json`:

```json
{
  "daily_limit": 50000,
  "today": "2026-03-01",
  "used_today": 23450,
  "consecutive_over_days": 0,
  "demoted": false
}
```

## Running the Audit

```bash
python3 scripts/budget_audit.py          # Full audit with alerts
python3 scripts/budget_audit.py --json   # Machine-readable output
python3 scripts/budget_audit.py --reset-only  # Just reset daily counters
```

## Governance Rules

1. **Daily reset** at midnight (configurable timezone)
2. **Yellow at 80%** — logged, no action
3. **Red at 100%** — logged, orchestrator alerted
4. **Demotion at 200%** OR 3 consecutive days over budget
5. **Rehabilitation** — demoted agent must go 7 clean days, then orchestrator manually restores privileges

## Demotion Mechanics

Demotion removes an agent's `subagents.allowAgents` list in `openclaw.json`, preventing them from spawning other agents. They can still be spawned by the orchestrator.

## Files

- `scripts/budget_audit.py` — Audit script (run from heartbeat or cron)
- `references/GOVERNANCE.md` — Full governance framework documentation