claudex

KO | EN

gitlite — search

#python #java #php #dotnet #machine-learning #unity #kotlin #tensorflow #latex #csharp #swift #react

★ 16 Open GitHub ↗

Run GPT-5.6 Sol and Codex models inside Claude Code — private, localhost-only, one-command setup for macOS and Linux.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# Claudex

[中文文档](README.zh-CN.md)

### Claude Code's shell. GPT-5.6 Sol's brain. One command.

Run OpenAI Codex subscription models inside Claude Code through a private, localhost-only [CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI) instance—without changing your existing Claude Code or Codex setup.

> “If this gets blocked, I owe you a reset.”
>
> — [Tibo, after sharing the original three-step `claudex` recipe](https://x.com/thsottiaux/status/2076119366647894371)

[![Release](https://img.shields.io/github/v/release/liuzhao1225/claudex)](https://github.com/liuzhao1225/claudex/releases/latest)
[![CI](https://github.com/liuzhao1225/claudex/actions/workflows/ci.yml/badge.svg)](https://github.com/liuzhao1225/claudex/actions/workflows/ci.yml)
![Platform](https://img.shields.io/badge/platform-macOS%20%7C%20Linux-blue)
[![License](https://img.shields.io/badge/license-MIT-green)](https://raw.githubusercontent.com/liuzhao1225/claudex/main/LICENSE)

## Install

```bash
curl -fsSL https://github.com/liuzhao1225/claudex/releases/latest/download/install.sh | bash
```

**Claude Code orchestration · Codex models · localhost-only · reversible install**

> [!CAUTION]
> Claudex is an unofficial community project. Tibo's post is personal commentary—not an OpenAI policy statement, terms exception, endorsement, or account-safety guarantee. Anthropic does not support routing Claude Code to non-Claude models through a gateway. Using this project may put your account at risk; read [Account and policy risk](#account-and-policy-risk) before installing.

### Requirements

- macOS or Linux on arm64 or x86_64
- [Claude Code](https://code.claude.com/docs/en/installation)
- A ChatGPT account with Codex access
- `curl`, `tar`, and either `shasum` or `sha256sum`

The installer downloads a checksum-pinned CLIProxyAPI binary into Claudex's private data directory, creates a localhost-only configuration, opens Codex OAuth, starts the proxy, and verifies that `gpt-5.6-sol` is available. OAuth authorization in the browser still requires your interaction.

Then launch Claude Code with:

```bash
claudex
```

If Claudex saved you setup time, consider [starring the repository](https://github.com/liuzhao1225/claudex).

Claude Code is required. The installer stops without changing anything if it is missing and prints its official installation link. The Codex CLI is optional because CLIProxyAPI performs its own OAuth flow; when it is missing, Claudex prints the [official Codex installation link](https://github.com/openai/codex) and continues.

## What it changes

Claudex's primary installation files are kept under these user-scoped paths:

```text
~/.local/bin/claudex
~/.config/claudex/
~/.local/share/claudex/
~/.local/state/claudex/
```

The corresponding XDG environment variables are respected. The only additional touchpoint is shell configuration: if `~/.local/bin` is not on `PATH`, the installer adds one marked, reversible block to the current zsh or Bash configuration after creating a timestamped backup next to that file.

Claudex does not:

- modify Claude Code or Codex configuration;
- read or copy `~/.codex/auth.json`;
- reuse, overwrite, or stop another CLIProxyAPI installation;
- install a login service, LaunchAgent, or systemd unit;
- expose the proxy outside `127.0.0.1`;
- update itself silently.

## Commands

```text
claudex [Claude Code arguments...]       Start Claude Code through the private proxy
claudex -- [Claude Code arguments...]     Bypass management-command name matching
claudex setup [--model MODEL]             Repair setup, redo OAuth, and verify a model
claudex login [--no-browser]              Redo Codex OAuth
claudex doctor                            Run redacted diagnostics
claudex start|stop|restart|status         Manage the private proxy process
claudex update                            Install the latest checksum-checked Claudex release
claudex rollback                          Restore the previous installed version
claudex uninstall [--keep-auth]           Remove Claudex; optionally preserve OAuth files
claudex version                           Print Claudex and CLIProxyAPI versions
```

The default model is `gpt-5.6-sol`. An explicit Claude Code `--model` argument is preserved and is never duplicated.

At launch, Claudex sets gateway and model variables only for the child `claude` process:

- `ANTHROPIC_BASE_URL`
- `ANTHROPIC_AUTH_TOKEN`
- `ANTHROPIC_MODEL`
- `ANTHROPIC_DEFAULT_OPUS_MODEL`
- `ANTHROPIC_DEFAULT_SONNET_MODEL`
- `ANTHROPIC_DEFAULT_HAIKU_MODEL`
- `CLAUDE_CODE_SUBAGENT_MODEL`

It deliberately does not reproduce the original post's extra behavior and performance overrides: always-on effort, fixed tool concurrency, and disabled Tool Search. Some of those controls are now documented by Anthropic, but they are outside Claudex's minimal, locally tested gateway configuration.

## Security model

- CLIProxyAPI is pinned to a version tested with each Claudex release.
- Every upstream archive is verified against a repository-reviewed SHA-256 lock before extraction.
- The proxy binds only to `127.0.0.1`; its management API and control panel are disabled.
- A random 256-bit local API token is stored in a `0600` file and is never printed by `doctor`.
- Configuration, OAuth, runtime, and state directories are private to the current user.
- Claudex resolves and exactly matches both the saved PID and the private executable path before stopping a process.
- Updates are explicit, staged, checksum-checked, and restore the previous installed version if installation or the post-update health check fails. A proxy that was stopped before the update is stopped again after verification.

The proxy itself still sends prompts and credentials to the selected upstream services. Review [CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI) before trusting it with an account or source code.

## Verified installation

The one-line installer is a convenience bootstrap. For an auditable installation, verify the immutable release and build attestation first:

```bash
version=v0.1.1

gh release download "$version" \
  --repo liuzhao1225/claudex \
  --pattern install.sh \
  --pattern SHA256SUMS

expected=$(awk '$2 == "install.sh" { print $1 }' SHA256SUMS)
if command -v shasum >/dev/null 2>&1; then
  actual=$(shasum -a 256 install.sh | awk '{ print $1 }')
else
  actual=$(sha256sum install.sh | awk '{ print $1 }')
fi
test -n "$expected" && test "$actual" = "$expected"

gh release verify "$version" --repo liuzhao1225/claudex
gh release verify-asset "$version" install.sh --repo liuzhao1225/claudex
gh attestation verify install.sh \
  --repo liuzhao1225/claudex \
  --signer-workflow liuzhao1225/claudex/.github/workflows/release.yml

bash install.sh
```

## Troubleshooting

Run:

```bash
claudex doctor
claudex status
```

Common failures:

- **Port 1455 is occupied:** Codex OAuth needs its callback listener. Stop that listener and rerun `claudex login`.
- **Port 8317 is occupied:** initial setup selects the next free port through 8399. If the persisted port is later taken by another program, rerun `claudex setup`.
- **`gpt-5.6-sol` is absent:** the installer reports the available `gpt-*` models and exits nonzero. Claudex never silently substitutes a model.
- **Headless Linux:** use `claudex setup --no-browser` or `claudex login --no-browser` and follow the URL printed by CLIProxyAPI.

The private proxy log is stored under the Claudex XDG state directory and is rotated at 1 MiB. `doctor` never prints log contents or credentials.

## Account and policy risk

The technique was publicly discussed by Theo and Tibo and implemented by the third-party CLIProxyAPI project. Those posts are not product documentation, a terms exception, an account-safety guarantee, or an official approval of subscription proxying.

- [Theo's original experience report](https://x.com/theo/status/2075776733626892542)
- [Tibo asking for the recipe](https://x.com/thsottiaux/status/2075830097488249060)
- [Theo's short recipe](https://x.com/theo/status/2076114415368482854)
- [Tibo's three-step post](https://x.com/thsottiaux/status/2076119366647894371)
- [CLIProxyAPI Codex OAuth documentation](https://help.router-for.me/configuration/provider/codex)
- [CLIProxyAPI Claude Code documentation](https://help.router-for.me/agent-client/claude-code)

Before using Claudex, review the current provider documents yourself:

- [Anthropic: LLM gateway configuration and unsupported non-Claude routing](https://code.claude.com/docs/en/llm-gateway)
- [Anthropic: connecting Claude Code to a gateway](https://code.claude.com/docs/en/llm-gateway-connect)
- [OpenAI: using Codex with a ChatGPT plan](https://help.openai.com/en/articles/11369540-using-codex-with-your-chatgpt-plan)
- [OpenAI: ChatGPT Pro plan restrictions](https://help.openai.com/en/articles/9793128-about-chatgpt-pro-plans)
- [OpenAI Terms of Use](https://openai.com/policies/terms-of-use/)

Plan-specific guidance differs across Plus, Pro, Business, Enterprise, and other account types. Policies and product behavior can change at any time. You are responsible for deciding whether your use complies with the agreements and plan guidance that apply to your account.

## Development

```bash
shellcheck install.sh bin/claudex scripts/*.sh
shfmt -d -i 2 -ci install.sh bin/claudex scripts/*.sh
bats tests
./scripts/verify-dependency-lock.sh
./scripts/package.sh v0.1.1 dist
```

See [SECURITY.md](SECURITY.md) for vulnerability reporting. Claudex is available under the [MIT License](LICENSE).

## Star History

claudex

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README