Standalone Codex plugin for automatically redeeming explicitly authorized, banked usage resets. It supports one-shot, bounded, and continuous authorization and runs as a private macOS LaunchAgent, so Codex does not need to remain open.

Important

This is an unofficial community project. It is not affiliated with, endorsed by, or supported by OpenAI.

The safe default waits until the Codex backend reports an exhausted rate limit. An explicit percentage threshold is also available for users who want an earlier attempt.

Safety model

• Plain arm --yes authorizes one exact currently available reset credit.
• arm --count N --yes authorizes up to N successful resets and waits for current or future detailed credits.
• arm --continuous --yes is standing authorization for current and future credits until explicit disarm.
• Every consume request still uses one exact backend-provided credit ID and a durable UUID.
• The exact credit ID and a UUID idempotency key are persisted before redemption.
• Ambiguous failures retry the same UUID. A confirmed nothingToReset response creates a fresh logical attempt.
• Redeemed, expired, missing-detail, workspace, and spend-control states fail closed.
• check --dry-run never consumes a credit or changes state.
• State transitions use a private file lock plus atomic, fsynced writes.
• Monotonic revisions prevent stale workers from passing compare-and-swap after an authorization cycles back to waiting.
• Non-final successful or unavailable credits enter settling until an authoritative snapshot prevents stale reselection; final one-shot or bounded outcomes complete directly.
• The watcher talks only to the public codex app-server protocol. It does not read Codex credentials or call private backend routes.
• Logs and notifications contain fixed messages, never backend payloads, credit IDs, or tokens.

Requirements

• macOS with per-user LaunchAgents
• Codex CLI with codex app-server and reset-credit support
• uv for a durable managed service runtime; without it, a working Python 3.10–3.13 whose lifecycle you manage
• An authenticated Codex account with a detailed banked reset credit

Git/Codex must be able to access RobertTLange/codex-auto-reset before installing it as a marketplace.

Install as a Codex plugin

codex plugin marketplace add RobertTLange/codex-auto-reset --ref main
codex plugin add codex-auto-reset@codex-auto-reset

Open a new Codex conversation, then ask:

Use $codex-auto-reset to install the background service and show its status.

When uv is installed, the skill selects a durable uv-managed Python rather than a project .venv or Homebrew Cellar target. Its fallback uses a validated PATH Python whose durability is the user's responsibility.

Direct CLI

For repository development:

uv sync --locked --dev
uv run codex-auto-reset --help

For a repository checkout, the same bundled wrapper is available directly:

MANAGE=./plugins/codex-auto-reset/skills/codex-auto-reset/scripts/manage
"$MANAGE" <command>

Installed-plugin users should invoke $codex-auto-reset in a new Codex conversation instead of guessing the plugin cache path. For checkout usage, use this wrapper for service operations; it deliberately avoids a repository .venv, which may be deleted or recreated.

Install the watcher

Backend-confirmed exhaustion, 60-second polling:

"$MANAGE" install-service

Explicit earlier attempt at 95% used:

"$MANAGE" install-service \
  --poll-seconds 300 \
  --usage-threshold-percent 95

Omitted options preserve the existing service settings. To remove a saved percentage threshold:

"$MANAGE" install-service --backend-only

The backend remains authoritative. If it answers nothingToReset, the authorization stays armed and the watcher tries a fresh logical attempt on a later poll.

Authorize resets

One exact currently available credit:

"$MANAGE" status
"$MANAGE" arm --yes

Plain arm reads the current bank and chooses the available Codex reset that expires soonest. arm --count 1 is equivalent. It refuses count-only responses because an exact credit ID is required.

A bounded sequence, including credits issued later:

"$MANAGE" arm --count 5 --yes

Continuous redemption until explicitly disabled:

"$MANAGE" arm --continuous --yes

Bounded and continuous authorization may start while the bank is empty. The watcher waits for a detailed credit, atomically binds its exact ID, and consumes at most one credit per polling iteration. A terminal or unavailable candidate does not reduce the bounded success allowance.

Inspect without mutation

