Readme of mushan-bit/codex-auto-retry

Why this exists

Since GPT Pro doubled its quota, Plus members have been getting squeezed. Codex regularly answers with:

Selected model is at capacity. Please try a different model.

The built-in auto-retry that used to ride this out has disappeared from the desktop app, so the only way forward is to sit there and click 重试 every few seconds. That gets old fast — so this tool clicks it for you, in the background, and only counts a retry when the banner actually goes away.

Screenshots

The Codex capacity banner with its Retry button

The exact banner this app reacts to: Selected model is at capacity. Please try a different model.

Close-up of the capacity banner with the Retry button highlighted

The Retry button the companion clicks (highlighted). A retry only counts once this banner disappears — no more “clicked but nothing happened”.

Badge states: running · paused · retrying · idle · error · permission needed.

Pulse ring animation played on the floating badge when a retry is triggered

Every triggered retry plays a pulse ring on the badge and posts a notification.

Features

Verified retries: a retry only counts after the banner disappears. The click tries AXPress, then a process-targeted mouse event, then a real system-wide click at the button's screen coordinates (Codex is briefly raised and the previous app gets focus back). Banners that survive all three are reported as “no effect” instead of being counted.
Menu bar control: toggle Auto, show/hide the floating badge, inspect the current state, see and reset the lifetime retry count, open Accessibility settings, or quit. The menu bar title shows the lifetime retry count.
Floating badge: always-on-top status badge you can drag anywhere; hide it from either menu and bring it back from the menu bar. The choice is remembered.
Notifications + animation: every triggered retry posts a system notification and plays a pulse ring on the badge.
Lifetime counter: total retries triggered are persisted in retry-count.json and shown in the menu bar, the menu, and the badge tooltip.
Background scanning: Codex is watched every 0.5 s when frontmost and every 1 s in the background — no need to keep the window in front, and the watcher does not steal focus.
Localized matching: Retry, 重试, Retry the request, Try again and other translations are matched; labels like codex-auto-retry are explicitly rejected so the app never clicks the wrong thing.
Safe by construction: at most 5 consecutive attempts (2 s → 30 s backoff), a 15 s quiet period before the attempt gate resets, and an automatic pause after five ineffective clicks.
Privacy-first logs: status and event logs contain no prompts, file contents, or message bodies.

Install

Download the latest package from the releases page:

codex-auto-retry-1.0.0.pkg — installs Codex Auto Retry.app into /Applications and registers the local Codex plugin.
codex-auto-retry-1.0.0.dmg — drag-and-drop disk image.
codex-auto-retry-1.0.0.zip — plain app archive for the older local plugin flow.

After installing, fully quit and reopen Codex (a new window is not enough — the MCP server has to restart). The plugin is registered through ~/plugins/codex-auto-retry and ~/.agents/plugins/marketplace.json. If the installer could not register it, run:

node scripts/install-local.mjs

If Codex still runs an old copy, remove the stale plugin cache ~/.codex/plugins/cache/local/codex-auto-retry and restart Codex.

Build from source

git clone https://github.com/MuShan-bit/codex-auto-retry.git
cd codex-auto-retry
node scripts/build.mjs          # builds .app, .pkg, .dmg and .zip next to the repo
swift test --package-path companion
node --test server/*.test.mjs scripts/*.test.mjs

Accessibility permission

The app needs System Settings → Privacy & Security → Accessibility. On first launch it opens that pane and explains itself in the badge menu. Grant the permission to Codex Auto Retry, not to Codex or ChatGPT.

/Applications/Codex Auto Retry.app

macOS grants Accessibility to the responsible process, so the plugin must launch the .app through LaunchServices (open -n "/Applications/Codex Auto Retry.app"). Spawning Contents/MacOS/codex-auto-retry-companion directly makes Codex the responsible process, and granting the app then has no effect.

If an old build was granted permission before, remove the old entry from the list and re-add the app, or reset the record:

tccutil reset Accessibility com.codex.auto-retry.companion

The build script pins the signing identity in .signing-identity (git-ignored) so rebuilds do not change the code requirement. Override it with CODEX_AUTO_RETRY_SIGNING_IDENTITY.

Usage

Menu bar: click the icon to toggle Auto, hide/show the badge, view the status and lifetime count, reset the counter, open Accessibility settings, or quit.
Floating badge: drag to move; right-click for Auto on/off, hide, status, lifetime count, or quit.
MCP tools exposed to Codex: auto_retry.start, auto_retry.pause, auto_retry.status, auto_retry.stop.
Retry policy: only when Auto is on, the capacity banner is visible, and there is exactly one enabled retry button. Verified clicks only, 5 attempts max, backoff 2 s → 30 s.

Diagnostics

Check how macOS attributes the Accessibility permission:

open -n -g "/Applications/Codex Auto Retry.app" --args --diagnose /tmp/codex-auto-retry-diagnose.json
cat /tmp/codex-auto-retry-diagnose.json   # expect selfAttributed: true, trusted: true

Dump what the watcher sees in Codex (banner regions, retry buttons, windows):

open -n -g "/Applications/Codex Auto Retry.app" --args --dump-ax /tmp/codex-auto-retry-ax.json
sleep 2
python3 -c 'import json;d=json.load(open("/tmp/codex-auto-retry-ax.json"));print("capacityRegions:",len(d.get("capacityRegions") or []))'

Debug-only flags: --no-permission-ui (skip opening settings), --no-permission-prompt (skip the system prompt), --menu-probe, and --badge-preview.

Logs

State and events live in ~/Library/Application Support/CodexAutoRetry/: status.json, events.json, panel-position.json, retry-count.json. Prompts, file contents, and message bodies are never recorded.

Limitations

Matching depends on Codex's Accessibility tree and retry wording. If Codex changes its UI, the companion reports retry click had no effect and pauses instead of clicking blindly.
If Codex is not running, the permission is missing, the retry button is absent, or several retry candidates exist, nothing is clicked.
The companion watches the MCP server that launched it and exits within 5 s of the server going away, so no orphan badge is left behind.
Each Codex conversation starts its own MCP server, so multiple open conversations can produce multiple companions and badges.