Documentation Index
Fetch the complete documentation index at: https://docs.agents-squads.com/llms.txt
Use this file to discover all available pages before exploring further.
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
Budget Alerts
⚠️ 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
Permanent Adjustment
Edit the agent’s .md file:
budget:
per_run: 5.00 # Increased from 2.00
daily: 30.00 # Increased from 15.00
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:
4. Review Weekly
squads cost --squad all --period week
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 |
# Check subscription capacity
squads dash
# Weekly: █████████████░░░░░░░ 64% (resets Feb 1)
# 2.6M / 4.0M tokens
