Skip to content

4.5. Budget & Safety

Squad includes built-in budget controls and safety limits that prevent runaway token consumption and ensure predictable resource usage.

Budget Configuration

Open the Budget Config panel from the squad monitoring dashboard to set limits for your squad.

Token Limits

Setting Default Description
Max total tokens 100,000 Maximum tokens across the entire execution
Max tokens per agent 30,000 Maximum tokens any single agent can consume
Max tokens per task 10,000 Maximum tokens for a single task execution

Execution Limits

Setting Default Description
Max concurrent agents 3 Maximum agents running simultaneously
Max tasks per plan 20 Maximum tasks the planner can create
Max plan iterations 3 Maximum re-planning attempts if a plan is rejected
Max agent turns 20 Maximum reasoning turns per agent per task

Time Limits

Setting Default Description
Execution timeout 1,800s (30 min) Maximum total execution time
Task timeout 300s (5 min) Maximum time for a single task
Agent idle timeout 60s Maximum idle time before an agent is stopped

Warning Threshold

The warning threshold (default: 80%) triggers a notification when token usage reaches the specified percentage of the total budget. This gives you time to intervene before the limit is hit.

Real-Time Budget Tracking

The Budget Meter provides a visual overview of current resource consumption:

  • Total token usage vs. budget limit
  • Per-agent token breakdown
  • Number of tasks created vs. limit
  • Active agent count vs. concurrency limit
  • Elapsed time vs. timeout

Safety Events

Budget Warning

When token usage reaches the warning threshold, a squad:budget-warning event is emitted. The monitoring dashboard highlights the budget meter in amber to signal approaching limits.

Budget Exceeded

When any budget limit is reached, execution is automatically paused:

  • The exceeded limit is identified (total tokens, per-agent tokens, task count, etc.)
  • Running tasks are allowed to complete their current turn
  • No new tasks are started
  • A squad:budget-exceeded event is emitted

Emergency Stop

In critical scenarios (e.g., extremely rapid token consumption), an emergency stop halts all execution immediately:

  • All running agents are stopped
  • Pending tasks are cancelled
  • The execution status changes to failed
  • A squad:emergency-stopped event is emitted with the reason

Best Practices

  • Start conservative — Begin with the default limits and increase them as you understand your squad's usage patterns.

  • Use per-agent limits — If one agent tends to be verbose, set a lower per-agent token limit rather than raising the total budget.

  • Monitor the first run — Watch the budget meter closely during the first execution to calibrate your limits.

  • Set task timeouts — Individual task timeouts catch stuck agents before they consume the entire budget.

Budget Limits Are Not Exact

Token counting is approximate and may slightly exceed configured limits before the system detects the overage. Always set limits with a small margin of safety.