Codex Remaining for Oh My Pi

An unofficial Oh My Pi (OMP) extension showing remaining OpenAI Codex quota below the editor.

Features

• Compact (v0.1.10): same single-box layout with the unified title Codex Summary, showing 5h/7d percentages, reset countdowns, plan, and credits. No other compact layout changes.
• Bars (default, v0.1.9): two independent bordered panels: Codex Summary (plan/credits and optionally Tibo/Forecast) and Quotas (5h/7d colored progress bars). Hiding Tibo or Forecast collapses only its summary rows: no empty lines, no switch back to legacy layout. Long public-data sections wrap for small terminals.
• Five colors: 0–20% red, 21–40% orange, 41–60% yellow, 61–80% lime, 81–100% green.
• Fast startup and model switching (v0.1.7+): registers commands immediately, shows cached quota or a loading indicator before CLI fetching completes, and detects provider switches within about 250ms. Network/CLI/config checks run in the background. Cached quota is clearly marked stale until refreshed. v0.1.9 fetches Tibo/Forecast concurrently and commits them to the visible UI as one snapshot without gating the independent quota refresh.
• Performance/QoL audit (v0.1.10): switching bars/compact/toggle paints from local state immediately without awaiting the quota CLI; cached 30-second ticks avoid duplicate widget rebuilds; unchanged Tibo/Forecast snapshots skip unnecessary repaints. Standard/default OMP agent directories resolve without spawning an extra config-path CLI; custom/profile agent directories remain supported via PI_CODING_AGENT_DIR. Full quota and community network checks remain independent and asynchronous.
• Automatically refreshes usage every 5 minutes, countdowns every 30 seconds; retries failures after 1 minute and marks cached data as stale.
• Tab completion for every command, with descriptive options; remembers the selected layout.
• Native Right Arrow chaining (v0.1.6): choosing updates, alerts, or alerts threshold opens its nested menu automatically in OMP 18.8.8, without pressing Tab again.
• Update notifications (v0.1.4+): checks public npm metadata at most once per 24 hours, notifies once per new version, never auto-upgrades. Can be disabled.
• Low quota alerts (v0.1.5): alerts when Codex 5h or 7d remaining quota falls to 20% (warning) or 10% (critical). Each alert level is shown only once per reset window; choose a warning threshold or disable alerts.
• Tibo public announcements (v0.1.8): shows the last regular reset, banked bonus credit announcement, and any scheduled deadline after real account credits separated by │. Uses codex-resets.com as primary, codex-reset.com as secondary, tibo.cc as third-resort fallback; never merges conflicting sources.
• Reset notifications (v0.1.8): enabled by default, once per newly announced regular/banked reset, persistent deduplication and no historical replay on first install.
• Tibo forecast (v0.1.8): enabled by default, single model/API at codex-reset.com/api/forecast; shows actual 24h/48h percentages, confidence, and explicit Loading / Unavailable / No forecast / Stale states. It is experimental, not a guaranteed reset.
• Uses local omp usage (no separate API key).

Requirements

OMP 18.8.8+, an OpenAI Codex account already connected to OMP, and an active openai-codex model. The omp command must be available on PATH or discoverable as the running executable. Verified locally on Windows OMP 18.8.9 (Editor key handling originally tested with OMP 18.8.8); the GitHub Actions matrix is configured for Windows, macOS, and Linux, but passing CI does not replace real TUI testing on each OS.

Install

Install from the npm registry:

omp plugin install omp-codex-remaining

npm package: omp-codex-remaining. Alternatively, download codex-remaining.ts into ~/.omp/agent/extensions/ and restart OMP.

Once installed, restart OMP or use /reload. No manual config.yml registration is needed for a standard npm plugin installation.

Update

When a new version is published to npm, run:

omp plugin upgrade omp-codex-remaining

Restart OMP (or use /reload) after upgrading. You can check the installed version with omp plugin list.

