Feature: Budget guardrails by tool, provider, and time window

[symonbaikov]

Summary

Add budget guardrails so users can define usage limits by tool, provider, model, or time window and receive warnings before they overspend.

Example guardrails:

• $10/day for OpenRouter
• 80% of Cursor credits
• Do not spend Claude weekly quota after 18:00
• Warn when Codex usage crosses a daily token or cost threshold

The first version should focus on clear warnings and visibility, not hard blocking.

Problem

OpenUsage can show current usage, but users still need a way to prevent accidental overspend. AI tooling costs are often spread across multiple apps and providers, so it is easy to miss that one tool is burning through credits or that a weekly quota is being consumed too early.

Users need proactive answers to questions like:

• "Am I about to exceed today's OpenRouter budget?"
• "Has Cursor already used most of this month's credits?"
• "Should I avoid Claude Code tonight because my weekly quota is almost gone?"
• "Which tool is closest to its limit right now?"

Proposed feature

Introduce configurable budget guardrails with warnings when usage approaches or exceeds a limit.

Guardrail types

Support a small but useful set of rules for v1:

• Cost limit by provider/tool, for example OpenRouter <= $10/day
• Credit or quota percentage limit, for example Cursor <= 80% credits/month
• Token/request limit where cost is unavailable
• Time-window rule, for example warn if Claude weekly usage happens after 18:00

Warning behavior

OpenUsage should surface warnings before and after a threshold is crossed:

• warning at a configurable pre-limit threshold, for example 80%
• critical warning when the limit is exceeded
• short explanation of the driver, for example OpenRouter used $8.20 of $10 today, mostly from o3
• current status per guardrail: ok, warning, exceeded, unavailable

Example output

Budget guardrails

WARN  OpenRouter daily budget
      $8.20 / $10.00 used today (82%)
      Top driver: o3, $5.10

OK    Cursor monthly credits
      62% / 80% guardrail

BLOCKED BY POLICY? no hard blocking in v1

WARN  Claude weekly after-hours usage
      Weekly quota is 74% used. Avoid Claude Code after 18:00.

Suggested implementation shape

This likely needs three pieces:

1. A guardrail config model that can describe provider/tool/model scope, threshold, time period, and warning levels.
2. An evaluation layer that compares normalized usage data against configured guardrails.
3. UI/TUI output that shows guardrail status, warnings, and the main usage driver behind each warning.

For v1, guardrails should be advisory only. Hard blocking or automatically disabling tools can be considered later because it requires deeper integration with each client/provider.

Configuration ideas

The exact format can be decided during implementation, but the config should be easy to write and review. For example:

guardrails:
  - name: OpenRouter daily budget
    scope:
      provider: openrouter
    period: day
    limit:
      type: cost
      amount: 10
      currency: USD
    warn_at: 0.8

  - name: Cursor monthly credits
    scope:
      tool: cursor
    period: month
    limit:
      type: percent_quota
      amount: 0.8
    warn_at: 0.75

  - name: Claude weekly after-hours warning
    scope:
      tool: claude-code
    period: week
    condition:
      after_local_time: "18:00"
    warn_when:
      weekly_usage_percent_above: 0.7

Acceptance criteria

• Users can define at least one guardrail in local config.
• Guardrails can target a provider or tool.
• Guardrails can evaluate daily and weekly usage periods.
• OpenUsage shows ok/warning/exceeded status for each configured guardrail.
• Warnings include current usage, limit, percentage used, and the main contributing tool/model/provider when available.
• Missing cost, quota, or model metadata is handled gracefully with an unavailable or partial status instead of crashing.
• The implementation includes tests for guardrail evaluation logic, including below-threshold, warning, exceeded, and missing-data cases.

Open questions

• Should guardrails live in the main OpenUsage config file or a separate config file?
• Which usage sources currently expose enough quota/cost data for provider-specific guardrails?
• Should warning thresholds be global defaults, per-rule settings, or both?
• Should notifications be limited to the TUI/CLI for v1, or should desktop/system notifications be included later?

Why this matters

This turns OpenUsage into a proactive cost-control tool. Users should not have to discover overspend after the fact; they should see clear warnings while they still have time to switch tools, change models, or stop an expensive workflow.