Feature proposal: codexbar guard — a quota-aware exit code to gate automation

[OfficialAbhinavSingh]

Update: implemented in #2237 (build + tests green on Linux). Opening it with code + proof rather than waiting on a green light — happy to iterate on the flag shape or close if the direction isn't wanted.

Summary

Add a codexbar guard subcommand that turns CodexBar from a passive display into an active guardrail: it exits 0 when a provider has enough headroom to safely start work, and non-zero when it doesn't — so it can be dropped into scripts and agent loops.

Motivation

Today CodexBar (menu bar and CLI) reports limits — you still have to look, interpret the projection, and decide. For anyone running long or looping agent tasks, the failure mode is hitting a limit mid-task and losing the run.

The data to prevent that is already computed — the CLI prints Pace: On pace | Expected 25% used | Projected empty in 3h 35m. guard just exposes that as a decision an automated caller can act on, via the one thing shell/automation already speaks: an exit code.

Proposed behaviour

codexbar guard --provider <id> [--need <percent>] [--for <duration>] [--json]

• --need 20% → exit 0 if ≥20% of the relevant window remains, else exit non-zero.
• --for 3h (optional) → also fail if a reset would land inside that window, or if the current projection ("projected empty in …") is shorter than --for.
• Exit codes: 0 = safe, 1 = insufficient headroom, 2 = unknown/unreachable (fail-closed by default; --fail-open to invert).
• --json → emit the decision + the numbers behind it for callers that want detail.

Examples

# stop the loop before it starts a task it can't finish
while codexbar guard --provider claude --need 15%; do run-agent-iteration; done

# gate a long build; if blocked, show when it frees up
codexbar guard --provider codex --need 30% --for 2h \
  && ./long-task.sh \
  || echo "hold off — $(codexbar usage --provider codex | grep -i reset)"

Why this fits CodexBar

• Delivers the tagline literally — "may your tokens never run out" — by preventing work you can't finish rather than reporting the crash after.
• Composable, not bloat. One subcommand + exit codes on data the tool already has. No new UI, fits the minimal-CLI style.
• Squarely for agent-automation users — gating codex/claude loops on remaining quota. Cross-platform (CLI/Core), so it lands for the Linux CLI users too.

Scope (MVP)

Single provider, --need <percent>, exit 0/1/2, fail-closed. --for, --json, and multi-provider (--provider all, pass only if every provider passes) as follow-ups. Deterministic — straightforward to cover with focused tests (no live provider or app run needed).

Status

Implemented in #2237 — build and Linux tests green. Feedback on the flag shape (--need / --window / --fail-open) is very welcome, and I'm happy to close it if a quota-guard / exit-code contract isn't something you'd want in CodexBar, @steipete.

[clawsweeper]

Codex review: keeping this open for maintainer follow-up; there is still a little grit to resolve. Reviewed July 16, 2026, 6:16 PM ET / 22:16 UTC.

Summary
Keep open because this is a new CLI/API contract requiring product approval, and the same contributor's open implementation PR already owns the proposed work; the issue should remain paired until that PR merges or closes.

Likely related people

• steipete — high confidence; introduced and repeatedly evolved the CLI surface and is the likely product-direction owner.
• ThiagoCAltoe — medium confidence; previously maintained adjacent CLI command and version behavior.

Reproducibility: not applicable. This issue proposes a new CLI capability rather than reporting broken existing behavior. Current documentation confirms that no equivalent guard command exists on main.

Ways to help us reproduce this

• Add a screenshot or short recording showing the behavior.
• Add expected vs actual behavior.

Next step
Do not dispatch another fix PR because the same contributor's open implementation PR already owns the work and awaits a product-direction decision.

Maintainer decision needed

• Question: Should CodexBar adopt a first-class quota-gating command, and if so should the linked PR's --need, --window, --fail-open, and exit-code contract become the supported CLI API?
• Rationale: The request adds a new automation capability and durable shell-facing API whose failure semantics cannot be selected safely from implementation evidence alone.
• Likely owner: steipete — The repository owner has the strongest CLI feature history and was explicitly asked to decide whether this product direction belongs in CodexBar.
• Options:
  • Sponsor the narrow MVP (recommended): Accept a single-provider percentage guard after reconciling exit status 2, documenting fail-open behavior, and reviewing the linked PR's focused implementation.
  • Decline the command surface: Keep CodexBar's CLI informational and close both the proposal and linked implementation without adding automation-gating semantics.
  • Request a revised contract: Keep the proposal open but ask for a smaller or differently named command and flag contract before implementation review continues.

