Codex Helper

Chinese README

Codex Helper is a lightweight local enhancement launcher for Codex desktop.

It focuses on a small set of local and remote workflow gaps while keeping the Codex desktop experience familiar.

Features

• Remote port forwarding: detect and forward web ports from Codex SSH sessions so remote dev servers can be opened locally.
• Helper Settings: configure Helper from a standalone window opened from the menu bar, with a UI that stays close to Codex.
• Usage-limit overlay hide: optionally hide the You're out of Codex and Work usage card. This is visual only and does not reset or bypass account limits.
• Provider management: switch ChatGPT desktop between Official ChatGPT login and API providers (DeepSeek, Kimi, MiniMax, DashScope, Zhipu GLM, Xiaomi MiMo, GitHub Copilot, xAI Grok, or custom). API providers can be mixed: every selected provider's models appear in one Codex model list, and the local proxy routes each request by model. A catalog option on each provider, off by default, prefixes those model names with the provider name. Official login stays exclusive. Helper writes ~/.codex/config.toml and a native-style model catalog. Copilot and Grok OAuth use device-code flows and store tokens in ~/.codex-helper/oauth/.
• SSH sync: Helper Settings → Sync pushes providers.json, OAuth tokens, and the active provider to other Macs over SSH. A replica Helper applies the incoming active provider locally.
• Local provider proxy: non-Official traffic goes through 127.0.0.1:3721 (/v1/responses and /v1/chat/completions). Helper injects the upstream key for the routed provider, sanitizes ChatGPT-desktop tool payloads, and retries a custom-tool rejection once as function tools. It can also expose named local Endpoint keys for other agents, and serves GET /v1/models with every model from the selected provider mix. A failed request does not switch providers.

Characteristics

• Dynamic injection: Codex Helper keeps Codex application files unchanged, so the enhancement layer is reversible.
• Focused scope: it supplements uncovered workflows instead of duplicating Codex-native capabilities or adding ambiguous actions.
• Codex-like interaction: controls follow Codex visual patterns. Helper Settings lives in its own window so Codex Settings stays untouched.

Local State

Codex Helper owns one state directory:

~/.codex-helper/
  logs/
  scripts/
  config.json
  providers.json
  endpoint.json
  oauth/
  sync.json
  state.json

Diagnostics are written to dated JSONL files under ~/.codex-helper/logs/ (codex-helper-YYYY-MM-DD.jsonl, local date). Helper Settings → Logs can page through them, search their contents, and open a record to inspect its stored detail. A Diagnostics setting (off by default) can also record API-provider LLM request metadata from the local Helper proxy (secrets stripped from headers, plus a short user-message preview). Request and response bodies are not stored. When that setting is on, Helper may also keep a bounded compat summary for suspect responses or rewritten function_call items. Official ChatGPT login traffic is not included.

Development

bun install
bun run check
bun run launch
env RUSTC_WRAPPER= cargo test --manifest-path src-tauri/Cargo.toml
bun run build:app

The Tauri backend currently targets macOS /Applications/ChatGPT.app by default.

Bun is used for development scripts in this repository. A built CodexHelper.app runs as a Rust/Tauri application and does not require Bun at runtime; injected scripts execute inside the Codex renderer.

bun run build:app runs scripts/build-macos-dmg.sh and writes dist/macos/CodexHelper-<version>-macos-<arch>.dmg.

Releases

Push a v* tag to build signed, notarized DMGs and updater archives via GitHub Actions. See docs/release-guide.md for secrets and local signing. Helper Settings → About checks latest.json from GitHub Releases and can install the update.

App and menu bar icons live in src-tauri/icons/:

• icon.png — application icon (committed; used for .app / DMG and Tauri bundle metadata)
• tray.png — menu bar template source (black on transparent; build generates tray-menu.png)

If local Rust builds fail with sccache: error: Operation not permitted, run Cargo with RUSTC_WRAPPER= as shown above.

Acknowledgements

This project learned from the dynamic launcher approach used by BigPizzaV3/CodexPlusPlus and the tweak-oriented user experience explored by b-nnett/codex-plusplus.