---
name: budget-warning
description: Check project budget status and warn proactively when spending approaches the configured monthly limit. Activate when the user is about to start work that will consume tokens, especially at the beginning of work sessions or before large tasks.
user-invocable: false
---

# Proactive Budget Warning

Check the project's budget status and warn if spending is approaching or has exceeded the configured monthly limit.

## Activation

Trigger at natural checkpoints:
- Start of a new work session
- Before the user begins a large task (L or XL complexity)
- When budget-related context is relevant

## Steps

1. Call `fathom_check_budget` to get current budget status
2. Evaluate the spending level against thresholds:
   - Below 50%: No warning needed
   - 50-79%: No warning, but note if asked
   - 80-89%: Gentle note about approaching limit
   - 90-99%: Clear warning with remaining budget
   - 100%+: Strong warning that budget is exceeded
3. If a warning is warranted, present it briefly using the appropriate format below

## Warning Behavior

- Warn at most ONCE per conversation at each threshold level
- If you already warned about 80% in this conversation, only warn again if it crosses 90%
- Never repeat the same warning in the same session
- Do not warn at all if budget data is unavailable -- just skip silently

## Format

At 80-89%:

> Budget note: You've used {percent}% of your ${monthlyLimit}/month budget (${remaining} remaining). Current burn rate: ${dailyBurnRate}/day.

At 90-99%:

> Budget warning: ${remaining} remaining of ${monthlyLimit}/month budget ({percent}% used). At current rate, budget runs out in {daysRemaining} days. Consider using a more economical model or deferring non-critical tasks.

At 100%+:

> Budget exceeded: You've spent ${currentSpend} against a ${monthlyLimit}/month limit. All further AI usage is over budget. Consider pausing non-essential tasks or adjusting your monthly limit in .fathom/intent.yaml.

## Fallback

If budget data is not configured, skip silently. The user can configure a budget via `fathom init` or by editing `.fathom/intent.yaml`.