Skip to content

All posts

AIBusiness

How to set budget alerts for a runaway AI agent

Ritesh Patel

AI: How to set budget alerts for a runaway AI agent

The Claude Code docs describe no built-in budget alert and no automatic kill switch for spend. Contain a runaway agent in layers: an admin-set spend limit or gateway cap that blocks further requests, a --max-budget-usd flag for scripted runs, and cost alerts built from the OpenTelemetry cost counter in your own monitoring stack.

Checked against the Claude Code costs, monitoring, settings reference and CLI reference pages, and the Claude apps gateway spend-limit page, as of 2026-11-17.

Which spend controls Claude Code documents

The costs page groups spend controls by how your organization accesses Claude Code. The table lists each control that the docs describe, the scope it covers and what the docs say happens at the limit.

Control Where you set it Scope What the docs say happens at the limit
Spend limits on usage credits (Team and Enterprise) Organization settings > Usage in claude.ai Organization, group or member The developer’s request is refused. They can continue after an admin raises the named limit, or after the plan reset time if the message names one
Workspace spend limits (Claude Console) Claude Console workspace Total Claude Code spend in the workspace Not described on the costs page
Claude apps gateway spend limits Admin API on a self-hosted gateway User, group or organization, per day, week or month The gateway returns 429 on the developer’s following requests until an admin raises the cap or the period resets
--max-budget-usd Command-line flag One print-mode run Claude Code stops the run once estimated spend reaches the amount
Cloud provider budgets Your cloud billing console Cloud account Not described in the Claude Code docs. The costs page points to your cloud’s budget controls

None of these controls warns you before the limit. Claude Code warns the developer at 75%, and again past 95%, of their most-consumed cap, using the gateway’s usage headers, so the warning reaches the person running the agent. It does not reach the team that owns the budget.

Why there is no automatic kill switch to configure

The settings reference has no setting that caps spend or stops a session at a threshold. The closest entry is autoContinueAtUsageLimit, which waits in the open session and continues the task after a claude.ai usage limit resets. It does not stop anything.

The modelPricing setting changes how cost is reported, including the figure that --max-budget-usd checks. It does not set a limit. Treat any stop you build as your own design, and test it against a real run before you depend on it.

Set budget alerts from the OpenTelemetry cost counter

Claude Code emits two counters that you can alert on. claude_code.cost.usage reports cost in USD, and claude_code.token.usage reports tokens. Both are incremented after each API request.

  1. Turn on telemetry and point the OTLP exporter at your collector:
export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_METRICS_EXPORTER=otlp
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317
export OTEL_EXPORTER_OTLP_PROTOCOL=grpc

Port 4317 is the gRPC port, and the monitoring page’s default for an http:// endpoint is http/protobuf, so set the protocol explicitly. The variable requires Claude Code v2.1.323 or later.

  1. If you need alerts to fire sooner, shorten the export interval. The default is 60000 ms. The monitoring page’s example uses 10000:
export OTEL_METRIC_EXPORT_INTERVAL=10000
  1. In your metrics backend, create an alert on claude_code.cost.usage for each developer. Group by user.account_uuid for signed-in users, so one developer’s spend stays in one series. Do not group by user.id. The monitoring page describes it as an anonymous identifier generated on first run and stored in ~/.claude.json, so one developer on two machines gets two values, and deleting the file creates a new one. If account identity is missing for some users, say so in the alert’s scope, because a per-install grouping splits that person’s spend and can keep a per-developer threshold from firing.
  2. Add rules for the three cases the monitoring page lists: cost spikes, unusual token consumption and high session volume from specific users.
  3. Send each alert to a person or to your own automation. Nothing in the Claude Code docs acts on the alert for you.

Stop a scripted run with –max-budget-usd

The flag is documented for print mode only, so an interactive session has no documented equivalent. Pass it to claude -p:

claude -p --max-budget-usd 5.00 "query"

The CLI reference adds three behaviors to plan around. Spend from subagents counts toward the cap. Once spend reaches it, spawning another subagent fails with Budget limit reached, and running background subagents stop. Totals restored with --continue or --resume do not count toward the cap. Spend can also pass the cap, so leave headroom. The cap-enforcement behaviors require Claude Code v2.1.217 or later.

Cap each developer at the gateway

On a self-hosted Claude apps gateway, you can cap one developer’s spend for each day, week or month, and set the organization and group caps the same way. The admin API calls, the example caps and the enforcement.fail_closed_on_error setting are covered in how to cap AI coding agent spend per developer.

The gateway’s dollar figures are its own estimate, which the docs call a circuit breaker rather than an invoice. Reconcile them against your provider’s usage reporting before you set a cap from them.

Map each layer to what it stops

Rate limits, budget caps and alerts do different jobs. The table below maps each job to the control the docs describe, so you can see which gaps remain.

Layer What it bounds Documented control
Per-run ceiling One print-mode run --max-budget-usd
Per-developer dollar cap Spend per developer over a period Gateway spend limits, or Team and Enterprise spend limits at the organization, group or member level
Throughput Tokens and requests per minute A workspace rate limit in the Claude Console caps Claude Code’s share of the organization’s limits
Drift detection Cost and token spikes after they happen claude_code.cost.usage and claude_code.token.usage in your backend
Automatic stop on an alert Nothing documented None described in the Claude Code docs

The last row is the gap. If you need a stop that fires when an alert does, build it in your own automation and test it against a real run.

Enforcing this with AIControls

AIControls supports per-user and per-session cost and budget limits. This post does not claim that AIControls sends anomaly alerts or stops a session automatically. For the current capabilities, see the AIControls platform page.

For the wider governance model, read the governing AI agents hub. For per-developer caps in detail, read how to cap AI coding agent spend per developer and how to track AI coding tool cost per developer.

Frequently asked questions

Does Claude Code send a budget alert when spend gets high?

The Claude Code docs do not describe one. Claude Code exports the cost and token counters through OpenTelemetry, and the monitoring page says anomaly detection, baselining and alerting are the responsibility of your SIEM or observability backend. You write the threshold rule in that backend, and you choose the threshold from your own pilot baseline, since the docs give no alert values.

Will Claude Code stop an agent automatically when a budget is reached?

The docs describe stops in three places. A per-developer cap on a self-hosted Claude apps gateway returns a 429 on later requests. The --max-budget-usd flag stops a print-mode run. An admin spend limit holds a developer's request until the limit is raised. None of them is triggered by an alert, and the docs do not describe an alert that stops a session.

Is the cost metric the same as my invoice?

No. The monitoring page calls cost metrics approximations and points to your cloud or Console billing for official figures. Claude Code computes its displayed costs from token counts at list price unless managed settings set modelPricing to your contracted rates. Reconcile the metric against your provider's usage reporting before you set a budget from it.

What should I do when an agent is heading the wrong way right now?

Press Escape to stop it. The costs page gives this as its course-correction step: if Claude starts heading the wrong direction, press Escape to stop immediately. To roll back, use /rewind or double-tap Escape to restore the conversation and the code to an earlier checkpoint. Then read the cost counter for that session to see what it spent before you stopped it.

Ritesh Patel, Founder & VP Product, Nirmata

Ritesh Patel is a founder of Nirmata and leads its products. He writes about governing AI coding agents, MCP security and Kubernetes policy as code.

LinkedIn

Govern AI agents with AIControlsControl what AI agents do, and prove it.
Share

Stay up-to-date with the latest in AI, governance, and infrastructure

Subscribe to our free monthly newsletter to get industry news, DevOps tips, and articles right to your inbox on Kyverno, containerization, Kubernetes deployment & management and more.