cost-governor

# 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 inp...

# Cost Governor - Installation & Setup

Pre-flight cost control for OpenClaw subagent spawns. Prevents surprise API bills.

## Quick Install

```bash
# Via ClawHub (when published)
clawhub install cost-governor

# Or manual install
cd ~/.openclaw/workspace/skills
# Download from ClawHub or extract package
```

## First-Time Setup

1. **Create tracking file:**
```bash
mkdir -p ~/.openclaw/workspace/notes
cat > ~/.openclaw/workspace/notes/cost-tracking.md << 'EOF'
# Cost Tracking Log

## Multipliers
- Creative: 7.5x
- Research: 3x
- Technical: 2x
- Simple: 1.5x

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

2. **Set daily budget (optional):**
```bash
echo "DAILY_BUDGET=20.00" >> ~/.openclaw/workspace/.env
```

3. **Test it:**
Ask your agent: "Estimate cost for researching passive income on Opus"

## Usage

The skill activates automatically when:
- You ask to spawn a subagent
- You request a cost estimate
- Daily cron runs (if configured)

### Manual Cost Check

```
You: "How much would it cost to spawn a research agent on Opus?"
Agent: [reads SKILL.md, estimates using multipliers]
Agent: "Research task on Opus, ~3K tokens: $3.50 estimated (3x multiplier)"
```

### Pre-Flight Gate

```
You: "Research the best passive income methods"
Agent: "Estimated cost: $3.50 (Opus, research, 3x multiplier). Approve?"
You: "Yes"
Agent: [spawns, logs to cost-tracking.md]
```

## Configuration

### Adjust Multipliers

Edit `~/.openclaw/workspace/notes/cost-tracking.md`:

```markdown
## Multipliers
- Creative: 10x    # Your creative tasks run long
- Research: 2.5x   # You scope research tightly
```

Agent reads this file on each cost check.

### Set Budget Alert

Add to workspace `.env`:
```bash
DAILY_BUDGET=50.00
WEEKLY_BUDGET=300.00
```

Agent will warn when approaching limits.

## Integration with Cron (Optional)

Daily spend summary at 6 PM:

```bash
openclaw cron add \
  --name "Daily Cost Report" \
  --sch...