Claudex

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.

Quick start

Install Claudex, then complete the official Codex browser sign in when prompted.

One command source installer

macOS, Linux, or WSL:

curl -fsSL --proto '=https' --tlsv1.2 https://claudex.work/install.sh | bash

Windows PowerShell:

irm https://claudex.work/install.ps1 | iex

These 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.

Package managers

brew install BeamoINT/tap/claudex       # macOS or Linux

Windows users can also install from the BeamoINT Scoop bucket:

scoop bucket add beamoint https://github.com/BeamoINT/scoop-bucket
scoop install beamoint/claudex

Then 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.

macOS, Linux, or WSL

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
claudex

The 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.

Windows

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"
claudex

The 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.

What Claudex adds

• 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 /skill execution
  and Codex style $skill references 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.

Common commands

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.

Supported platforms

"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.

Documentation

Project policies and history are in CONTRIBUTING.md, GOVERNANCE.md, MAINTAINERS.md, SECURITY.md, SUPPORT.md, and CHANGELOG.md.

How it works

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.

Contributing

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 issue and maintainer supported work under help 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.sh

On Windows, run ./test.ps1 from PowerShell. GitHub Actions repeats the suite on macOS, Ubuntu, and Windows.

License

Claudex is available under the MIT License. See NOTICE.md for project independence, trademark, and third party dependency notices.