Claude Code'x

Claude models inside the official Codex App.

Claude Code'x — or just CCodex — is a compatibility bridge that teaches the Codex desktop and mobile apps to run Claude models.

curl -fsSL https://github.com/gkorepanov/ccodex/releases/latest/download/install.sh | sh

[!NOTE] CCodex is an independent, unofficial, community project. It is not affiliated with, sponsored, or endorsed by OpenAI or Anthropic. Codex, Claude, and related marks belong to their respective owners.

Why

Want Fable and Opus writing your code, but can't stand the Claude Code app? Same. The Codex App is everything it isn't: a genuinely great agentic UI with remote sessions from desktop and mobile that just work, from anywhere. CCodex is the missing bridge.

What you get

• 🤖 Claude models in the official Codex App — claude:* models appear right in the stock model picker, next to gpt-*.
• 📱 Rock-solid remote sessions — drive Claude tasks from the Codex App and the official ChatGPT mobile app over SSH, exactly the way you already use OpenAI models.
• 🔀 Seamless provider switching — jump between OpenAI and Claude mid-project with a compact context handoff, so your chat doesn't start from zero.
• ⚡ Native-feeling Codex features — threads, turns, tools, approvals, /compact, Fork, effort and fast-mode settings all work with Claude models like they were built in.
• 🧩 Claude skills in $ autocomplete — project and user skills appear beside Codex skills and invoke Claude's native slash commands.
• 📊 Status commands — /ccstatus shows provider health and quotas for ❋ Claude and ֎ Codex; /ccstate shows the current task's model, context, traffic, cost, and session stats.
• ✨ Bonus: better thread titles — threads in the Codex App get auto-named in a fun, readable way with an emoji prefix, so you can tell them apart at a glance. Want your own naming style? Drop any custom prompt into ~/.ccodex/config.toml.

Not a hack

CCodex is not a Codex harness bolted onto a reverse-engineered Anthropic subscription. It is the native Claude Code harness (official Claude Agent SDK + Claude Code runtime), surfaced through the excellent Codex App UI. You log in to each provider with its own official CLI, and no Anthropic or OpenAI terms are violated.

100% local, 100% open source

CCodex sends nothing anywhere. There are no CCodex servers, no telemetry, no proxies of ours in the middle — traffic goes over the exact same infrastructure the stock Claude CLI and Codex CLI already use, straight to the providers. Everything else lives on your machine, and the entire codebase is MIT-licensed and open.

Project status

[!WARNING] CCodex is very early and not extensively tested yet. Expect bugs — and please report them.

Install

The one-liner above is all you need. Prefer npm?

npm install -g @gkorepanov/ccodex
ccodex setup

Provider login is optional at install time — add or repair it whenever:

ccodex auth codex
ccodex auth claude
ccodex setup

Keeping it healthy, updated, or removing it:

ccodex doctor            # (or --json)
ccodex update            # npm latest; --check / --channel next / rollback available
ccodex uninstall         # preserves config and state; add --purge --yes to wipe

The release asset also ships a matching uninstall.sh that works even if your shell PATH no longer resolves ccodex.

How it works

CCodex owns the SSH-side codex app-server command and preserves the Codex App's full thread / turn / tool / approval lifecycle, while delegating ordinary Codex CLI commands to your global Codex installation:

• codex app-server, proxy, and daemon ... always run on CCodex's pinned runtime; everything else goes to your external Codex CLI.
• Native gpt-* models remain completely stock; claude:* entries run on Claude Code. Claude effort and fast mode map from Codex reasoning / priority settings.
• Switching providers on the next message creates a compact context handoff behind the scenes; same-provider model changes stay in-place.
• Codex approval modes map cleanly onto Claude permissions: Full Access → bypassPermissions, Ask for approval → default, Approve for me → auto.
• In Claude tasks, /compact <prompt> performs real prompted Claude compaction while projecting the native Codex contextCompaction lifecycle. Stock tasks are untouched.

