quosparr

command module
v1.0.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 13, 2026 License: AGPL-3.0 Imports: 14 Imported by: 0

README

English · 简体中文 · 繁體中文 · 한국어 · 日本語 · Русский · Français

CodexRunway logo

CodexRunway

How much longer can your Codex keep running?

CodexRunway is a native macOS menu bar app for checking Codex and Grok quota. It also provides Codex Reset Updates, reset credits, API-equivalent cost, and local sessions, with separate multi-account management for each provider.

https://github.com/user-attachments/assets/76cbc417-b237-42a7-a2a7-a68b18ae21a8

Highlights

  • Check remaining Codex quota from the menu bar.
  • Switch from the always-visible Codex | Grok tabs; the menu bar and context menu follow the selected provider.
  • View included Grok quota, product breakdown (Build / Imagine / Chat), weekly/monthly periods, prepaid balance, and on-demand usage via the official CLI chat-proxy billing API.
  • On the Grok panel, reuse the same Token Usage multi-chart (heatmap / line / bar) and API Equivalent Cost modules as Codex, plus recent local sessions from Grok CLI logs.
  • Manage multiple Grok OAuth / SuperGrok accounts with isolated sign-in, current-login import, paste token/JSON, refresh, aliases, ordering, removal, and explicit switching.
  • View 5-hour, weekly, and additional quota windows.
  • See whether Codex rate limits have reset today (data from Did Codex Reset), with a link to the related public post.
  • Toggle the “Codex Reset Updates” section in settings and configure its own refresh interval (on by default, every 5 minutes).
  • Manage multiple Codex accounts: browser sign-in, import local auth.json, paste token/JSON (including /auth/session), import files, or add an API key.
  • Switch accounts safely after confirmation by atomically writing ~/.codex/auth.json, with an optional Codex restart so CLI / IDE stay in sync.
  • Show the current account, subscription tier, and expiration.
  • Estimate this week’s Codex allowance from official weekly usage percent and daily Credits, compare it with previous weeks to spot quota cuts, and toggle the module in settings (on by default).
  • View reset credit count, status, and expiration time.
  • View API-equivalent cost and token usage for today, the current cycle, the previous cycle, this month, or a custom range; the default range is configurable in settings.
  • Show a year-to-date token usage chart under quota on the main panel (heatmap / line / bar; daily / weekly / cumulative); style is switchable in the panel and settings, heatmap by default; can be turned off.
  • Use a local incremental session index for faster cost scans.
  • View recent Codex sessions, projects, status, and usage summaries.
  • Repair the local session index.
  • Support light, dark, system appearance, and English, 简体中文, 繁體中文, 한국어, 日本語, Русский, Français.
  • Support built-in update checks.
  • Offer macOS 14+ desktop widgets for quota overview, token trend, a key metric, and Codex Reset Updates.

Screenshots

CodexRunway quota overview CodexRunway reset credits details CodexRunway API-equivalent cost CodexRunway setting page CodexRunway multi-account CodexRunway Grok quota

Installation

Install from the project-maintained Licoy Homebrew Tap:

brew install --cask licoy/tap/codex-runway

CodexRunway also supports in-app updates. To force Homebrew to check and install an upgrade, use:

brew upgrade --cask --greedy codex-runway

Uninstalling keeps settings and managed account copies by default. Adding --zap also removes data under ~/.codex-runway, but does not delete the official ~/.codex or ~/.grok directories or sessions:

brew uninstall --cask codex-runway
brew uninstall --cask --zap codex-runway
Manual installation

Download the matching DMG from GitHub Releases:

  • Apple Silicon: CodexRunway-macos-arm64.dmg
  • Intel: CodexRunway-macos-x86_64.dmg

Open the DMG and drag CodexRunway.app into Applications, or download and unpack the ZIP for the same architecture.

On its first launch, the installed app requests launch at login by default; you can turn it off or on in Control Panel → General → Launch at login. If macOS requires approval, use Open Login Items Settings to allow it. Later launches respect changes made in System Settings; command-line and development runs do not register login items.

macOS Security Blocks

Current releases are ad-hoc signed and not notarized. If macOS says the developer cannot be verified or the app was not checked for malicious software, right-click CodexRunway.app and choose Open, or go to System Settings > Privacy & Security and click Open Anyway.

If macOS says CodexRunway.app is damaged and should be moved to the Trash, it is usually the download quarantine attribute. After placing the app in Applications, run:

xattr -dr com.apple.quarantine /Applications/CodexRunway.app

Then open the app again.

