← Back to Skills Marketplace
Agent Budget Governance
by
Nissan Dookeran
· GitHub ↗
· v1.0.0
301
Downloads
0
Stars
2
Active Installs
1
Versions
Install in OpenClaw
/install agent-budget-governance
Description
Trust-based budget system for multi-agent teams — daily token limits with automatic midnight resets, yellow/red/demotion thresholds, audit logging, and mesh...
README (SKILL.md)
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/\x3Cname>/BUDGET.json:
{
"daily_limit": 50000,
"today": "2026-03-01",
"used_today": 23450,
"consecutive_over_days": 0,
"demoted": false
}
Running the Audit
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
- Daily reset at midnight (configurable timezone)
- Yellow at 80% — logged, no action
- Red at 100% — logged, orchestrator alerted
- Demotion at 200% OR 3 consecutive days over budget
- 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
Usage Guidance
This skill contains useful local audit code, but the documentation and governance docs over-claim its enforcement capabilities. Before installing or running: 1) Inspect and test the script in a safe environment (backup ~/.openclaw/workspace/agents). 2) Note schema mismatch: ensure your existing BUDGET.json uses the fields the script expects (daily_limit_output_tokens, used_output_tokens, consecutive_overbudget_days, status, warnings, spawns) or update the script or files accordingly. 3) If you expect automatic spawn-blocking/demotion at the gateway (modifying openclaw.json or session spawn middleware), know that the provided script does not perform those changes — additional enforcement code or gateway middleware is required. 4) Run the script with --json or --reset-only in a sandbox to observe behavior and confirm it only updates local files. 5) If you plan to rely on demotion for security/cost control, implement or review the separate mechanism that enforces spawn restrictions (and audit it). 6) Because the AGENTS_DIR is hard-coded, confirm it matches your installation or modify the script to point to the correct workspace path. If you want me to, I can produce a short patch to (a) align the code with the SKILL.md demotion claim (e.g., safely modify openclaw.json with backups) or (b) make the script accept a configurable agents directory and schema mapping.
Capability Analysis
Type: OpenClaw Skill
Name: agent-budget-governance
Version: 1.0.0
The skill bundle implements a legitimate budget governance system for multi-agent environments, tracking token usage via local JSON files. The core logic in `scripts/budget_audit.py` is transparent, performing file-based audits and resets without any network access, shell execution, or unauthorized data access. The instructions provided in `SKILL.md` and `references/GOVERNANCE.md` are strictly aligned with the stated purpose of cost management and do not exhibit signs of malicious prompt injection or deceptive behavior.
Capability Assessment
Purpose & Capability
Name/description promise: a trust-based budget system that can demote agents by removing mesh spawn rights (editing openclaw.json). What’s delivered: a Python audit script that reads/writes per-agent BUDGET.json files and appends to a governance log. The script does NOT modify openclaw.json or gateway policies. Also the SKILL.md and references show different BUDGET.json field names than the script expects (documentation uses fields like daily_limit/used_today while the code expects daily_limit_output_tokens/used_output_tokens), which is an incoherence.
Instruction Scope
SKILL.md instructs running the audit and describes demotion removing subagents.allowAgents in openclaw.json; the runtime script only resets counters, logs warnings/demotions to its governance log, and updates BUDGET.json. There is no code to enforce spawn-blocking at the gateway or to modify openclaw.json — the instructions overstate enforcement scope.
Install Mechanism
No install spec (instruction-only) and only requires python3 on PATH. No external downloads or archive extraction. Low install risk.
Credentials
No environment variables or external credentials are requested. The script operates on a hard-coded local path (~/.openclaw/workspace/agents) which is proportional to a local governance tool, but the hard-coded path and AGENT_MAP may not match every user's layout and could cause it to silently ignore or overwrite files.
Persistence & Privilege
always:false and no network access are good. The script persists changes to per-agent BUDGET.json and governance/log.jsonl (expected for a budget auditor). However, the documentation claims changes to openclaw.json for demotion — if a user expects automatic mesh-revocation, that will not happen with the provided script. No indication the skill modifies other skills' config files or gains elevated privileges.
How to Use
- Make sure OpenClaw is installed (local or Docker)
- Run the install command in chat:
/install agent-budget-governance - After installation, invoke the skill by name or use
/agent-budget-governance - Provide required inputs per the skill's parameter spec and get structured output
Version History
v1.0.0
Initial release: trust-based budget system for multi-agent teams
- Implements daily token limits per agent with automatic midnight resets
- Provides warning (yellow) and alert (red) thresholds based on usage
- Supports agent demotion and privilege revocation after repeated or extreme overages
- Includes governance audit logging and easy integration with any OpenClaw multi-agent setup
- Works entirely with local files for privacy and security
Metadata
Frequently Asked Questions
What is 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... It is an AI Agent Skill for Claude Code / OpenClaw, with 301 downloads so far.
How do I install Agent Budget Governance?
Run "/install agent-budget-governance" in the OpenClaw or Claude Code chat to install it in one step — no extra setup required.
Is Agent Budget Governance free?
Yes, Agent Budget Governance is completely free (open-source). You can download, install and use it at no cost.
Which platforms does Agent Budget Governance support?
Agent Budget Governance is cross-platform and runs anywhere OpenClaw / Claude Code is available (cross-platform).
Who created Agent Budget Governance?
It is built and maintained by Nissan Dookeran (@nissan); the current version is v1.0.0.
More Skills