Skip to main content
How-To Guides Last updated: 16 November 2026

Cost budgets

Nathan Schram
By Founder, Little Bear Apps

Running agents remotely means they can rack up costs while you’re not watching. Untether tracks API costs per run and per day, with configurable budget limits and warning thresholds to keep spending visible — even when you’re away from the screen.

Configure budgets

untether config

untether config set cost_budget.enabled true
untether config set cost_budget.max_cost_per_run 2.00
untether config set cost_budget.max_cost_per_day 10.00

toml

[cost_budget]
enabled = true
max_cost_per_run = 2.00
max_cost_per_day = 10.00
SettingDefaultDescription
enabledfalseEnable cost tracking and budget enforcement
max_cost_per_run(none)Maximum cost for a single run (USD)
max_cost_per_day(none)Maximum total cost per day (USD)
warn_at_pct70Show a warning when this percentage of the budget is reached
auto_cancelfalseStop at limit: refuse new runs once the daily budget is reached, and end a session after the reply that passes the per-run budget (see Stop at limit)
warn_run_above_usd(unset = $20)Flag any single run that costs more than this, even with enabled = false; 0 turns it off
notify_run_outliertruePost the one-line chat notice for an outlier run (the log line is written either way)

Per-chat overrides

You can toggle budgets on or off per chat without editing the config file. Open /config → 💰 Cost & usage and use the toggle buttons:

  • Budget — turn budget tracking on or off for this chat
  • Stop at limit — the per-chat override of auto_cancel (see Stop at limit)

These override the global [cost_budget] settings for the specific chat. Clear the override to revert to the global setting. See Inline settings for the full /config menu reference.

Loop mode and budgets