Update notifications (v0.1.4): The extension checks public npm release metadata on startup and at most once per 24 hours afterward. A checked-at timestamp and last-notified version are saved alongside your display preference, to avoid repeated checks or duplicate notices across restarts. If a newer version exists, OMP shows the version and the manual upgrade command. Nothing installs automatically. No API key, OAuth token, or model usage is sent to npm; the network request only retrieves public package metadata. Automatic checks are on by default and can be turned off at any time using /codex-remaining updates off. A network failure will not interrupt quota display; manual checks show a warning.

Uninstall

omp plugin uninstall omp-codex-remaining

Restart OMP afterward. The saved layout preference is stored separately in codex-remaining-settings.json and can be deleted manually if you want to reset it.

Migrating from the standalone extension: after confirming the npm install succeeded, move or delete the old copy from ~/.omp/agent/extensions/. If you previously added that standalone path to config.yml under extensions:, remove only that entry, then restart OMP. Keeping both copies may register duplicate commands/widgets.

Commands

| Command | Action | | --- | --- | | /codex-remaining compact | One-line display without bars | | /codex-remaining bars | Two progress bars (default) | | /codex-remaining toggle | Switch layouts | | /codex-remaining | Open the interactive command help | | /codex-remaining help | Open the same command help | | /codex-remaining refresh | Force-refresh Codex usage now | | /codex-remaining updates | Show update notification settings | | /codex-remaining updates on | Enable daily npm update notifications | | /codex-remaining updates off | Disable automatic npm update checks | | /codex-remaining updates check | Check for a newer npm version now, even when automatic checks are off | | /codex-remaining alerts | Show quota-alert settings | | /codex-remaining alerts on | Enable low quota alerts (default) | | /codex-remaining alerts off | Disable low quota alerts | | /codex-remaining alerts threshold 20 | Set warning threshold to 10–90% (critical remains at 10%) | | /codex-remaining tibo | Open the detailed Tibo reset/forecast overlay without fetching data | | /codex-remaining tibo details | Alias for the same dedicated details overlay | | /codex-remaining tibo on | Show Tibo information after plan/credits (default) | | /codex-remaining tibo off | Hide Tibo and stop its background requests | | /codex-remaining tibo refresh | Force check new Tibo regular and banked reset records | | /codex-remaining tibo alerts | Show community reset-notification settings | | /codex-remaining tibo alerts on | Notify for newly announced resets and banked credits (default) | | /codex-remaining tibo alerts off | Turn off community reset notifications | | /codex-remaining tibo forecast | View experimental 24h/48h forecast and source | | /codex-remaining tibo forecast on | Show forecast after Tibo section (default) | | /codex-remaining tibo forecast off | Hide forecast from widget | | /codex-remaining tibo forecast refresh | Check single forecast API now |

The Help screen lists the commands, current layout and automatic refresh schedule. Close it with Enter, Esc or q. Opening Help does not fetch new quota data.

Tab autocomplete: Type /codex-remaining and press Tab to open all eight subcommands (help, compact, bars, toggle, refresh, updates, alerts, tibo) with a description beside each option. Select a command from the list and press Enter to run it. Autocomplete also works after a space, for example /codex-remaining + Tab, and filters as you type (e.g. /codex-remaining re + Tab). v0.1.6 nested menus: On OMP 18.8.8, selecting updates using Right Arrow or Tab automatically opens on, off, check without an extra Tab. Selecting alerts automatically opens on, off, threshold; selecting threshold opens common percentage presets. The right arrow accepts a popup selection only when the caret is at the end of the input; otherwise it moves the caret normally. /codex-remaining alerts threshold without a number displays syntax help instead of silently failing. You can also type a custom integer from 10 to 90.

Layout, npm update checks, and low-quota alerts are saved automatically to codex-remaining-settings.json under the directory returned by omp config path.

Low quota notifications

The default warning level is 20% remaining, with a separate critical level at 10% for both Codex 5-hour and 7-day quotas. Alerts use the most recently successfully fetched quota data; failed or stale fetches do not trigger new alerts. A message for a given level and reset window is not repeated across refreshes or restarts. If quota recovers above the warning threshold, or a new quota reset period begins, warnings can be triggered again.