Requirements

  • macOS 12+

  • Codex installed and used on this Mac is recommended

  • Import from local ~/.codex/auth.json, or add accounts in the app (browser sign-in, paste credentials, import files, and more)

  • Before using the Grok panel, install the official Grok CLI:

    curl -fsSL https://x.ai/cli/install.sh | bash
    
  • Grok account management and billing support OAuth / SuperGrok and compatible legacy sessions only. Run grok login --oauth, sign in from the app, import the current login, or paste ~/.grok/auth.json / credential JSON. API-key-only credentials are not added as managed accounts.

  • When GROK_HOME is set, the app uses that directory; otherwise it uses ~/.grok. See xAI Settings.

Run Locally

swift run CodexRunway

On macOS 14+, this command automatically builds and registers a separate CodexRunway Dev app and Widget extension, then launches it. The development app lives at .build/codex-runway-widget-dev/CodexRunway-dev.app and can be added directly from the system widget gallery. Quit any other running CodexRunway instance first. Set CODEX_RUNWAY_DISABLE_DEV_APP=1 only when you want the raw unpackaged command-line process without widgets.

Self-check:

swift run CodexRunway --self-check

The self-check reads local state only and makes no network request. It prints redacted Codex diagnostics plus the Grok CLI version, credential status, and account identity. Tokens and API keys are never printed.

Desktop Widgets

Desktop widgets require macOS 14 or later. Starting with a release that contains this fix, public releases and local development builds both include the Widget extension. Each widget can independently select Codex, Grok, or both in Edit Widget; Codex Reset Updates is Codex-only. After upgrading, macOS registers the production widget from the app's Contents/PlugIns directory.

swift run CodexRunway uses separate swift-dev identifiers and does not replace an existing installation. You can also package a widget-enabled app manually with .dev identifiers:

INCLUDE_WIDGET=1 \
RUNWAY_BUNDLE_ID=com.github.codex-runway.dev \
RUNWAY_APP_GROUP_ID=group.com.github.codex-runway.dev \
RUNWAY_WIDGET_STORAGE_MODE=local \
bash Scripts/package-app.sh

The app is written to dist/CodexRunway.app. Public releases containing this fix and local ad-hoc builds use the read-only versioned derived snapshot at ~/.codex-runway/widget-snapshot.json with 0600 permissions. A Developer ID build with a registered App Group can instead set RUNWAY_WIDGET_STORAGE_MODE=app-group. The snapshot contains no email, account ID, token, auth JSON, or raw external event text. Developer ID signing, App Group registration, and notarization remain available as future distribution work.

Network proxy

In Control Panel → General → Network, choose Follow System, HTTP Proxy, or SOCKS5 Proxy; custom proxies support username and password authentication. The setting covers Codex requests, app-initiated Grok requests and CLI operations, public status and pricing feeds, and software update checks, release notes, and package downloads. Browser sign-in pages and already-running external CLI processes keep their own network settings; the system proxy is not changed.

Changes apply only after Save Proxy Settings; a running update keeps the configuration it started with. Test Connection uses the current draft to fetch the public update feed without sending account credentials or saving the draft. Proxy credentials are stored in the macOS Keychain, separately from non-secret preferences. Invalid configuration, unavailable credentials, or a failed custom proxy do not trigger a direct connection; fix the settings or explicitly switch back to Follow System.

Privacy

  • Tokens are read from local ~/.codex/auth.json; multi-account credentials are stored only under ~/.codex-runway/accounts/<id>/auth.json (directory mode 0700, file mode 0600). The account index index.json never contains tokens.
  • Official Grok credentials are read from $GROK_HOME/auth.json (or ~/.grok/auth.json when unset). Managed copies live at ~/.codex-runway/accounts/grok-<stable-id>/auth.json with directory mode 0700 and file mode 0600; the separate ~/.codex-runway/accounts/grok-index.json contains no tokens.
  • Grok quota is fetched with the local OAuth credential against the official CLI chat-proxy /v1/billing?format=credits endpoint (the same official API the Grok CLI uses). The app does not read browser cookies or infer fake quota from local sessions.
  • While refreshing the current Grok account, the official CLI may rotate tokens; the app mirrors the resulting official credentials only to that managed account. Non-current accounts use an isolated GROK_HOME and never write the official credentials.
  • A Grok account switch replaces only OAuth / compatible legacy login scopes in the official credentials while preserving API-key and unknown scopes. A switch is guaranteed only for new sessions. Running Grok processes are not terminated and may write the previous account back, so the app shows a strong warning before continuing.
  • Official ~/.codex/auth.json is overwritten only when you confirm an account switch (atomic write), so Codex CLI / IDE stay in sync.
  • Refreshing a non-active managed account updates only its library copy, not official auth.json. Refreshing the active account keeps the official auth file and the library copy in sync.
  • Invalid or mock credentials are never written back to official ~/.codex/auth.json.
  • Access tokens, refresh tokens, ID tokens, and API keys must not be written to logs, README files, issue templates, or self-check output.
  • API-equivalent cost is computed from local session JSONL logs by default, with derived data such as a local incremental index under ~/.codex-runway/. Session contents are not uploaded.
  • Weekly quota estimates store only derived Credits totals and percents in ~/.codex-runway/quota-estimate-history.json. No tokens or keys.
  • Online usage supplements API-equivalent cost only when local token data is unavailable. The chart’s “Official stats (all devices)” series comes from current-account profile statistics and may lag or be revised; “Local logs (all sessions)” scans the sessions present on this Mac and historical entries may span accounts. Daily values in this comparison use UTC dates so both sources share the same day boundary. The two series are not a subset relationship and should not be subtracted.
  • Session repair only touches ~/.codex/session_index.jsonl, creates a backup before writing, and never deletes session files.
  • “Codex Reset Updates” only downloads the public status feed from Did Codex Reset. It sends no Codex account, token, or local session content.
  • Update checks request only version information. Codex account and session data are not uploaded.
  • Widget snapshot storage contains only non-secret derived quota, balance, cost, daily-token, and reset-status data. The main app is the sole writer; widgets are read-only.