"$MANAGE" check --dry-run
"$MANAGE" runtime

Disable or uninstall

"$MANAGE" disarm --yes
"$MANAGE" uninstall-service --yes

disarm and uninstall refuse an in-flight redeeming state, leaving the service running. Waiting, armed, settling, bounded, and continuous authorization can otherwise be disabled. If redemption races with uninstall after launchd stops, uninstall restarts the watcher before refusing so its idempotent attempt can finish.

To remove the Codex plugin after removing its service:

codex plugin remove codex-auto-reset@codex-auto-reset

Lifecycle

disabled -> waiting -> armed -> redeeming -> settling -> waiting -> ...
                 |         |          |
                 |         |          +-- authoritative retirement proof
                 |         +-- nothingToReset -> armed (fresh UUID)
                 +-- no detailed credit -> waiting

one-shot/final bounded success -> completed

• disabled: no authorization; no account request from the watcher.
• waiting: bounded or continuous authorization is active, but no exact credit is currently bound.
• armed: one exact credit is bound; the watcher evaluates policy.
• redeeming: the request identity is durable; ambiguous failures retry it.
• settling: the previous identity is retained until a complete snapshot proves it cannot be selected again.
• completed: one-shot authorization or a bounded success allowance is finished.

status reports lifecycle, authorization mode, successful resets, and remaining allowance without starting Codex or exposing credit IDs.

Local files

Path	Purpose	Mode
~/Library/Application Support/codex-auto-reset/state.json	Authorization and idempotency state	0600
~/Library/Application Support/codex-auto-reset/config.json	Polling and threshold settings	0600
~/Library/Application Support/codex-auto-reset/lib/	Private copied watcher runtime	0700 tree
~/Library/LaunchAgents/com.roberttlange.codex-auto-reset.plist	LaunchAgent definition	0600
~/Library/Logs/codex-auto-reset/	Sanitized stdout/stderr	private directory

State/config parents must be owned by the current user and private. Symlinked managed paths are rejected.

Updates

codex plugin marketplace upgrade codex-auto-reset
codex plugin remove codex-auto-reset@codex-auto-reset
codex plugin add codex-auto-reset@codex-auto-reset

Open a new Codex conversation and run the skill's install workflow again. Service settings are preserved unless explicitly changed.

Troubleshooting

• Status: disabled: install may be running, but no reset is authorized. Run an explicit arm command.
• waiting: authorization is active, but no detailed credit exists yet, or the exact credit is not eligible.
• settling: the watcher is retaining the previous identity until the backend authoritatively retires it.
• retry_pending: app-server, state, or protocol failure. The watcher backs off to at most 15 minutes and notifies only on status transitions.
• unavailable: the current exact credit was redeemed, expired, or reported unavailable. Bounded or continuous authorization may remain active; run status and disarm --yes if no future reset should be redeemed.
• Service diagnostics: inspect ~/Library/Logs/codex-auto-reset/stdout.log and stderr.log.
• LaunchAgent diagnostics: launchctl print gui/$(id -u)/com.roberttlange.codex-auto-reset.

Compatibility and limitations

• macOS only; launchd is the supported background runner.
• The app-server reset-credit protocol is still evolving. This implementation follows the current openai/codex app-server contract.
• When availableCount is present but credits detail is absent or capped, only a returned detailed credit can be armed. This intentional fail-closed behavior can leave otherwise available count-only credits unused.
• Missing, malformed, count-only, or capped detail never proves that a settling credit retired.
• Percentage mode is opt-in. It evaluates reported usedPercent; the backend can still decline an early reset.
• Paid credits are not reset credits and are never spent by this plugin.

Upgrading from 0.1

Version 1 state is migrated fail-closed: disabled remains disabled, and armed, redeeming, or completed state remains an exact one-shot authorization. Upgrading never creates bounded or continuous authority.

Development

uv sync --locked --dev
uv run ruff check .
uv run ruff format --check .
uv run pytest --cov=codex_auto_reset --cov-fail-under=80
uv build

See SECURITY.md for the threat model and reporting guidance.