A desktop control center for running, configuring, extending, and repairing Codex in the ChatGPT desktop app.
Download · Download guide · Build from source · Troubleshooting
ChatGPT Codex Tools brings the scattered parts of a local Codex setup into one approachable desktop manager. Launch ChatGPT with the right connection mode, switch API providers, manage enhancements and scripts, repair missing conversation history, and collect useful diagnostics without editing configuration files by hand.
Important
This is an independent community project. It is not affiliated with or endorsed by OpenAI. You still need the official ChatGPT desktop app and must follow the terms of any service or API provider you use.
See the guided first-run setup
ChatGPT Codex Tools is more than an alternative launcher. It manages the local state around ChatGPT Codex and keeps connection settings, conversation ownership, extensions, and recovery workflows consistent when you change providers or desktop versions.
- One control plane instead of scattered config files. Change providers, models, MCP servers, Skills, Plugins, enhancements, and scripts from a desktop UI. The manager applies the related local configuration together instead of requiring manual edits across several files.
- Official access and custom APIs can coexist. Hybrid API mode keeps an official ChatGPT account bound for native capabilities while sending supported model requests through a configured API endpoint. Pure relay mode is also available when official sign-in is not required.
- Provider switching includes state migration. When the active mode changes, the manager can synchronize provider attribution in local conversation history so existing threads remain visible under the new setup.
- Risky maintenance actions are backup-first. Conversation repair and Skill/MCP restoration validate prerequisites, create recoverable snapshots, and limit changes to the relevant records or TOML tables.
- Enhancements live inside the Codex experience. A local renderer bridge adds practical actions to the ChatGPT Codex interface rather than forcing every workflow back into a separate utility window.
- Detects the operating system, CPU architecture, ChatGPT installation, manager runtime, and required local paths.
- Finds CCSwitch when installed and imports its Codex provider profiles; CCSwitch is optional and can be skipped.
- Creates the dedicated ChatGPT Codex entry point and launches ChatGPT with the selected helper, bridge, and connection mode.
- Shows readiness, active provider, enhancement mode, entry-point status, and common repairs on the home dashboard.
- Handles restarts and single-instance coordination so stale helper processes are less likely to break a launch.
| Mode | Best for | Behavior |
|---|---|---|
| Official sign-in | Using the standard ChatGPT account and native Codex behavior | Keeps requests and account state on the official path. |
| Official hybrid API | Keeping official login-dependent features while using another compatible model endpoint | Binds a provider to an official account, preserves native site/plugin capabilities, and routes supported API traffic through the configured Base URL and key. |
| Relay API | Using a compatible proxy, aggregator, or self-hosted endpoint without official login | Applies the selected provider, protocol, model list, context window, optional upstream proxy, and local relay settings. |
Provider management includes reusable profiles, drag-to-reorder, connectivity tests with a chosen model, model-list and context-window overrides, protocol selection, optional per-provider proxies, and imported CCSwitch metadata. Aggregated profiles can rotate requests across multiple API providers according to the configured strategy.
Enhancements can be enabled individually and are applied to the ChatGPT Codex renderer through the local bridge:
- Unlock locally configured and upstream-discovered models in the model picker.
- Delete conversations and export them as timestamped Markdown.
- Move projects and add a conversation Timeline for easier navigation.
- Create a Git worktree from the latest
upstream/<base-branch>instead of the current localHEAD. - Load local user scripts and marketplace scripts without manually editing the desktop application bundle.
- Expose a local mobile-control entry point through the built-in helper.
The manager distinguishes full, hybrid, and compatible enhancement modes. In particular, hybrid mode preserves official account-dependent site and plugin behavior, while pure relay mode avoids enabling features that require official access.
- Manage Codex MCP servers, Skills, Plugins, marketplaces, and related feature flags from one screen.
- Merge provider-specific configuration into
config.tomlduring provider changes while preserving unrelated common configuration. - Scan locally cached plugins and restore missing plugin, marketplace, and
node_replMCP entries. - Create, label, list, restore, and delete Skill/MCP snapshots stored under
~/.codex/backups_state/skill-mcp. - Browse the script marketplace, install or update scripts, toggle them individually, and manage local scripts alongside marketplace items.
Two focused repair flows address common cases where older Codex threads disappear or fail to load:
- Mode-history synchronization updates provider ownership and local indexes after a connection-mode change. It creates a full backup first and does not delete message content.
- Response-item repair removes only the incompatible top-level
namespacefield from affected historical tool-call payloads. It leaves message text, tool output, and nested arguments untouched.
Before writing, the repair flow requires ChatGPT and Codex to be closed, scans candidate files, calculates the required backup space, and stops safely when prerequisites are not met. Progress, changed-file counts, repaired-record counts, and the backup directory are shown in the UI.
- Live logs cover launcher activity, renderer script loading, bridge requests, bridge responses, and repair operations.
- The generated diagnostic report includes application version, platform, important paths, and relevant settings for support requests.
- Maintenance actions repair desktop entry points, configuration paths, provider synchronization, plugin state, and other local integration problems.
- Backups are surfaced in the UI so a repair or restore operation has a clear recovery path rather than being a one-way mutation.
Use the latest GitHub release or the friendlier download guide.
| Platform | Installer | Portable build |
|---|---|---|
| macOS Apple Silicon | macos-arm64 |
ARM64 zip |
| macOS Intel | macos-x64 |
x64 zip |
| Windows PC | windows-x64 |
x64 zip |
| Windows ARM | windows-arm64 |
ARM64 zip |
Warning
Current macOS packages are not signed or notarized. Gatekeeper may report that the installer or app cannot be opened. See macOS blocks the app before changing any system security setting.
- Install the official ChatGPT desktop app.
- Download the package that matches your operating system and CPU architecture.
- Open ChatGPT Codex Manager and complete the guided setup.
- Choose an official or compatible API connection.
- Launch ChatGPT from the ChatGPT Codex entry created by the manager.
The manager keeps the primary launch action, connection state, enhancements, and repair shortcuts on its home screen. Advanced configuration remains available when you need it, but is not required for a normal first launch.
- Go 1.26
- A current Node.js and npm installation
- Platform build tools required by Go and the desktop webview
npm --prefix web install
npm --prefix web run vite:build
go run .npm --prefix web run check
npm --prefix web run vite:build
go test ./...
go build -o codextools .The project uses a Go backend and a React 19 + Vite frontend. The backend discovers the local ChatGPT installation, manages settings and providers, launches the appropriate desktop processes, and exposes a loopback-only manager service. A Chrome DevTools Protocol bridge connects approved UI actions inside ChatGPT to the local helper.
React manager UI
|
Local Go manager ── settings, providers, repair, scripts, diagnostics
|
Desktop launcher ── ChatGPT process + renderer bridge
|
ChatGPT Codex UI enhancements
The Go backend remains in a single main package so release builds can select binary roles through -ldflags "-X main.binaryRole=...". Responsibilities are separated across focused files such as manager.go, launcher.go, bridge.go, relay.go, repair.go, and diagnostics.go.
Make sure ChatGPT was opened through the ChatGPT Codex entry rather than its normal application shortcut. Open Diagnostics and Logs in the manager to check the launch and injection state.
Test the local endpoint from PowerShell:
Invoke-RestMethod -Method Post -Uri http://127.0.0.1:57321/backend/status -Body "{}" -ContentType "application/json"If the endpoint responds but the plugin still times out, restart ChatGPT through ChatGPT Codex. In the logs, look for renderer.script_loaded, bridge.request, and bridge.response; missing events usually point to the renderer bridge or a stale script cache.
If Gatekeeper blocks the downloaded package, remove quarantine from that package and retry the installation:
sudo xattr -rd com.apple.quarantine ~/Downloads/ChatGPT-Codex-Tools-*-macos-*.pkgIf the installed apps are blocked at launch, remove quarantine from those apps:
sudo xattr -rd com.apple.quarantine "/Applications/ChatGPT Codex 管理工具.app"
sudo xattr -rd com.apple.quarantine "/Applications/ChatGPT Codex.app"Only run these commands for files you downloaded from this project's official GitHub releases and understand the security implications of bypassing quarantine.
The Upstream worktree action updates the remote branch first and then performs the equivalent of:
git worktree add -b <new-branch> <worktree-path> upstream/<base-branch>The new worktree therefore starts from the latest remote-tracking branch instead of the current local HEAD. If the manager cannot safely detect the native worktree form in your ChatGPT version, enter the repository, branch, worktree path, remote, and base branch manually from the ChatGPT Codex Tools menu.
ChatGPT Codex Tools is actively developed as an open community project. It does not accept sponsorships or donations. Source, product direction, and release history remain public so the project can be studied, discussed, and forked.
No license file is currently included in the repository. Do not assume redistribution rights beyond those explicitly granted by the copyright holder.
Thanks to the earlier community projects that established the foundation, workflows, and user-facing direction behind this independent Go refactor, and to everyone reporting compatibility issues across ChatGPT desktop releases.