Data sources

  • Codex Reset Updates: Data comes from Did Codex Reset at https://didcodexreset.com/api/status.json. Unofficial and advisory only; may be delayed or temporarily unavailable.
  • Once a schedule enters its awaiting-confirmation phase, the app uses that schedule's grace duration from the public feed, falling back to 3 hours for older feeds. Longer values such as 24 or 72 hours may cross local calendar days; they remain awaiting confirmation rather than reporting a completed reset, and end only at the actual deadline. A network refresh failure keeps the latest valid status and shows the error in reset details; public status data still becomes unavailable after 30 hours without a producer update.
  • Quota / reset credits / quota estimate / official token usage / some online usage: When signed in, requests use your local credentials against official ChatGPT / Codex backend APIs. Official token usage belongs to the current account and shows the backend statistics date. Quota estimate is unofficial: weekly allowance is extrapolated from weekly used percent and daily Credits (1000 Credits ≈ $40, version credits-usd-2026-08-26).
  • Grok quota: Returned only by the official CLI chat-proxy /v1/billing?format=credits endpoint using a local OAuth / SuperGrok login. There is no secondary data source, and API billing or local-session statistics are not mixed into this quota.
  • Grok API-equivalent cost / local sessions: Computed from local ~/.grok/sessions turn_completed usage using official xAI Text API prices (input / cached / output; prompts ≥ 200k use long-context rates; price book xai-builtin-2026-09-27). Unknown models are not invented as exact costs. CLI costUsdTicks is subscription-credit accounting and is not used as API-equivalent cost.
  • Local-log token usage / API-equivalent cost / recent sessions: Computed by default from local ~/.codex session logs and the local index. Historical local logs have no reliable account attribution, so they may include multiple accounts.

Development and Contribution

swift test
swift build
swift build -c release

See CONTRIBUTORS.md for contribution notes.

Community

License

This project follows the repository LICENSE.

Documentation

Overview

Quosparr is a menu-bar / system-tray monitor for local Codex quota, reset credits and API-equivalent cost.

Directories

