Token Budgets: A UX Pattern for AI Coding Spend

You ask a coding assistant to inspect a repo, and the expensive part is the read. In a Java monorepo test covering four scenarios, Portal by Spotify's bulk-reader approach saved about 90% of the tokens Claude Code would otherwise have consumed for direct file reads.

Most AI coding tools treat token usage as a hidden number. The meter appears after the fact, or not at all, so the user learns the cost only when the invoice arrives. The expensive action is usually the one the user least understands.

Token budgets are a UX feature. They decide what the assistant does first, what it asks for second, and what the user can see before the bill arrives.

Make the cost visible before the action

A token budget works like a fuel gauge, not a fine. If the interface hides the expensive path, it steers without consent. The user needs to see which request will consume a large amount of context, which one will finish in a small amount, and which one can be avoided.

Cost transparency is a clear label near the action: this read will add a large context load. The user should be able to choose a cheaper route without reading a pricing table. Context management belongs before the broad answer, because the broad answer is where the spend grows.

The stakes are not hypothetical. One quarter of engineering leaders reportedly spend $200 to $500 per developer per month on tokens, and some reportedly spend well over $2,000. By 2028, AI coding costs are projected to exceed the average developer's salary. A budget belongs in the interface when the spend is already real.

Default to the cheap deterministic step

The strongest objection is that cheap steps feel like a downgrade. Users want the assistant to read the whole file, understand the repo, and answer in one pass. If the tool blocks that path, it can feel like a penalty.

The answer is to make the cheap path the default, not the fallback. The shunt plugin's check-file-size hook blocks Claude Code Read calls when a file exceeds a default threshold of 350 lines and directs Claude to use the /bulk-reader skill. The user still gets the answer, but the tool spends tokens on a summary or a scoped question rather than on raw text.

Cheap deterministic steps also need a model budget. The author's bulk-reader and code-writer examples use Gemini 2.5 Flash as the worker model, while Portal's model field can accept other configured models. The model choice should stay visible, but the cheaper route should run first.

Delegation also needs a time budget. Portal delegation responses generally take 10 to 30 seconds, and a single Portal invocation is capped at 30 seconds. A good UX pattern splits large work into smaller calls, shows the split, and lets the user stop before the next call starts.

Make the saving legible

Savings are only useful when they are legible. A hidden discount does not build trust. The interface should show what was avoided, not just what was spent. When the saving is visible, the assistant stops being a black box and becomes a tool with a known cost.

The display has three parts, in order:

• Expose context costs: the preview shows the context load before the action.
• Default to cheap deterministic steps: the default runs the scoped read or summary first.
• Make savings legible: the receipt says what was saved and why.

The display should be small enough to read while the user is working. It should not require a settings page, a finance dashboard, or a separate report. The user should see the cost consequence where the action is chosen. The display should update after the action and show the unit, such as tokens, so the user can compare actions.

The receipt is the trust layer. It tells the user that the tool chose a cheaper route, not just a smaller bill. The user can then decide whether to keep the default or override it.