claudex — Claude Code proxy for ChatGPT/Codex

Use your ChatGPT Plus/Pro or Codex subscription in Claude Code via OAuth, with no OpenAI API key.

Claudex is a high-fidelity Claude Code -> OpenAI Responses proxy for ChatGPT/Codex users. It preserves Claude Code workflows across images, files, tool results, /compact, context-limit recovery, prompt-cache usage mapping, and hardened streaming errors.

curl -fL --progress-bar https://raw.githubusercontent.com/pilc80/claudex/main/install.sh | bash
# When prompted, choose ChatGPT/Codex OAuth setup.
claudex

Key features

• 🏆 ChatGPT/Codex subscriptions — use Claude Code through ChatGPT/Codex OAuth with no OpenAI API key.
• 🏆 Claude Code workflows — keep tools, agents, long sessions, and parallel work across supported backends.
• 🏆 Text, image, and file support — translate conversations, vision inputs, file/document blocks, tool calls, and streaming responses.
• 🏆 1M context support — make /context aware of verified 1M GPT context windows such as gpt-5.5-pro and newer GPT models.
• 🏆 Compaction support — preserve /compact, auto-compaction, and context-limit recovery behavior.
• 🏆 Correct error translation — surface OpenAI/Codex failures as actionable Claude Code errors.
• 🏆 Setup health checks — use claudex-config config doctor to check config, auth, proxy state, setup, and reauthentication.
• 🏆 Local-first privacy — run locally with explicit routing; OAuth tokens are read from provider-specific local files or environment variables.
• 🏆 WebFetch guardrails — WebSearch is disabled for Claude launches because it is not supported through the proxy; known URLs should use WebFetch.

Why this fork?

Most Claude Code -> Codex proxies are fine for text-only request routing. This fork focuses on preserving full Claude Code workflows when OpenAI Responses/Codex behaves differently from Anthropic Messages:

• /compact works with streamed and non-streamed Responses shapes.
• Claude launches include --disallowedTools WebSearch, --allowedTools WebFetch, and a short web-research system prompt because WebSearch is not supported through the proxy. Search should use GitHub/gh, MCP search, or Bash/curl to a local search provider; known URLs should use WebFetch.
• claudex intentionally does not invent cross-protocol auto-compaction. When Codex says the context window is full, claudex returns Claude Code's normal context-limit prompt so users can run /compact or /clear.
• Current-turn images and current tool-result images are preserved.
• Old base64 image history is pruned before oversized requests; upstream v0.2.4 resends historical images and can hit the 32 MB request body limit.
• Document/file blocks are mapped where Responses can represent them.
• Prompt cache keys and cached-token usage are mapped back to Claude Code.
• Native Claude Code error semantics: unlike lightweight proxies that often collapse provider failures into generic 502s, claudex maps upstream failures to the closest Anthropic error type so Claude Code can compact, back off, or surface auth/config failures the same way it would against Anthropic. Deterministic request/account errors are returned directly; only retryable provider-health failures feed failover and circuit breakers.
• Error-only proxy dumps help diagnose upstream OpenAI and Claude-visible errors.

Fork and upstream scope

This repository is a fork of StringKe/claudex, based on upstream v0.2.4.

Use the upstream README and docs for the general Claudex feature set, CLI, provider list, smart routing, config discovery, and non-Codex providers:

• Upstream README: https://github.com/StringKe/claudex
• Upstream docs: https://stringke.github.io/claudex/

This README documents the fork-specific Codex/OpenAI Responses work and local setup details. The OpenAI Responses / ChatGPT/Codex path is the main validation target; non-Responses providers stay close to upstream Claudex behavior.

Goal

Make OpenAI/ChatGPT/Codex models run from Claude Code with high practical fidelity: preserve Claude workflows, translate the Anthropic Messages protocol accurately, and work around Responses/Codex endpoint limits where possible.

The main target path is:

Claude Code
  -> Anthropic Messages API shape
  -> claudex OpenAIResponses adapter
  -> ChatGPT/Codex Responses endpoint

Feature Status

✅ Ready for everyday Claude Code use

• ✅ ChatGPT/Codex OAuth profiles
• ✅ Text conversations, tool use, and streaming tool calls
• ✅ Image inputs and file/document inputs supported by Claude Code
• ✅ Agentic and parallel Claude Code workflows
• ✅ 1M /context support for large GPT models
• ✅ /compact, auto-compaction, and context-limit recovery
• ✅ OpenAI/Codex error translation
• ✅ Prompt-cache and cached-token usage mapping
• ✅ OAuth expiry checks and reauth prompts
• ✅ Local installer and config doctor readiness checks
• ✅ Safe staged installer updates

⚠️ Depends on provider/account support

