umum-ai/claude-codex-bridge

Run OpenAI Codex agents from Claude Code. Ask Claude to delegate a task to
Codex, follow its progress, send another instruction while it works, stop it,
or continue a saved session.
The plugin connects Claude's MCP tools and Channels to codex app-server.
Codex tasks run asynchronously; starting a task returns its session ID without
waiting for the task to finish.
Requirements
- **Claude Code 2.1.261**, installed and signed in.
- **Codex CLI 0.153.4**, installed and signed in with access to the model you
want to use.
- **Node.js 24.20.0 or newer**, including npm and npx.
These are the tested versions. Older versions are unsupported; compatibility
with newer versions must be verified. The plugin uses the experimental Codex
app-server protocol and Claude Code Channels research preview.
node, npx, and codex must be on the PATH inherited by Claude Code. The npm
package includes the bridge's JavaScript dependencies. The plugin
uses npx to fetch its exact package version on first startup; subsequent
starts use npm's cache. No source build or protocol generation is required.
Install
1. Check the required tools
Install Claude Code,
Codex CLI, and
Node.js, then check:
If Codex is not signed in, run codex login. Claude and Codex use their own
accounts and model access. The plugin does not provide a subscription or API
credits.
2. Add the marketplace and install the plugin
Claude installs the plugin from this repository's marketplace. The plugin
starts the pinned version of
@kvokka/claude-codex-bridge
with npx --yes. The first startup needs access to the npm registry.
3. Enable the plugin and Channels
Merge this into ~/.claude/settings.json, keeping your other settings:
The installation commands already register the marketplace and enable the
plugin. The complete fragment above also shows how to reproduce the settings.
4. Start Claude in your project
The maintainer reports that channelsEnabled: true enables this ordinary
startup on Claude Code 2.1.261 without a shell alias or wrapper. Channel
activation can also depend on your account and organization policy. Verify
incoming progress with the example below before relying on it.
Anthropic's Channels documentation
currently describes channelsEnabled as a managed setting and requires
per-session opt-in. If tools load but incoming progress does not arrive, see
Channels troubleshooting.
Use it
Talk to Claude normally. Give Codex a concrete task, the project directory, and
an explicit model when you want one:
> Use the bridge to start Codex with model gpt-5.6-luna in
> /absolute/path/to/my-project. Review the authentication code and suggest a
> fix for the failing login test. Report its progress as channel events arrive.
To check that notifications work, use a task with a short delay:
> Start Codex in this project. Ask it to announce that it started, run a command
> that waits 15 seconds, and then reply BRIDGE_DONE. Wait for channel events;
> do not poll codex_status or codex_events.
While Codex is working:
> Tell that Codex session to focus on the token refresh path.
To interrupt it:
> Ask that Codex session to stop.
After a task completes:
> Continue that Codex session: implement the proposed fix and run the relevant
> tests.
Keep the threadId if you want to continue after restarting Claude:
> Resume Codex thread THREAD_ID in /absolute/path/to/my-project, then ask it to
> continue the investigation.
Claude can list available models with codex_models. An explicitly selected
model is requested without provider fallback. Ask for a service tier such as
fast to override the service_tier in your Codex config for that thread.
Available tools
| Tool | What you can ask Claude to do |
| --- | --- |
| codex_models | List the models available to Codex. |