Budgets

§ BUDGETS

Octopush is token-first, and budgets are how you keep that visible spend under control. Set a limit, choose how it applies, and Octopush warns you as you approach it — then blocks sends once you hit it, with an escape hatch when you really need one.

How to open it

Budgets and the usage dashboard live in Settings ▸ Usage.

[screenshot: Settings ▸ Usage with a budget set and the spend dashboard]

Scopes and periods

A budget has a scope and a period.

• Scope — global, project, or workspace. Cap your whole account, a single repository, or one worktree.
• Period — daily or monthly.

You can set a budget for any scope and clear it just as easily.

Warnings and blocking

As spend climbs toward a budget, Octopush surfaces toast warnings:

• 50% — heads-up toast.
• 80% — heads-up toast.
• 100% — you’ve hit the limit.

At 100%, Octopush blocks sends for that scope. If you need to push one more turn through, there’s a one-turn override — it lets a single send go and then re-applies the block.

Caution

The 100% block is a hard stop by design. The one-turn override is exactly that: one turn. It won’t quietly let a runaway agent keep spending past your cap.

The usage dashboard

Settings ▸ Usage also shows where your spend goes:

• Hourly trend — spend over time.
• Cost by model — which models cost you the most.
• Cost by session — which sessions cost you the most.

A typical flow

1. Open Settings ▸ Usage.
2. Set a monthly budget at the global scope, and a tighter daily budget on a workspace you expect to be expensive.
3. Work as usual; act on the 50% and 80% toasts.
4. At 100%, sends are blocked — use the one-turn override only if you must.
5. Open the dashboard to see cost by model and by session, and adjust which models you reach for.

Tips

Budget the expensive workspace, not just the account

A global cap protects the account, but a per-workspace daily budget is what catches a single runaway agent before it eats the month. Use both scopes together.

Note

Budgets pair naturally with model management: the cheapest way to stay under budget is to reserve premium models for the turns that need them — and in DIRECT, the savings-first ledger makes that trade-off explicit.