Skip to main content

​
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:
LevelScopePurpose
Per-RunSingle executionPrevent expensive single runs
Daily24-hour rollingCap daily spend per agent
MonthlyCalendar monthOverall 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

FieldDescriptionEnforcement
budget.per_runMaximum cost per single executionHard limit - execution stops
budget.dailyMaximum daily spendSoft limit - requires approval
budget.monthlyMaximum monthly spendHard limit - agent disabled
timeoutMaximum 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

ThresholdAction
80% of dailySlack alert to squad channel
100% of dailyNew executions paused, pending review
90% of monthlyExecutive 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 TypeRecommended ModelCost/1M tokens
Data gathering, summarizationHaiku$0.25
Code review, analysisSonnet$3.00
Architecture, complex reasoningOpus$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

ModeSourceTrackingLimits
SubscriptionMax plan quotasquads dashWeekly reset
APIPay-per-tokenAnthropic dashboardMonthly 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