Setting up budget controls

Budget controls prevent runaway API spend. x tracks token usage and estimated cost per session, per project, and globally. When limits are reached, x pauses and asks before continuing.

Quick setup

# Set a per-session limit
$ x budget --set 10.00

# Set a global daily limit
$ x budget --global 50.00

# Check current usage
$ x budget
  Session:  $2.34 / $10.00  (23%)
  Global:   $8.17 / $50.00  (16%)

Environment variables

For persistent configuration, set these in your shell profile so they apply to every session:

export X_BUDGET=10.00          # per-session limit in USD
export X_BUDGET_GLOBAL=50.00   # daily global limit
export X_BUDGET_WARN=0.8       # warn at 80% of limit (0.0-1.0)

CLI flag override

The --budget flag overrides environment variables for a single session:

# One-off high-budget session for a large refactor
$ x run --budget 25.00 "refactor the entire auth module"

# Tight budget for a quick fix
$ x run --budget 2.00 "fix the typo in README"

What happens at the limit

Budget enforcement works in two stages:

1. Warning — When spend hits the warning threshold (default 80%), x shows a yellow notice in the status bar. The agent continues working.
2. Pause — When the limit is reached, x pauses execution and prompts with three options:

• Continue — extend the budget by the original amount and keep going
• Finish — let the agent complete its current thought, then stop
• Stop — halt immediately, preserving all work done so far

Viewing spend history

# Show stats for recent sessions
$ x stats --since 7d

# JSON output for scripting
$ x stats --since 30d --json | jq '.totalCost'

Precedence

When multiple budget sources exist, the most restrictive limit wins:

1. CLI flag (--budget) — highest priority
2. Environment variable (X_BUDGET)
3. Default ($5.00 per session)

Global limits (X_BUDGET_GLOBAL) are checked independently and always enforced, regardless of per-session settings.