Claude Codex Adapter

🔌

Native protocol, no fork

Codex App runs its usual SSH probe, bootstrap, and app-server proxy. A codex shim earlier in PATH routes only app-server calls into the adapter.

🧠

Claude Code turns

Agent text and reasoning stream into the conversation; Bash becomes command approvals; Edit/Write/MultiEdit become file-change approvals with live diffs.

🔁

Explicit existing backends

Provider and loop selection is sanitized metadata that maps known descriptors to existing runtime paths: Agent SDK, agent-http, agentapi, claude-p, codex-proxy, and mock.

📦

Zero-toolchain deploy

Ships compiled ESM .mjs, so a remote host needs only Node 24. Dev runs straight from TypeScript with tsx.

What it does

The adapter implements the Codex app-server v2 protocol (stdio, WebSocket, Unix-socket daemon, and app-server proxy) and bridges each Codex request to a Claude Code runtime. Thread lifecycle, streaming, approvals, MCP, and remote filesystem/command utilities are all backed by real runtime behavior.

The current release path is intentionally narrow. TypeScript remains the production runtime. Rust-first work is present as RFCs, an experimental protocol crate, fixtures, parse/reserialize tests, and a pinned fixture drift gate, but it does not replace the runtime, transport, store, or launcher. Provider and agent-loop work exposes descriptors, sanitized config projection, and explicit selection for known descriptors only; it does not add a new provider runtime, auth system, gateway, subscription model, or multi-agent orchestrator.

Credentials should be supplied by the local user or organization through API keys, official cloud-provider credential chains, same-host local CLI auth, or an approved organization gateway. The project does not support personal subscription pooling, browser cookie/session-token reuse, credential sharing, private endpoints, provider bypasses, or claims of unavailable entitlements. Release checks include CI check, cargo-test, TypeScript tests, the pinned Rust fixture drift gate, docs build for docs changes, and opt-in credentialed smoke or acceptance checks.

bash

npm install
npm run build        # tsc -> dist/ (production artifact)
npm run dev          # tsx src/adapter.mts — run sources directly
npm run doctor       # environment self-check

Then install the codex shim on the remote host and add a Remote connection in the Codex App. See Getting started.

For release gates and reviewer expectations, see Release readiness.

Requires Node.js 24+

The thread store uses node:sqlite, which is only stable (unflagged) on Node 24.