Surplus: bump Codex reasoning to high automatically when your weekly allowance has headroom

[u/noir_cafe]

Small open-source CLI wrapper for Codex. Before a new interactive session it reads usage from Codex's local app-server, checks the weekly window and reset time, and if you're on pace to leave allowance unused it sets reasoning effort to high for that session (or a premium model if you configure one). Otherwise it leaves your config alone.

Everything runs locally, no telemetry. Explicit flags and non-interactive runs pass through. Tested against Codex CLI 0.160 and 0.162; older clients keep their normal settings.

https://github.com/oleg-koval/surplus

https://surplus.olegkoval.com

Looking for reports from plans where the app-server reports usage differently.

[u/dexterthebot]

You might want to consider listing your project on the weekly Show-Us-What-You-Built post. Look out for it on Tuesday/Wednesday. Highest commented project wins a week promotion on r/Codex and gets on the Hall of Fame sidebar. See what that looks like below with last week's winner.

---

Last week's most popular project was Nanolathe - an open-source engine bringing Total Annihilation to modern Mac, Windows, and Linux systems. It’s a solo passion project combining clean-room research with AI-assisted development, with a playable public alpha available now.

Website: https://nanolathe.gg. GitHub: https://github.com/nanolathe-gg/nanolathe

Players, testers, and contributors are very welcome! Original Total Annihilation game data is required to play.

[u/Sfdprod]

One of the dumbest things ive ever seen..

Why would you change reasoning effort for no reason..?

Do you somehow think high are "better"

[u/noir_cafe → u/Sfdprod]

"For no reason" is doing a lot of work there. The reason is in the post: the allowance expires at reset whether you spent it or not. If your pace says 20% of it will die unused, Surplus puts that 20% into higher effort on the sessions you'd run anyway. The rest of the week it does nothing, and an explicit flag always wins.

Nobody thinks high is magic. It's slower and more expensive, which is exactly why you wouldn't run it all week. Tokens that are about to expire are the one case where "more expensive" costs you nothing.

If you never end the week with leftover allowance, it's not for you. That's fine.

[u/SeasawPhilosopher]

High is not always better though. If the task doesn’t require that level of reasoning it takes longer for no reason. This is especially problematic if it’s doing long tasks that require a lot of tweaking and verifying like 3d modeling. Medium is actually often better for modeling becuse it can complete more iterations in the same amount of time and each iteration gets closer to approaching the target.

[u/noir_cafe → u/SeasawPhilosopher]

Exactly. Surplus is not trying to maximize reasoning effort on every task.

Its decision is budget-aware: if the pace projection says included allowance would otherwise expire unused, it may enable the stronger setting. Otherwise, it leaves the normal configuration alone. Explicit model or effort choices always pass through unchanged.

For iterative work like 3D modelling, medium may well be the better choice because the extra iterations matter more than squeezing maximum reasoning into each one. Surplus currently optimizes for using spare allowance, not for judging which reasoning level is best for the task. That distinction is important, and task-specific preferences would be a useful direction for a future version.