Codex–Claude Subagent

An MCP plugin for the Codex desktop app and Codex CLI that uses interactive Claude Code sessions as role-controlled subagents for exploration, code review, and implementation.

Sessions remain observable and resumable from Codex. The plugin does not use the Claude API, claude -p, or API-key billing. Claude runs alone by default; its native subagents are available for implementation only when explicitly requested. It uses the Claude Code installation already available on your Mac and does not install Claude Code for you.

Install

You need macOS, Node.js 20 or newer, Python 3, a plugin-enabled Codex desktop app or Codex CLI, Git with access to GitHub, and Claude Code 2.1.322 or newer already signed in with an active claude.ai subscription.

The lifecycle observer uses Claude Code's early-access Mods API. Claude Code updates may require a compatibility update to this plugin. See the compatibility notes and saved-session limits before relying on unattended or long-term resume workflows.

Codex desktop app from a ZIP

The easiest way to install the plugin in the Codex desktop app is:

1. Download the distribution ZIP from the latest GitHub Release

2. Double-click the downloaded release ZIP file to extract it.

3. Open the extracted folder and double-click Install.command to install the plugin.

If macOS blocks the installer the first time, right-click Install.command, choose Open, and confirm.

Internet access is required. The installer uses Codex CLI (from your PATH or the desktop app), checks that the published Git files match this ZIP, then installs or updates the same plugin ID and verifies its installed contents. An outdated or mismatched ZIP is rejected before replacing the plugin; download the latest ZIP instead. Re-running the same verified version does not replace its cache. If an older cache is in use, close the app and running Codex CLI chats and retry. Start a new chat after updating; existing chats are not switched.

If an older ZIP installation reports a marketplace source conflict, close Codex and its CLI chats, run codex plugin marketplace remove codex-claude-subagent, then run Install.command again. Removing the source registration leaves the original extracted folder and plugin cache intact. The installer then registers the official Git source and updates the same plugin ID.

Codex CLI from GitHub

For Codex CLI, add the GitHub marketplace and install the plugin:

codex plugin marketplace add zetsubo-dev/codex-claude-subagent
codex plugin add codex-claude-subagent@codex-claude-subagent

For an existing Git installation, close running Codex sessions before updating:

codex plugin marketplace upgrade codex-claude-subagent
codex plugin add codex-claude-subagent@codex-claude-subagent

These commands update the existing plugin ID, not a second installation. For the verified update and busy-cache checks, use Install.command instead.

Related MCP server: codex-subagent-mcp

Quick start

After installation, start a new Codex conversation. No additional command or special plugin syntax is required. Describe the task in natural language and mention Claude or a named Claude model such as Fable or Opus when you want Codex to delegate it to Claude Code. A plain request such as "review this" stays with Codex and does not request a Claude session.

Examples:

• Ask Claude to review this change.

• Have Claude investigate the cause of this test failure.

• Ask Claude to implement this fix.

• FableとOpusでレビューして — request separate reviews from both models.

A review request returns findings; it does not automatically authorize fixes or repeated fix/re-review cycles. Ask for those explicitly when wanted.

Choose the Claude model and effort

Specify the model and reasoning effort in the same request when needed:

• Ask Claude Sonnet to review this change with medium effort.

• Investigate this issue with Claude Opus using high effort.

Requested model and effort values are passed through to Claude Code. New reviews default to Opus when no model is named. Other roles use Claude Code's model default, and unspecified effort always uses Claude Code's default.

If this plugin is useful to you, please consider giving the repository a star. It helps others discover the project and supports further development.

License

This project is released under the MIT License.