Use /codex-remaining alerts off to disable automatic warnings, alerts on to re-enable, or alerts threshold 15 to set a 15% warning threshold. The critical level remains at 10%. These preferences are saved in codex-remaining-settings.json. The extension does not request separate API keys or change your OMP configuration.

Tibo public reset tracker

Community Reset data is not an official OpenAI account record. The extension reads Codex Resets (primary), Codex Reset (secondary, with its API and forecast), and Tibo (third-resort fallback). All API calls are read-only, do not include your Codex token, and run in the background. The sources are not independent proof if one republishes another. On a narrow terminal the sections wrap onto separate header rows rather than losing Forecast. The separators distinguish your actual account credits from public announcements and experimental predictions:

╭─ Codex Summary ───────────────────────────────────────────────────╮
│ ⏱ Plus · ✦ 3 exp 12d 1h                                           │
│ Tibo: Reset 7 Oct · Banked 8 Oct                                 │
│ Forecast: Reset chance within 24h: 20% · within 48h: 35% · low    │
╰───────────────────────────────────────────────────────────────────╯

╭─ Quotas ──────────────────────────────────────────────────────────╮
│ 5h ███████████████████░░░ 95%  ↻ 1h                              │
│ 7d █████░░░░░░░░░░░░░░░░ 22%  ↻ 4d                               │
╰───────────────────────────────────────────────────────────────────╯

Reset is the latest regular quota-reset announcement. Banked is the latest public announcement about bonus/banked reset credits; it does not confirm that a credit was delivered to your personal account. If a future announcement includes a deadline, it is displayed as Next ... by [date], not an exact guaranteed reset time. Stale records are labeled (stale) and outages never block the quota widget. The data loads asynchronously, can be cached locally, and can be disabled with /codex-remaining tibo off. The numbers above are illustrative, not live. Forecast uses only codex-reset.com, never averages or falls back to a different forecast model. The API currently returns 24h and 48h probabilities; this extension does not fabricate a seven-day probability. Use /codex-remaining tibo forecast for details. Every optional feature (quota alerts, npm update checks, community resets/notifications, forecast display) starts ON; any explicit OFF setting is preserved across sessions. Community alerts start from the last seen events and never replay old announcements on a fresh install. Attribution: codex-reset.com.

Native status-line behavior

v0.1.3 never modifies OMP config.yml or built-in status-line settings. If a custom OMP status line already contains the native usage segment, the extension displays a warning and pauses its own widget to avoid duplicate quota displays. Your original status line keeps working.

If you want the Codex Remaining widget instead, explicitly inspect omp config get statusLine.leftSegments and omp config get statusLine.rightSegments. Remove only the usage segment from your own custom status-line configuration, preserving every other segment, then restart OMP. This is optional and may hide native usage for other model providers. Standard OMP status-line presets are untouched.

Troubleshooting

• Select an openai-codex model for the widget to appear.
• Check omp usage --provider openai-codex --json --redact if no quota appears.
• Check omp --version if the extension cannot find the OMP executable.
• A yellow quota unavailable status means the last fetch failed; the extension retries automatically in 1 minute. stale quota means it is showing the last successful values, not live quotas.
• A failed /codex-remaining refresh shows a warning rather than reporting false success.
• If the widget is paused due to the custom native usage segment, review the read-only instructions above; the extension will not edit your configuration.

Testing

With Bun installed, run bun run test from this repository to check Help/Autocomplete, quota rendering, refresh failures/retries, read-only configuration behavior, update settings migration, version comparison, npm failure handling, nested Tab routing through OMP's forced-completion path, Right Arrow chaining-marker handling, and quota alert thresholds/duplication/recovery. Run bun run build:check to validate the bundle, and npm pack --dry-run to validate package contents. GitHub Actions runs these checks on Windows, macOS, and Linux. Tests are included in GitHub but excluded from the published npm tarball.

License

MIT, copyright 2026 Athikarn. Maintained by Athikarn (npm profile). Unofficial and not affiliated with OpenAI or Oh My Pi.