Path Synopsis
Scripts
gen-glyphs command
Command gen-glyphs writes internal/app/glyphs_gen.go: the interface icons, taken from Remix Icon (https://remixicon.com, Remix Icon License v1.0), and copies the provider SVGs from LobeHub Icons (https://icons.lobehub.com, MIT) into internal/app/assets/providers.
Command gen-glyphs writes internal/app/glyphs_gen.go: the interface icons, taken from Remix Icon (https://remixicon.com, Remix Icon License v1.0), and copies the provider SVGs from LobeHub Icons (https://icons.lobehub.com, MIT) into internal/app/assets/providers.
gen-l10n command
Command gen-l10n converts the Swift localization tables into internal/l10n/tables_gen.go.
Command gen-l10n converts the Swift localization tables into internal/l10n/tables_gen.go.
release-assets command
release-assets signs final, post-processed archives using mygo v0.4.1's Ed25519-over-SHA256 protocol; the private key is read only from the environment.
release-assets signs final, post-processed archives using mygo v0.4.1's Ed25519-over-SHA256 protocol; the private key is read only from the environment.
verify-sqlite command
verify-sqlite exercises only the explicitly named packaged runtime, in memory.
verify-sqlite exercises only the explicitly named packaged runtime, in memory.
internal
alerts
Package alerts decides which quota, reset-credit and rate-limit-reset notifications are new.
Package alerts decides which quota, reset-credit and rate-limit-reset notifications are new.
app
Package app is the Quosparr host: tray icon, panel and the startup sequence.
Package app is the Quosparr host: tray icon, panel and the startup sequence.
codex
Package codex reads and writes Codex credentials and Quosparr's managed multi-account library.
Package codex reads and writes Codex credentials and Quosparr's managed multi-account library.
codexapi
Package codexapi talks to the ChatGPT/Codex backend: quota and reset credit requests, the OAuth refresh and login (PKCE) exchanges, and the models they return.
Package codexapi talks to the ChatGPT/Codex backend: quota and reset credit requests, the OAuth refresh and login (PKCE) exchanges, and the models they return.
estimate
Package estimate ports QuotaEstimate.swift, QuotaEstimateAvailability.swift and QuotaEstimateHistoryStore.swift: how many Credits a full quota window is worth, extrapolated from the Credits used so far in the current cycle.
Package estimate ports QuotaEstimate.swift, QuotaEstimateAvailability.swift and QuotaEstimateHistoryStore.swift: how many Credits a full quota window is worth, extrapolated from the Credits used so far in the current cycle.
export
Package export writes the files other programs read: the status JSON for scripts (status.json), the widget snapshot for the WidgetKit extension (widget-snapshot.json) and the widget's deep-link and layout contract.
Package export writes the files other programs read: the status JSON for scripts (status.json), the widget snapshot for the WidgetKit extension (widget-snapshot.json) and the widget's deep-link and layout contract.
export/swiftjson
Package swiftjson writes JSON that is byte-identical to what the Swift app's JSONEncoder produced for the shared on-disk files (status.json, widget-snapshot.json, alerts.json, quota-estimate-history.json, reaction-visitor.json), and reads the numbers and dates it wrote.
Package swiftjson writes JSON that is byte-identical to what the Swift app's JSONEncoder produced for the shared on-disk files (status.json, widget-snapshot.json, alerts.json, quota-estimate-history.json, reaction-visitor.json), and reads the numbers and dates it wrote.
grok
Package grok manages the Grok accounts of Quosparr: parsing the Grok CLI credential file, the managed multi-account library, import and export, the OAuth login and token refresh.
Package grok manages the Grok accounts of Quosparr: parsing the Grok CLI credential file, the managed multi-account library, import and export, the OAuth login and token refresh.
l10n
Package l10n ports Quosparr's Swift localization layer: the translation tables, system-language resolution and Swift-style format strings.
Package l10n ports Quosparr's Swift localization layer: the translation tables, system-language resolution and Swift-style format strings.
migration
Package migration performs the one-time, non-destructive brand migration.
Package migration performs the one-time, non-destructive brand migration.
netx
Package netx builds the explicit HTTP clients Quosparr uses for every network request.
Package netx builds the explicit HTTP clients Quosparr uses for every network request.
platform
Package platform holds the small operating-system boundaries of Quosparr: the single-instance lock and the app-owned directory.
Package platform holds the small operating-system boundaries of Quosparr: the single-instance lock and the app-owned directory.
resettoday
Package resettoday is the Go port of Quosparr's "did Codex reset today" feature: the hosted status feed (RateLimitResetToday*.swift), its strict decoder, the verdict and next-scheduled-reset rules, the optional reaction service, and the controllers that poll and refresh them.
Package resettoday is the Go port of Quosparr's "did Codex reset today" feature: the hosted status feed (RateLimitResetToday*.swift), its strict decoder, the verdict and next-scheduled-reset rules, the optional reaction service, and the controllers that poll and refresh them.
resettoday/runwayfmt
Package runwayfmt adapts internal/runway's duration and schedule formatting to the resettoday.Formatter the detail copy needs.
Package runwayfmt adapts internal/runway's duration and schedule formatting to the resettoday.Formatter the detail copy needs.
runway
Package runway is the Codex-side application coordinator.
Package runway is the Codex-side application coordinator.
sessions
Package sessions reads the Codex session files under ~/.codex for the recent sessions list (Scanner) and diagnoses or repairs ~/.codex/session_index.jsonl (Repairer).
Package sessions reads the Codex session files under ~/.codex for the recent sessions list (Scanner) and diagnoses or repairs ~/.codex/session_index.jsonl (Repairer).
store
Package store is the compatibility layer for Quosparr's user preferences and network proxy settings.
Package store is the compatibility layer for Quosparr's user preferences and network proxy settings.
usage
Package usage reads Codex session logs and turns them into API-equivalent cost summaries.
Package usage reads Codex session logs and turns them into API-equivalent cost summaries.
usage/decimal
Package decimal is a small exact decimal type that follows the arithmetic and text rules of Foundation's Decimal for the operations the usage cost code needs: construction from integers and text, addition, multiplication, division, comparison, and JSON numbers.
Package decimal is a small exact decimal type that follows the arithmetic and text rules of Foundation's Decimal for the operations the usage cost code needs: construction from integers and text, addition, multiplication, division, comparison, and JSON numbers.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL