Surplus 0.2.0: Spend the AI Allowance You Would Lose

Surplus 0.2.0 is out.

I built it for a very specific kind of waste: the weekly AI coding allowance you paid for, did not use, and watched disappear when the reset arrived.

The problem is not only rate limits

Claude Code and Codex give you usage windows. Most of the week, that means choosing the model and settings you normally use, then trying not to hit the ceiling too early.

The awkward part comes later. You reach the end of the window with allowance left, but you do not know how much is safe to spend. So you keep using the conservative setting. The reset arrives. The unused capacity is gone.

Surplus is a small command-line layer that makes that trade-off explicit. It watches the usage information the providers already expose, estimates your pace, and decides whether a new interactive session can use the stronger configuration without burning through the rest of your week.

The goal is not to make every launch premium. The goal is to stop treating a weekly allowance like a light switch: on until it suddenly is not.

What changed in 0.2.0

The first version mostly asked whether you were near the reset. Version 0.2.0 adds pace-based routing.

Surplus keeps a short local history of observations and projects what your current burn rate would leave unused at reset. If the projection clears your reserve and safety margin, it can start the next interactive Claude Code or Codex session with the stronger configuration you chose. If the numbers are unclear, stale, malformed, or too close to the limit, it keeps your normal settings.

There is hysteresis as well, so one noisy reading does not make the decision flip back and forth between launches. During the first part of a fresh window, when there is not enough history to make a useful pace estimate, Surplus falls back to the more conservative near-reset rule.

That is the important distinction: it spends surplus only when the evidence says there is surplus.

It now tells you inside the tools

Routing is useful, but silent routing is hard to trust. Surplus 0.2.0 adds notices inside Claude Code and Codex.

At session start, it can print one short line when a premium window is open or when your current pace suggests you are on track to leave allowance unused. An optional prompt nudge can speak only when that state changes, and an optional Claude statusline segment can show a compact signal such as ⚡ opus 41% 1.8d.

These are deliberately small signals. They should help you make a decision without turning every prompt into a dashboard.

surplus configure features \
  --session-notice on \
  --prompt-nudge on \
  --statusline-segment on

Surplus installs its hooks alongside existing Claude Code and Codex hooks, leaves those other hooks alone, and removes only its own entries on uninstall. A hook failure is non-blocking and exits within the short budget it is given.

The normal commands stay normal

Install it globally, then keep typing the commands you already use:

npm install --global surplus-cli
surplus install
claude
codex

Useful commands include:

surplus status claude
surplus status codex
surplus configure claude --premium opus
surplus configure codex --premium MODEL --effort high
surplus demo
surplus uninstall

Claude's default premium target is opus. Codex keeps the model from your effective configuration and raises reasoning effort only when its live model catalog confirms that the setting is valid for that model. You can choose a specific Codex target instead.

Explicit model and effort flags, resumed or background sessions, cloud sessions, non-interactive commands, provider utility commands, and accounts billed outside the supported included-usage windows pass through unchanged. Surplus does not make a model call to measure usage and does not edit your provider's model settings.

The boundaries matter

Surplus is not a billing guard. It cannot prevent charges caused by paid-overage settings already enabled in a provider account, and it does not change those settings.

It also cannot manufacture a premium bucket that the provider does not expose. The signals are shared allowance data, not a promise that each model has a separate reserve. If the provider does not report a valid window or does not confirm that included usage is allowed, Surplus chooses the normal settings.

The local-first design is intentional. Configuration, usage history, account identity hashes, and policy state stay in your local state directories. Surplus sends no analytics or usage events; Codex usage metadata is fetched through Codex's normal provider connection.

Try it

Surplus 0.2.0 is available on npm under the MIT license:

npm install --global surplus-cli

The source, security notes, implementation plan, and interactive demo are on GitHub. The package is also available on npm.

If your weekly reset regularly takes unused allowance with it, this is the whole idea: use the stronger setting when you have room, stay conservative when you do not, and make the decision visible enough that you can disagree with it.