If you turn on Loop mode in /config → 🔁 Loop mode, autonomous loop fires count toward the same daily and per-run budget caps as manual runs. There is no separate per-loop budget. With Stop at limit on, a loop fire after the daily budget is reached is refused like any other run; without it, a budget only alerts you about loop spend. Without it, the runaway caps in [loop] (max_iterations, max_total_duration_hours, expiry_days) are what actually bound a loop. Set a budget before turning on Loop mode so you hear about its spend. With Loop mode off, Claude can’t start scheduled runs on its own at all (#925). See Schedule tasks → Loop mode for the full picture. (#289)

How it works

After each run completes, Untether checks the reported cost against your budgets:

  1. Per-run check: if the run cost reaches max_cost_per_run, you get an alert
  2. Daily check: if the cumulative daily cost reaches max_cost_per_day, you get an alert
  3. Warning threshold: at warn_at_pct (default 70%) of either budget, you get an early warning

Only one alert is shown per run, and the per-run check comes first: a run that trips the per-run warning or limit doesn’t also report the daily one.

Claude costs are per run

Claude reports a running total for the whole session, including earlier runs you resumed. Since v0.36.0 Untether subtracts what the session had already cost, so budgets, /stats and the footer see only this run’s spend. A turn that Claude runs on its own after a background task counts as its own small run (#778). When a reply’s cost includes what background agents spent since the previous reply, the footer says so (💰 … · incl. 2 bg agents, #821).

Token-only engines

Engines that don’t report USD costs (Codex, and OpenCode on its free tier) show token counts in the footer instead, marked 🔢 (e.g. 🔢12.3k/400, input/output); 💰 means the footer carries a cost (#417). Codex reports a running total for the whole thread, so since v0.36.0 Untether shows each run’s own share; a figure that is still the whole thread (for example the first /continue of a thread started outside Untether) is labelled · thread total (#419). Pi currently shows no cost or token footer: its usage block isn’t in a shape the footer reads. Gemini CLI and AMP (both deprecated) surface total_cost_usd when their CLI reports one. Budget alerts apply only to the USD-reporting path.

Expensive single runs

Even with no budget configured, a single run that costs more than warn_run_above_usd ($20 unless you set it) adds one line to its final message, whatever your footer settings (#702):

💸 This run cost $24.30 (over the $20.00 alert)

It also logs cost.run_outlier with the run’s shape (turns, cost per turn, duration and token counts), so you can tell one long task from a session whose context has grown expensive (#717). The line is skipped when a budget alert already covered the run. Separately, if spend is neither shown ([footer] show_api_cost = false) nor bounded (no [cost_budget]), Untether logs one config.cost_visibility_gap warning per start (#658).

Alert levels

AlertIconMeaning
Warning⚠️Cost is approaching the budget threshold
Exceeded🛑Cost has exceeded the budget

Because the check runs when a result arrives, an alert on its own doesn’t stop anything: turn on Stop at limit for that. Claude’s automatic retry after a stalled stream is skipped either way when the failed run already hit a per-run or daily limit.

With the cost footer on ([footer] show_api_cost = true, the default), the alert is a suffix on the 💰 line, ⚠️ 73% or 🛑 budget. With the footer off, it’s a line of its own:

Untether

⚠️ Run cost $1.45 is 73% of per-run budget $2.00

Cost warning alert showing budget threshold exceeded

Stop at limit

Set auto_cancel = true (or turn on Stop at limit in /config → 💰 Cost & usage) to make the limits act, not just alert (#896). Budgets must be enabled for the chat. Claude reports cost only when a reply finishes, so Untether acts at the two points it safely can; it never interrupts a reply in progress.

  • Daily budget reached: new runs are refused until midnight: prompts, /continue, follow-ups into a live session, /at, loop fires, crons and webhooks. In a chat you get a message with a Run anyway button, which starts the refused run once (only in that chat):

    Untether

    🛑 Daily budget reached ($10.20 of $10.00). New runs are paused until midnight.

    Crons, webhooks and loop fires are skipped with a one-line message instead (no button), for example 🛑 Daily budget reached ($10.20 of $10.00). Skipped cron:daily-review; new runs are paused until midnight. You get that line once a day per cron, webhook or loop, not on every fire. A refused cron or webhook isn’t announced and its fetch step doesn’t run, and a run_once cron isn’t used up: it stays scheduled and fires at its next schedule match (logged as triggers.cron.run_once_refused). Every refusal is logged as cost_budget.run_blocked, whether or not a message was sent (notice_sent). A plugin command that runs an engine with mode="capture" gets a refused result (RunResult.refused = "daily_budget") instead of a message.

  • Per-run budget passed: when a reply takes the run’s total past max_cost_per_run, that reply is delivered with a 🛑 Stopped: run cost $2.30 passed the per-run budget $2.00 line, then the session is closed, so no background wake-ups or follow-ups add to it. The run’s total counts every turn of a live session, not only the last one. Background tasks still running are stopped and named. The same happens, with 🛑 Stopped: today's cost … reached the daily budget …, when a reply takes the day’s total to max_cost_per_day. Logged as cost_budget.run_stopped.

Your next message after a per-run stop starts a new run with a fresh per-run total. That includes a message you sent while the stopping reply was still being written: it is never added to the stopped session as another turn. A session stopped by the daily budget stays paused until midnight unless you tap Run anyway.

Daily reset

The daily cost counter resets at midnight in the host’s local time zone (the server clock, not yours), and each new day starts from zero. Since v0.36.0 the day’s total is saved to daily_cost.json next to untether.toml after every run, so restarts, upgrades and daily reboots no longer reset it; a file left over from an earlier day is ignored (#898).

Check current usage

Use the /usage command in Telegram to see your Claude Code subscription usage:

/usage

This shows:

  • 5h window: usage percentage and time until reset
  • Weekly: 7-day usage percentage and time until reset
  • Per-model breakdown: Sonnet and Opus usage (if applicable)
  • Extra: overage credits used, when extra usage is turned on for your account

The /usage command reads your Claude Code OAuth credentials to fetch live data from the Anthropic API. If you see “No Claude Code credentials found”, sign in to Claude Code on that machine (run claude and follow the login prompt).

Untether

📊 Claude Code Usage

5h window: ████░░░░░░ 42% (resets in 2h 6m)
Weekly: ███░░░░░░░ 28% (resets in 5d 2h)
Sonnet: ████░░░░░░ 38%
Opus: ░░░░░░░░░░ 4%

Antigravity

In an Antigravity chat /usage asks agy for its own quota groups and your remaining AI credits, then shows the last session’s tokens. Each group is a separate pool with its own limits. Untether fetches this only when you send /usage (it costs no tokens, and the answer is reused for 60 seconds, the credits for 5 minutes); /usage debug adds cache age, the last error and the agy version. Antigravity reports tokens but no dollar cost, so [cost_budget] limits never trip for it.

Untether

📊 Antigravity quota
Gemini Models
• 5-hour: ██░░░░░░░░ 18% used · resets in 3h 12m
• Weekly: █░░░░░░░░░ 6% used · resets in 4d 2h
Claude and GPT models
• 5-hour: ░░░░░░░░░░ 0% used
• Weekly: ░░░░░░░░░░ 0% used
AI credits: 2,500 remaining · get more
From agy /usage (no quota spent).

Last session in this chat
Session 90ca6744… · 2 runs
Session total: 27k in · 290 out
Last run: 14k in · 150 out

A limit that hasn’t been touched shows no reset time. Because agy reports a running token total for the whole conversation, Untether records each run’s difference, as it does for Codex.

Other engines

Codex, OpenCode and the other engines don’t report subscription quota, so in their chats /usage shows the token totals of the chat’s last session of that engine instead: the session total, the last run, the run count, and the last run’s cost when the engine reports one. Codex reports a running total for the whole thread, so Untether records each run’s difference — the footer (🔢12.3k/400) shows this run’s tokens, and /usage shows the thread total. A token-only footer uses 🔢; 💰 means the footer carries a cost.

Untether

📊 codex · last session in this chat
Session 019dc356… · 3 runs
Session total: 168k in (142k cached) · 1.6k out (reasoning 900)
Last run: 12k in · 400 out
Quota and plan limits are not available for codex — its exec mode doesn’t report them. Transcript: /export

The history behind /usage is kept in memory, so straight after a restart it says there is no completed run yet; send a prompt first.

/usage command output showing 5h window, weekly usage, and per-model breakdown

Untether can show subscription usage in the footer of completed messages. This is configured in the [footer] section:

toml

[footer]
show_subscription_usage = true

When enabled, completed messages show a line like:

⚡ 5h: 45% | 7d: 30%

This tells you how much of your 5-hour and 7-day rate limits you’ve used. A window’s reset time is added once it passes 50%, for example ⚡ 5h: 72% (1h 14m) | 7d: 30%. See Subscription usage for details.

Historical statistics

For historical run data beyond the current session, use the /stats command:

/stats

This shows per-engine session statistics (runs, actions, duration) across today, this week, and all time. Pass an engine name to filter (e.g. /stats claude). Data is saved in the config directory; days older than 90 are folded into an all-time total, so “All time” stays complete.

Was this helpful?

Related Articles