• ⚠️ Web search/tool behavior
• ⚠️ Non-Codex OpenAI-compatible providers
• ⚠️ Model slot mapping (haiku, sonnet, opus)
• ⚠️ Provider-specific request parameter stripping
• ⚠️ Provider-specific model availability, e.g. mini/pro variants

ℹ️ Out of proxy scope by design

• ℹ️ Server-side Anthropic-hosted tools are intentionally out of scope. Claudex keeps Claude Code's local tool path instead.
• ℹ️ Codex hidden reasoning is not exposed as Claude Code thinking blocks. Claudex preserves visible outputs and usage accounting without leaking hidden reasoning text.

When to choose this fork

Choose this fork if you want Claude Code to use a ChatGPT Plus/Pro or Codex subscription through OAuth and you care about full Claude Code workflow fidelity, not just text-only request routing:

• /compact and context-limit recovery.
• Current-turn images, current tool-result images, and historical image pruning to avoid repeatedly resending base64 images until the request exceeds 32 MB.
• Document/file block mapping.
• Prompt-cache usage mapping.
• Hardened OpenAI Responses streaming, rate-limit, and failure events.
• Actionable error classification: deterministic request/account errors stay visible instead of poisoning circuit breakers, while retryable provider-health failures still back off and fail over.
• Release installer checksums, latest-version validation, and stale-proxy restart guidance.

Use upstream Claudex if you primarily need a broad multi-provider manager and are not relying on image-heavy Codex workflows. Use simpler proxies for text-only request routing. Use this fork for full Claude Code workflow fidelity on ChatGPT/Codex: images, tool-result images, files, /compact, context-limit recovery, prompt-cache usage, model-slot mapping, and hardened Responses streams.

Install

Release installer:

# macOS / Linux
curl -fL --progress-bar https://raw.githubusercontent.com/pilc80/claudex/main/install.sh | bash

# Windows PowerShell
irm https://raw.githubusercontent.com/pilc80/claudex/main/install.ps1 | iex

The installer downloads the latest release assets from pilc80/claudex, verifies SHA256 checksums from the release manifest or .sha256 files, installs both claudex and claudex-config, checks that the latest version is the one found in PATH, and can optionally set up a ChatGPT/Codex OAuth profile. On Windows, the installer uses stable claudex.exe and claudex-config.exe shims with versioned real binaries under versions/; the first migration refuses to replace a legacy running .exe and asks you to close all Claudex sessions. If a running proxy still uses the old binary, the installer can stop it or prints the exact restart commands.

If no matching release asset exists for your platform, the installer can fall back to cargo install unless source fallback is disabled.

Safer Windows flow:

irm https://raw.githubusercontent.com/pilc80/claudex/main/install.ps1 -OutFile install.ps1
notepad .\install.ps1
powershell -ExecutionPolicy Bypass -File .\install.ps1

Useful installer options:

# macOS / Linux
sh install.sh --dry-run
sh install.sh --yes --no-setup
sh install.sh --profile codex-sub
sh install.sh --install-dir "$HOME/.local/bin"
sh install.sh --no-source-fallback

# Windows PowerShell
.\install.ps1 -DryRun
.\install.ps1 -Yes -NoSetup
.\install.ps1 -Profile codex-sub
.\install.ps1 -InstallDir "$HOME\.local\bin"
.\install.ps1 -NoSourceFallback

Source install:

cargo install --git https://github.com/pilc80/claudex --force

For a private SSH checkout:

cargo install --git ssh://git@github.com/pilc80/claudex.git

For local development:

git clone git@github.com:pilc80/claudex.git
cd claudex
cargo build --release
ln -sfn "$PWD/target/release/claudex" "$HOME/.local/bin/claudex"
ln -sfn "$PWD/target/release/claudex-config" "$HOME/.local/bin/claudex-config"

Make sure $HOME/.local/bin is in PATH.

Command Split

This fork intentionally separates the Claude-compatible launcher from setup:

claudex
  Claude-compatible launcher. It forwards user arguments to Claude Code while
  adding Claudex guardrails for unsupported proxy features.
  After a `codex-sub` profile exists, plain `claudex` uses it by default.

claudex-config
  Claudex setup and management: auth, proxy, config/profile, sets,
  and the inherited `run <profile>` command family.

This keeps claudex close to claude at the launcher layer: flags such as claudex --resume <session-id> are forwarded to Claude Code instead of being claimed by the management CLI. Claudex still adds WebSearch guardrails because Claude Code WebSearch is not supported through the proxy: it detects supported Claude Code flags, disables WebSearch, allows WebFetch, and appends a short web-research policy prompt when those flags are available. Management stays in claudex-config; obsolete side commands such as the old dashboard, self-update command, and fake proxy start --daemon path are intentionally not part of the fork CLI. The previous Claudex management behavior remains available through claudex-config, including profiles, proxy control, OAuth, configuration sets, and claudex-config run <profile>.

