Claudex is an open source compatibility layer for using Codex GPT models and native Claude models through the Claude Code interface. It reuses the Codex login already on your computer, configures the local bridge automatically, and keeps native Claude authentication separate. Supported Claude and GPT sessions can run at the same time in separate processes.
Important
Claudex is an independent community project. It is not affiliated with, endorsed by, or supported by OpenAI or Anthropic. Its installer uses the official Codex CLI npm package and Claude Code installer when either prerequisite is missing. You remain responsible for the terms and usage limits of those services.
Install Claudex, then complete the official Codex browser sign in when prompted.
macOS, Linux, or WSL:
curl -fsSL --proto '=https' --tlsv1.2 https://claudex.work/install.sh | bashWindows PowerShell:
irm https://claudex.work/install.ps1 | iexThese small website bootstraps resolve the latest stable GitHub release, validate its published SHA-256 digest and archive paths, and only then run the native Claudex installer. The longer download first commands below are useful when you want to inspect the bootstrap before running it.
brew install BeamoINT/tap/claudex # macOS or LinuxWindows users can also install from the BeamoINT Scoop bucket:
scoop bucket add beamoint https://github.com/BeamoINT/scoop-bucket
scoop install beamoint/claudexThen run claudex --login. Package installs bootstrap their private managed
configuration automatically on first use. See the
package manager guide for upgrades and WinGet
submission status; WinGet is not currently an installable channel.
curl --fail --silent --show-error --location --proto '=https' --tlsv1.2 \
--output /tmp/claudex-bootstrap.sh \
https://raw.githubusercontent.com/BeamoINT/Claudex/main/bootstrap.sh
bash /tmp/claudex-bootstrap.sh
claudexThe bootstrap verifies the latest release archive before running it. The installer
opens Codex's official browser login only when authentication is needed and the
terminal is interactive. If ~/.local/bin is not on your PATH, follow the
instruction printed by the installer.
Invoke-WebRequest -UseBasicParsing https://raw.githubusercontent.com/BeamoINT/Claudex/main/bootstrap.ps1 -OutFile "$env:TEMP\claudex-bootstrap.ps1"
powershell.exe -NoLogo -NoProfile -ExecutionPolicy Bypass -File "$env:TEMP\claudex-bootstrap.ps1"
claudexThe installer adds the Claudex launcher directory to your user PATH. Open a new terminal if the claudex command is not immediately available.
For release downloads, system requirements, updating, and removal, see the installation guide.
- Automatic authentication through the existing Codex desktop or CLI session, including live account switch detection and clear login/logout recovery.
- Friendly model choices for GPT-5.6 Sol, Terra, Luna, and Solplan.
- Solplan planning with Sol and implementation with Terra.
- Native Fable, Opus, Sonnet, and Haiku shortcuts plus direct access to every model ID accepted by the installed Claude Code CLI.
- Fableplan planning with native Fable and isolated implementation with managed Terra. Only bounded plan text crosses between the two processes.
- Concurrent Claude and GPT sessions with separate provider environments and no shared credential process.
- Auto, max effort, and Ultracode modes with explicit and separate behavior.
- Stable context accounting and automatic compaction near 280k tokens.
- Codex usage limit reporting in the status line and through
/usage-limit. - Automatic, non destructive discovery of already installed Claude Code and
Codex skills, including Codex bundled/system skills, project skills, legacy
Claude commands, and enabled plugin skills, with native
/skillexecution and Codex style$skillreferences inside Claudex. - The detected ChatGPT subscription tier in the startup banner instead of Claude Code's misleading API billing label.
- Native agent activity labels that include model, reasoning effort, and task,
such as
Terra (high) - Audit JSON parser bugs. - Supported launchers and installers for macOS, Linux, Windows, and WSL, with the narrower hosted CI coverage shown below.
- Explicit native Codex and clean native Claude routes for harness specific features that should not be translated.
- Claude Code argument pass through, resume command rewriting, task cleanup, bounded retries, and compatibility detection.
- A clean full screen terminal experience without exposing launch commands or internal tool traffic unnecessarily.
- An optional direct Claude profile for the officially supported Claude in Chrome path.
Claudex keeps its generated configuration under ~/.config/claudex and does not replace your normal Claude Code settings. It never commits or bundles your Codex tokens, Claude sessions, prompts, history, or usage data.
claudex Start with Sol and auto mode
claudex --terra Start with Terra
claudex --luna Start with Luna
claudex --solplan Use Sol for planning and Terra for implementation
claudex --fable Start native Claude Code with Fable
claudex --opus Start native Claude Code with Opus
claudex --sonnet Start native Claude Code with Sonnet
claudex --haiku Start native Claude Code with Haiku
claudex --claude-model ID Start native Claude Code with an alias or full model ID
claudex --fableplan "TASK" Let Fable plan read only, then let Terra implement
claudex --max-effort Use Claude Code's maximum reasoning effort
claudex --ultracode Enable the session-scoped Ultracode workflow
claudex --manual Disable automatic permissions for this launch
claudex --usage-limit Refresh and display Codex plan limits
claudex skills List Claude and Codex skills available in this project
claudex --accounts List locally available Codex usage accounts
claudex --doctor Check installation, authentication, and models
claudex --login Sign in through Codex and synchronize the session
claudex --logout Sign out and clear the managed bridge session
claudex self-update --status Inspect automatic update state
claudex self-update --apply Apply the latest stable release now
claudex codex ... Use the native Codex harness
claudex claude ... Use the native Claude harness
claudex --remote-control Use Claude Remote Control with the direct Anthropic profile
claudex ultrareview ... Use Claude Ultrareview with the direct Anthropic profile
claudex --claude-chrome Use the direct Claude profile with Chrome support
Inside Claudex, /model solplan selects Solplan and /usage-limit prints the detailed quota report. Existing Claude and Codex skills can be referenced with /skill-name or $skill-name; see the skills guide for discovery and collision behavior. Unknown options and supported Claude Code subcommands are passed through unchanged. See the usage guide for the complete command reference.
The GPT model picker belongs to a managed Codex backed process. Native Claude
selectors launch a separate first party Claude process and preserve the caller
owned profile. For complete native argument control, use
claudex claude --model MODEL .... Open a Claude process and a GPT process in
separate terminals to use both providers concurrently. Claudex never places
both providers' credentials or routing variables in one process.
Use claudex codex ... for complete native Codex harness access and
claudex claude ... for complete native Claude harness access, subject to the
installed CLI, caller owned provider configuration, account, platform, and
service entitlements. The
default GPT backed mode translates only the portable semantics documented in
the compatibility matrix; it does not emulate Codex only tools or activate the
non skill components of Codex plugins inside Claude Code.
| Platform | Status | Hosted CI evidence | Installer |
|---|---|---|---|
| macOS 13+ on Apple silicon or Intel | Supported | macos-latest; hosted CI does not exercise both CPU architectures |
install.sh |
| Ubuntu 20.04+, Debian 10+, and compatible Linux on x64 or ARM64 | Supported | ubuntu-latest plus an Ubuntu 20.04 container on x64; no hosted ARM64 job |
install.sh |
| Windows 10 1809+, Windows 11, and Windows Server 2019+ on x64 or ARM64 | Supported | windows-latest on x64; no hosted ARM64 job |
install.ps1 |
| WSL 1 or WSL 2 | Supported as a Linux environment | No dedicated hosted WSL job | install.sh |
"Supported" means the installer and launcher contain an explicit platform path; it does not mean every operating system and CPU combination runs in hosted CI. Claude Code's own platform limitations still apply. In particular, native Windows does not provide the same sandbox implementation as macOS, Linux, and WSL2, and Claude in Chrome follows Anthropic's browser, plan, and environment requirements.
| Guide | Purpose |
|---|---|
| Documentation index | Find the right guide quickly |
| Installation | Requirements, setup, updates, and removal |
| Package managers | Homebrew and Scoop installation; WinGet submission status |
| Usage | Commands, model modes, Chrome, and pass through behavior |
| Configuration | Supported environment variables and settings |
| Skills | Existing Claude Code and Codex skill discovery, aliases, and compatibility |
| Architecture | Components, data flow, authentication, and trust boundaries |
| Troubleshooting | Diagnose common installation and runtime problems |
| Development | Repository layout, tests, and release workflow |
| Claude Code and Codex compatibility | Capability classifications, tested adaptations, and non portable boundaries |
| Roadmap | Current priorities, contribution ideas, and non goals |
Project policies and history are in CONTRIBUTING.md, GOVERNANCE.md, MAINTAINERS.md, SECURITY.md, SUPPORT.md, and CHANGELOG.md.
claudex command
-> managed GPT route: validates Codex, refreshes the loopback bridge,
and launches an isolated Claude Code profile
-> native Claude route: removes managed routing and launches the normal
Claude profile with the requested model
-> Fableplan route: captures a private native Fable plan, then launches
an isolated managed Terra implementer
-> preserves supported Claude Code commands and options on each route
The installer downloads a pinned CLIProxyAPI release, verifies its published SHA-256 digest, and binds it to 127.0.0.1 on a dedicated port with a generated local key. The dependency is not vendored into this repository and retains its own license. Read the architecture guide and third party notice before changing authentication or proxy behavior.
Contributions are welcome. Start with CONTRIBUTING.md, which covers local setup, testing, cross platform expectations, pull requests, and the project's no CLA contribution terms. By participating, you agree to the Code of Conduct.
- Ask usage questions in GitHub Discussions.
- Report reproducible bugs or propose features with the issue templates.
- Find approachable work under
good first issueand maintainer supported work underhelp wanted. - Review the roadmap before proposing a large change.
- Report security vulnerabilities privately through GitHub Security Advisories.
Run the complete local test suite before opening a pull request:
./test.shOn Windows, run ./test.ps1 from PowerShell. GitHub Actions repeats the suite on macOS, Ubuntu, and Windows.
Claudex is available under the MIT License. See NOTICE.md for project independence, trademark, and third party dependency notices.