cost-governor

name	cost-governor
version	1.0.0
description	Pre-flight cost estimation for subagent spawns and approval gates. Prevents API overspend and surprise billing. Budget control for sessions_spawn calls. Daily spend tracking. Essential for multi-agent OpenClaw deployments.
homepage	https://clawhub.com
changelog	Initial release - Pre-flight gates, historical multipliers, spend tracking
metadata	{"openclaw":{"emoji":"💰","requires":{"bins":[]},"os":["linux","darwin","win32"]}}

Cost Governor - Subagent Cost Control

Pre-flight cost checks before spawning subagents. Tracks spend. Gates expensive operations. Prevents surprise $300+ bills.

Files Included

• SKILL.md — This file (agent instructions)
• README.md — Human-readable setup guide
• cost-tracking-template.md — Copy this to notes/cost-tracking.md to get started
• lib/cost-tracker.js — Core estimation and logging library
• bin/cost-summary.js — CLI: daily/monthly spend summary

Problem Solved

You spawn a subagent for "research passive income ideas" on Opus. 30 minutes later: $12 gone. This skill estimates cost before execution, requires approval for expensive tasks (>$0.50), and tracks all spend.

When to Use

• Before spawning any subagent — estimate cost, log it
• Daily spend review — summarize costs vs budget
• Post-task reconciliation — compare estimated vs actual

Core Rules

1. Every subagent spawn >$0.50 estimated requires explicit user approval
2. All spawns get logged to $WORKSPACE/notes/cost-tracking.md
3. Estimates use multipliers from historical data (see Cost Model)
4. No silent expensive operations — always surface cost before execution

Cost Model

Based on historical data from cost-tracking.md:

Task Type	Base Estimate	Multiplier	Effective Estimate
Creative (open-ended)	Token estimate	7.5x	Apply to all creative tasks
Research (bounded)	Token estimate	3x	Web search + synthesis
Technical (structured)	Token estimate	2x	Code, config, structured output
Simple (template)	Token estimate	1.5x	Fill-in, short responses

Model cost rates (approximate per 1K tokens):

• Claude Opus: ~$0.075 input / $0.375 output
• Claude Sonnet: ~$0.003 input / $0.015 output
• GPT-4: ~$0.03 input / $0.06 output
• Grok 4.1 Fast Reasoning: ~$0.003 input / $0.015 output
• Claude Haiku 4.5: ~$0.0008 input / $0.004 output

Estimation Formula

estimated_cost = (estimated_output_tokens / 1000) * output_rate * task_multiplier

Example:

• Task: Creative writing (5000 tokens estimated on Opus)
• Calculation: (5000 / 1000) * $0.375 * 7.5 = $14.06
• Action: Require approval (>$0.50 threshold)

Setup

1. Create cost tracking file:

mkdir -p ~/.openclaw/workspace/notes
touch ~/.openclaw/workspace/notes/cost-tracking.md

2. Add header to cost-tracking.md:

# Cost Tracking Log

| Date | Task | Model | Est. | Actual | Ratio | Notes |
|------|------|-------|------|--------|-------|-------|

3. Set your daily budget (optional):

echo "DAILY_BUDGET=20.00" >> ~/.openclaw/workspace/.env

Usage

Pre-Flight Check (Before Spawning)

User: "Research passive income methods"
Agent: Checking cost... Estimated $3.50 (Research task, Opus, ~3K tokens * 3x multiplier). Approve?
User: Yes
Agent: [spawns, logs to cost-tracking.md]

Daily Spend Dashboard

Run manually or via cron:

## Daily Spend — 2026-02-21
| Task | Model | Est. | Actual | Ratio |
|------|-------|------|--------|-------|
| PassiveIncomeResearch | Opus | $3.50 | $4.20 | 1.2x |
| AIHardwareResearch | Sonnet | $0.80 | $0.65 | 0.8x |
**Total:** $4.30 est / $4.85 actual
**Budget remaining:** $15.15 / $20.00 daily

Post-Task Reconciliation

After each subagent completes:

1. Check actual cost (if available via /status)
2. Log to cost-tracking.md
3. Update multipliers if ratio is consistently off

Triggers

• Pre-spawn gate: Before sessions_spawn, estimate and log. If >$0.50, ask user.
• Cron (daily, optional): Summarize daily spend, flag overruns.
• Post-task: Log actual cost, update multipliers if data available.

Approval Gate Flow

1. Estimate cost using model + task type + multiplier
2. If estimate ≤ $0.50 → proceed, log silently
3. If estimate > $0.50 → present estimate to user, wait for "approve" / "yes"
4. Log decision (approved/rejected/modified) to tracking file

Budget Alerts

Set a daily budget cap. When spend exceeds it, the agent stops spawning and notifies you.

Setup: Add to your workspace config or mention it in system prompt:

"Daily API budget: $XX. Stop spawning subagents if estimated total exceeds this."

Cron-based daily summary (optional): Add to your cron:

# Daily cost summary at 11 PM
0 23 * * * node ~/.openclaw/workspace/skills/cost-governor/bin/cost-summary.js --daily

Anti-Patterns (What NOT to Do)

• ❌ Spawning Opus for simple lookups (use Sonnet or Haiku)
• ❌ Open-ended creative tasks without cost ceiling ("write a novel")
• ❌ Multiple subagents when one suffices
• ❌ Skipping post-task reconciliation
• ❌ Ignoring consistent ratio mismatches (update multipliers!)

Advanced: Custom Multipliers

Edit multipliers in your cost-tracking.md header:

## Multipliers (Updated 2026-02-21)
- Creative: 10x (our tasks run long)
- Research: 2.5x (bounded queries)

Agent reads these on each check.

Integration with Other Skills

• sessions_spawn: Always run cost check before spawning
• AGENTS.md: Log cost in agent entry ("Last used: $X.XX")
• Cron jobs: Wrap expensive recurring tasks with cost gates

Troubleshooting

Q: Estimates are consistently off A: Update multipliers in cost-tracking.md based on actual ratios.

Q: How do I get actual costs? A: Use /status after subagent completes, or check provider dashboard.

Why This Matters

Real story from r/LocalLLM (Jan 2026):

"Left my OpenClaw agent running overnight. Spawned 8 research subagents on Opus. Woke up to $340 API bill. This skill would've saved me."

Don't be that person.

---

Author: OpenClaw Community
License: MIT
Requires: OpenClaw with subagent support, notes/ directory