USER MANUAL · INSIGHTS

Budgets

Set cost limits per agent or workspace, track spending with visual progress bars, and receive proactive alerts before budgets run out.

/budgets

Overview#

Budgets let you define USD spending thresholds for individual agents or entire workspaces. Each budget tracks real-time spend against its threshold and displays progress visually, so you always know how close you are to your limit.

When spend approaches or exceeds the threshold, ClawButler triggers overage alerts and can optionally engage the budget circuit breaker to auto-disable the agent. An AI-powered advice engine analyzes your usage patterns and suggests optimal budget amounts.

Prerequisites#

Prerequisites

At least one connector synced (see Connectors)
Cost data flowing from synced agents (see Cost Tracking)

Expected Results#

After creating budgets, the Budgets page displays:

-Budget list with agent/workspace name, threshold amount, current spend, and progress bar
-Status indicators: on-track (green), approaching limit (amber), exceeded (red)
-Alert history showing triggered notifications with timestamps
-Budget alert history and current enforcement status for each budget

Web Operations#

Navigate to Budgets from the Insights section in the sidebar.

Budget List

The main view shows all budgets in a table. Each row displays the budget name, scope (agent or workspace), USD threshold, current spend, and a horizontal progress bar. The bar turns amber at 80% and red at 100%. Click any row to view details or edit.

Create / Edit Budget

Click 'New Budget' to open the creation form. Choose a scope — either a specific agent or an entire workspace. Set the USD threshold and configure alert preferences (email, in-app, or both). Optionally enable the circuit breaker to auto-disable the agent when the budget is exceeded. To edit, click the budget row and update any field.

Budget Enforcement

Budgets focus on thresholds, alerts, and optional circuit-breaker enforcement. Operators review current spend, warning thresholds, and whether enforcement will disable an agent when spend is exceeded.

Budget Alerts

Alerts fire at two thresholds: approaching (default 80%) and exceeded (100%). Each alert includes the budget name, current spend, threshold, and the agent or workspace affected. Alerts appear in the notification center and are logged in the audit trail.

CLI Operations#

List all budgets with spend status

Terminal

$ ap budget list

Create a budget for a specific agent with a USD threshold

Terminal

$ ap budget create --agent <id> --amount <usd>

Update the threshold amount for an existing budget

Terminal

$ ap budget update <id> --amount <usd>

Inspect budget status and threshold enforcement from the CLI

Terminal

$ ap budget list

FAQ#

Q: What happens when a budget is exceeded?

A: An overage alert is triggered immediately. If the circuit breaker is enabled, the agent is automatically disabled until the budget is raised or reset. If the circuit breaker is off, the agent continues running but alerts keep firing.

Q: How should I choose a budget threshold?

A: Start from recent cost history in Cost Tracking, then set a warning threshold and a hard limit that matches your acceptable weekly or monthly spend. Use alerts for early warning and circuit-breaker enforcement when you need a firm stop.

Q: Can I set a budget for all agents at once?

A: Yes. Choose 'Workspace' scope when creating a budget. This sets a single threshold that tracks aggregate spend across all agents in that workspace.