On interactive startup, Claudex checks GitHub releases at most once every three hours before starting Claude. If a newer release is available, it can print the platform-specific installer command; if the check fails or times out, startup continues.

Normal launch options come from environment variables:

claudex --resume <session-id>
CLAUDEX_MODEL=gpt-5.5 claudex
CLAUDEX_HYPERLINKS=on claudex
CLAUDEX_PROFILE=other-profile claudex

CLAUDEX_PROFILE defaults to codex-sub when that profile exists, otherwise to the first enabled profile. CLAUDEX_CONFIG can point at a custom config file.

ChatGPT/Codex OAuth Setup

The installer can offer this setup interactively. To run it manually:

claudex-config auth login chatgpt --profile codex-sub
claudex

Headless device-code login:

claudex-config auth login chatgpt --profile codex-sub --force --headless

Manual profile shape:

[[profiles]]
name = "codex-sub"
provider_type = "OpenAIResponses"
base_url = "https://chatgpt.com/backend-api/codex"
default_model = "gpt-5.5"
auth_type = "oauth"
oauth_provider = "openai"
enabled = true

# Optional: route only current-turn image requests to another accepted model.
# Keep unset unless your account accepts that model.
# image_model = "gpt-5.5"

[profiles.models]
haiku = "gpt-5.5"
sonnet = "gpt-5.5"
opus = "gpt-5.5"

Keep haiku = "gpt-5.5" for ChatGPT/Codex unless you have tested that your account accepts another model. This is intentional: Claude Code may ask for a haiku slot, but the Codex backend can still reject gpt-5.5-mini for ChatGPT subscription accounts with 400 model is not supported. If Claude Code selects a haiku/sonnet/opus slot, claudex sends the mapped model from [profiles.models]. Keep those aliases on models your account can use.

For verified large-context GPT models, claudex makes Claude Code aware of the real 1M window by presenting gpt-5.5-pro and newer GPT models to Claude Code with a [1m] suffix, then strips that suffix before forwarding requests to Codex/OpenAI. Plain gpt-5.5 and older GPT models default to the smaller 272k auto-compact window because the runtime can still reject prompts around that size despite some docs listing a 1M context window.

Deploying A Local Build

Build and point the local command at the exact release binary:

cargo build --release
ln -sfn "$PWD/target/release/claudex" "$HOME/.local/bin/claudex"
ln -sfn "$PWD/target/release/claudex-config" "$HOME/.local/bin/claudex-config"

Verify:

which claudex
readlink "$HOME/.local/bin/claudex"
readlink "$HOME/.local/bin/claudex-config"
claudex-config --version
shasum -a 256 target/release/claudex target/release/claudex-config

Restart the proxy after deploying a new binary:

claudex-config proxy stop
claudex

Changing the symlink does not update already-running processes. If an old proxy is alive, claudex may reuse it instead of starting the new binary.

macOS Local Signing

Local macOS rebuilds produce a new binary identity. If claudex reads OAuth credentials from Keychain, macOS may ask for Keychain access again after each unsigned rebuild. For local development, create one persistent self-signed code signing certificate named pilc80 local signing, then sign every local build with that identity.

Create the local certificate in Keychain Access:

1. Open Keychain Access.
2. Choose Certificate Assistant -> Create a Certificate.
3. Name: pilc80 local signing.
4. Certificate Type: Code Signing.
5. Check "Let me override defaults" and create it in the login keychain.
6. Set the certificate trust to "Always Trust" if macOS asks.

Sign a local build:

cargo build --release
codesign --force --sign "pilc80 local signing" target/release/claudex
codesign --force --sign "pilc80 local signing" target/release/claudex-config
codesign --verify target/release/claudex target/release/claudex-config

The Unix installer also supports signing installed macOS release binaries:

CLAUDEX_CODESIGN_IDENTITY="pilc80 local signing" sh install.sh --yes

This is for local Keychain trust only. Public release artifacts still require an Apple Developer ID certificate and notarization if distributed as trusted macOS software.

Release Integrity

Each release should publish:

claudex-<version>-<target>.tar.gz
claudex-<version>-<target>.tar.gz.sha256
claudex-<version>-x86_64-pc-windows-msvc.zip
claudex-<version>-x86_64-pc-windows-msvc.zip.sha256
claudex-release-manifest.json

Archives contain both claudex and claudex-config.

The release workflow also emits GitHub artifact attestations for release archives and the manifest. Use GitHub CLI attestation verification for provenance checks when needed.

Tests

Before publishing or deploying changes, run:

cargo test
cargo clippy --all-targets -- -D warnings
cargo build --release

Upstream Compatibility

This fork tries to keep non-OpenAIResponses behavior scoped and compatible with upstream Claudex. DirectAnthropic and OpenAICompatible providers should keep using the upstream paths unless a change is explicitly guarded for Responses.

License

This fork keeps the upstream MIT License and copyright notice. See LICENSE.