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

# Budget Controls

> Cost limits and spending governance for agent execution

## 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:

```yaml theme={null}
---
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`:

```yaml theme={null}
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

```bash theme={null}
# 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:

```yaml theme={null}
# 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:

```yaml theme={null}
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:

```bash theme={null}
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:

```yaml theme={null}
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:

```bash theme={null}
squads kpi insights
```

### 4. Review Weekly

```bash theme={null}
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.

```bash theme={null}
# Check subscription capacity
squads dash

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