Review details

Best possible solution:

Land a narrowly scoped guard command only after defining a stable command-specific exit-code contract, documenting fail-open behavior, and validating both human-readable and JSON output through deterministic CLI tests in the linked PR.

Do we have a high-confidence way to reproduce the issue?

Not applicable; this issue proposes a new CLI capability rather than reporting broken existing behavior. Current documentation confirms that no equivalent guard command exists on main.

Is this the best way to solve the issue?

Unclear pending product approval; a pure decision function reusing the existing provider-fetch pipeline is a maintainable implementation shape, but the command, flags, and exit-code contract require maintainer confirmation.

AGENTS.md: found and applied where relevant.

Remaining risk / open question:

• The proposed status 2 meaning must be reconciled with the documented existing status 2 contract to avoid ambiguous automation behavior.
• --fail-open changes whether unavailable quota permits automation to proceed, so its naming, default, output, and safety semantics require explicit product approval.

Codex review notes: model internal, reasoning high; reviewed against 9fa8e918c88b.

Label changes

Label changes:

• add P3: This is a speculative, additive automation feature with an open implementation PR and no report of broken existing behavior.
• add issue-rating: 🌊 off-meta tidepool: Current issue advisory state selects this label.
• add clawsweeper:no-new-fix-pr: Current issue advisory state selects this label.
• add clawsweeper:needs-product-decision: Current issue advisory state selects this label.

Label justifications:

• P3: This is a speculative, additive automation feature with an open implementation PR and no report of broken existing behavior.

Evidence reviewed

What I checked:

• Current CLI lacks the requested command: The current CLI documentation lists usage, cost, status, providers, config, serve, refresh, and version behavior but no quota-aware guard command, so the requested capability is not implemented on current main. (docs/cli.md:80, 9fa8e918c88b)
• Existing exit-code contract needs reconciliation: The documented CLI contract already assigns exit status 2 to a missing provider, while the proposal assigns 2 to unknown or unreachable quota; adopting the command therefore requires an intentional, documented command-level exit-code policy. (docs/cli.md:93, 9fa8e918c88b)
• Open implementation PR owns the work: The issue body and timeline link feat: add codexbar guard — quota-aware exit code to gate automation #2237, an open and mergeable pull request by the same contributor implementing the proposed command and focused decision tests. (3ca9952d000b)
• Repository policy favors focused CLI validation: The supplied repository AGENTS.md directs provider and CLI behavior toward deterministic focused tests without live account or Keychain access; the linked PR reports pure decision tests consistent with that validation boundary. (AGENTS.md:23, 9fa8e918c88b)
• CLI ownership history: Repository history attributes the initial serve CLI command work to steipete and later CLI version behavior maintenance to ThiagoCAltoe, making them relevant routing candidates for the new command contract. (Sources/CodexBarCLI, 2875b2380ddc)

Likely related people:

• steipete: Introduced the CLI serve surface and has the strongest observed history across the repository's CLI design and command behavior. (role: CLI feature owner and likely product-direction owner; confidence: high; commits: 2875b2380ddc; files: Sources/CodexBarCLI, docs/cli.md)
• ThiagoCAltoe: Maintained adjacent CLI version behavior, making them relevant for command-dispatch and exit-contract review. (role: recent adjacent CLI contributor; confidence: medium; commits: 375e6755a6be; files: Sources/CodexBarCLI, TestsLinux)

How this review workflow works

• ClawSweeper keeps one durable marker-backed review comment per issue or PR.
• Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
• A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
• PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
• Maintainers can also comment @clawsweeper review to request a fresh review only.
• Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge.
• Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
• Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.

[steipete]

Implemented and merged in #2237 as 562f9f2fc333f3528033245e06c3df5a333717f7. Thanks @OfficialAbhinavSingh for proposing and implementing the guard workflow.

The merged CLI contract uses explicit provider and window selection, inclusive --min-remaining, bounded timeout, tooling JSON, read-only/background credential access, and stable exits: 0 safe, 1 below threshold, 64 invalid arguments, 69 unavailable/timeout. --fail-open changes only unavailable results to exit 0 while JSON remains decision: "unknown".

Proof: 13 focused guard tests passed; make check passed; a full local run passed 697/697 selections; final live Codex OAuth check exited 69 because the available sessions had no rate-limit events; exact-head CI passed lint, Linux x64/ARM64, both macOS shards, aggregate gate, and security checks.