Setup is deliberately fail-closed and transactional: it validates the platform, exact runtimes, and provider availability before atomically activating a new version. A failed install or update leaves your previous version running. Setup never interrupts an active App session; the new version takes over on the next reconnect.

Local Codex App (same-Mac)

Over SSH the App resolves codex through your PATH, so the shim engages. The local Codex App, however, launches its bundled codex app-server directly and ignores PATH, so ccodex never sees it and no claude:* models appear. On macOS ccodex setup closes that gap without ever touching the signed .app bundle (so Sparkle auto-updates keep working):

• ccodex setup points the App at ccodex automatically via CODEX_CLI_PATH=~/.ccodex/bin/codex — it runs launchctl setenv for the live session, installs a one-shot login LaunchAgent (dev.ccodex.codex-cli-path) so the GUI session re-publishes it on every login/reboot, and exports it in the managed shell blocks for terminal-launched instances. The same managed codex entrypoint is used locally and over SSH. Fully quit the Codex App (Cmd+Q) and relaunch it (or log out and back in) so it picks up the variable.
• A bare app-server launch runs a thin stdio frontend: it forwards the App's newline-delimited JSON to the existing app-server-control socket, lazily starts the gateway when cold, and reconnects after gateway restarts. Provider state and lifecycle remain exclusively inside the existing gateway.
• There is no extra macOS gateway service. The same PID-managed gateway used over SSH starts lazily when the App connects and stops through the existing daemon contract. Setup/update/rollback only switch files and ask you to reconnect; they never restart a live gateway underneath a task.
• ccodex uninstall removes the login hook, restores any previous CODEX_CLI_PATH, strips the managed shell export, and stops only CCodex's own PID-managed gateway. Modified files are preserved. ccodex doctor --deep reports the entrypoint and login hook separately from gateway health.

Technical details

| | | |---|---| | CCodex | 0.4.8 | | Embedded Codex CLI | 0.146.0 (pinned; a newer global Codex never replaces it) | | Claude Agent SDK / Claude Code | 0.3.219 / 2.1.219 | | Runtime | Node.js >=22.13 <27, npm >=10 | | Platforms | macOS 11+ (arm64) · Linux arm64 & x64, glibc ≥2.31 (Ubuntu 22.04+, Debian 11+, Fedora/RHEL equivalents). Alpine/musl not supported | | Shells | Bash, Zsh, Fish | | Relay | Prebuilt per-platform @gkorepanov/ccodex-relay-* optional packages — installs never compile Rust or native addons |

Fresh setup writes the editable title prompt to ~/.ccodex/config.toml:

rename_prompt = """
Create a concise, vivid, memorable title for the task.
Start with exactly one rare, expressive, context-relevant emoji followed by one space.
Avoid generic decorative emoji when a more specific symbol fits.
Keep the complete title, including emoji, within 36 characters.
Return only the title.
"""

[features]
status_command = false # forward /ccstatus and /ccstate to the provider as plain messages
optimistic_side_startup = true # open `/side` immediately while provider context is prepared
claude_skills = true # expose Claude skills in the Codex App `$` autocomplete

Remove or comment out rename_prompt for byte-compatible stock Codex title generation. Setup never restores a prompt removed from an existing config. These settings never disable provider routing, lifecycle/protocol fidelity, permission mapping, or visible errors.

RPC capture is on by default under ~/.ccodex/state (mode 0600, rolls at a combined 1 GiB) and includes prompts/outputs unless you configure otherwise — and it never leaves your disk.

Client quirk worth knowing: the built-in /status differs by client (Mobile consumes provider-labelled quota events; Desktop may render its own OpenAI-account view). /ccstatus is the client-independent source of truth.

Development

npm ci --ignore-scripts
npm run check
npm test
npm run test:contracts
npm run test:public-package

Release workflows build and execute all three native relay packages, publish platform packages before the main package, generate checksums / SBOM / notices, and use npm trusted publishing with provenance.