Budget Controls - Agents Squads

Overview

Budget controls prevent runaway agent costs. Every agent and squad has defined spending limits that trigger alerts, require approval, or halt execution. Three levels of budget control:

Level	Scope	Purpose
Per-Run	Single execution	Prevent expensive single runs
Daily	24-hour rolling	Cap daily spend per agent
Monthly	Calendar month	Overall cost governance

Agent Budget Configuration

Each agent’s .md file includes budget limits:

---
name: research-analyst
squad: intelligence
budget:
  per_run: 2.00     # Max USD per execution
  daily: 15.00      # Max USD per day
  monthly: 200.00   # Max USD per month
timeout: 120        # Minutes before force-stop
---

Required Fields

Field	Description	Enforcement
`budget.per_run`	Maximum cost per single execution	Hard limit - execution stops
`budget.daily`	Maximum daily spend	Soft limit - requires approval
`budget.monthly`	Maximum monthly spend	Hard limit - agent disabled
`timeout`	Maximum execution time (minutes)	Hard limit - process killed

Squad Budget Configuration

Squads have aggregate limits in SQUAD.md:

budget:
  daily_limit: 45       # USD - total for all agents
  monthly_limit: 450    # USD
  alert_threshold: 0.8  # Alert at 80% of daily limit

Alert Thresholds

Threshold	Action
80% of daily	Slack alert to squad channel
100% of daily	New executions paused, pending review
90% of monthly	Executive alert, planning required

How Budget Tracking Works

1. Pre-Execution Check

Agent triggered
    ↓
Check: daily spend + estimated cost < daily limit?
    ↓
No → Reject with "Budget exceeded" message
Yes → Proceed

2. During Execution

Every 30 seconds:
    ↓
Check: current run cost < per_run limit?
    ↓
No → Graceful stop, save progress
Yes → Continue

3. Post-Execution

Execution complete
    ↓
Record: tokens, cost, duration
    ↓
Update: daily/monthly aggregates
    ↓
Check thresholds, send alerts if needed

Monitoring Costs

CLI Commands

# Today's spend across all squads
squads cost

# Specific squad
squads cost --squad engineering

# Check agent budget status
squads budget engineering

# Full cost dashboard
squads dash token-economics

Dashboard Output

Token Economics

Today
518k tokens  │  873 calls  │  $38.67
Week   8.5M tokens  │  15109 calls  │  $780.52

Models: opus $748  sonnet $23  haiku $9

Efficiency
173k tokens/goal  │  3 goals done

Rate Limits
RPM  ━━━━━━━━━━  1.2/4000
TPM  ━━━━━━━━━━  732/2.4M
● Capacity for autonomous triggers

Cost-Based Routing

Route to cheaper models for appropriate tasks:

# In SQUAD.md
context:
  model:
    default: sonnet       # Standard work
    expensive: opus       # Architecture, complex reasoning
    cheap: haiku          # Data gathering, formatting

Routing Guidelines

Task Type	Recommended Model	Cost/1M tokens
Data gathering, summarization	Haiku	$0.25
Code review, analysis	Sonnet	$3.00
Architecture, complex reasoning	Opus	$15.00

Smart Triggers and Budget

Triggers can be budget-aware:

triggers:
  - name: daily-analysis
    agent: market-analyst
    condition: |
      SELECT
        (SELECT COALESCE(SUM(cost), 0)
         FROM trigger_executions
         WHERE squad = 'intelligence'
         AND created_at > CURRENT_DATE) < 40.00
    cooldown: 4 hours

This trigger only fires if the squad has budget remaining.

Budget Alerts

Slack Alert Format

⚠️ Budget Alert: engineering

Daily spend: $42.50 / $45.00 (94%)
Top consumers:
  - issue-solver: $28.40 (12 runs)
  - code-reviewer: $8.20 (3 runs)

Action: Review pending work, consider pausing non-critical agents

Email Alerts (Enterprise)

Monthly budget reports sent to configured addresses with:

Spend by squad
Spend by agent
Cost per goal achieved
Recommendations

Overriding Budget Limits

Temporary Override

For urgent work, use --use-api flag:

squads run engineering/issue-solver --use-api

This uses API credits instead of subscription quota, bypassing subscription limits but still tracking costs.

Permanent Adjustment

Edit the agent’s .md file:

budget:
  per_run: 5.00    # Increased from 2.00
  daily: 30.00     # Increased from 15.00

Requires PR and human review (policy ORG-005).

Best Practices

1. Set Conservative Defaults

Start with low limits. It’s easier to increase than recover from overspend.

2. Use Per-Run Limits

Prevent individual execution explosions. A bug in a loop can burn budget fast.

3. Monitor Efficiency

Track tokens per goal, not just total spend:

squads kpi insights

4. Review Weekly

squads cost --squad all --period week

Identify patterns, adjust budgets accordingly.

5. Alert Before Limit

Set alert_threshold: 0.8 to get warnings before hitting hard limits.

Subscription vs API

Mode	Source	Tracking	Limits
Subscription	Max plan quota	`squads dash`	Weekly reset
API	Pay-per-token	Anthropic dashboard	Monthly billing

Most organizations should use subscription for predictable costs. API mode for burst capacity.

# Check subscription capacity
squads dash

# Weekly:  █████████████░░░░░░░ 64% (resets Feb 1)
#          2.6M / 4.0M tokens

​Overview

​Agent Budget Configuration

​Required Fields

​Squad Budget Configuration

​Alert Thresholds

​How Budget Tracking Works

​1. Pre-Execution Check

​2. During Execution

​3. Post-Execution

​Monitoring Costs

​CLI Commands

​Dashboard Output

​Cost-Based Routing

​Routing Guidelines

​Smart Triggers and Budget

​Budget Alerts

​Slack Alert Format

​Email Alerts (Enterprise)

​Overriding Budget Limits

​Temporary Override

​Permanent Adjustment

​Best Practices

​1. Set Conservative Defaults

​2. Use Per-Run Limits

​3. Monitor Efficiency

​4. Review Weekly

​5. Alert Before Limit

​Subscription vs API