@bacnh85/pi-budget

Spend cap enforcement for Pi — halts the agent when session cost exceeds a --budget USD limit. Companion to pi-sub (which renders usage); this one enforces.

Packages

Package details

extension

Install @bacnh85/pi-budget from npm and Pi will load the resources declared by the package manifest.

npm repohome report
$ pi install npm:@bacnh85/pi-budget
Package
@bacnh85/pi-budget
Version
0.1.3
Published
Sep 12, 2026
Downloads
245/mo · 9/wk
Author
bacnh85
License
MIT
Types
extension
Size
9.9 KB
Dependencies
0 dependencies · 0 peers
Pi manifest JSON
{
  "extensions": [
    "./extensions/index.js"
  ]
}

Security note

Pi packages can execute code and influence agent behavior. Review the source before installing third-party packages.

README

pi-budget

Spend cap enforcement for Pi — halts the agent when cumulative session cost exceeds a --budget <usd> limit. Companion to pi-sub: pi-sub renders subscription usage in the footer; pi-budget enforces a spend policy.

Zero dependencies. Plain JS.

Install

pi install npm:@bacnh85/pi-budget

Usage

pi --budget 0.50          # abort the session once spend hits $0.50
pi --budget 5             # a whole-dollar cap works too

When the cumulative cost of assistant responses reaches the cap:

  • The current turn is aborted (ctx.abort()).
  • A warning notification is shown.
  • A budget-exceeded custom entry is appended to the session record.
  • The footer shows Budget $X.XX / $Y.YY (red when exceeded, yellow below 20% remaining).

The budget resets on a new session. Context compaction does not reset it (compaction is mid-session). No cap set → the extension stays silent and shows no footer.

How it works

  • pi.registerFlag("budget") reads --budget <usd> once at startup.
  • message_end events accumulate message.usage.cost.total for assistant messages.
  • ctx.abort() stops the turn when the cap is crossed; an exceeded guard ensures the abort fires exactly once per session.

Limitations

  • Parent-session only. pi-subagent children are separate sessions, so child spend is not visible to this extension. Child aggregation from tool_result is a possible follow-up (tracked in the CHANGELOG).
  • Accuracy follows providers. Enforcement is only as accurate as each provider's usage.cost.total reporting.

Development

npm test   # node --test (no framework)

License

MIT