claude-plugin-codex

Install

Add the public marketplace:

codex plugin marketplace add yanchuk/claude-plugin-codex

Then open Codex's plugin directory, find Claude Plugin Codex, and install
Claude.

Start a new Codex thread and verify the install:

$claude setup

If Codex was already running, start a new thread or restart Codex before using
$claude.

What It Is

If you already use Codex and Claude Code, this plugin brings Claude Code into
your Codex workflow. Codex stays in charge of the thread. Claude Code gives a
second pass through the local claude CLI.

Use it for four things:

• a normal read-only Claude review
• a more skeptical adversarial review
• a quick second opinion while Codex keeps working
• a rescue pass when a Codex thread stalls or needs another agent

This is the inverse of
openai/codex-plugin-cc. That
plugin pulls Codex into Claude Code. This one pulls local Claude Code into
Codex.

Status

Alpha. The Codex marketplace flow has been verified with Codex CLI 0.130.0.
The stable command form is $claude. If your Codex UI exposes the skill as
/claude, you can use that as an alias.

Core Commands

• $claude setup checks whether Claude Code is installed, authenticated, and
  supports the needed CLI features.
• $claude review runs a structured read-only review of local git state.
• $claude adversarial-review asks Claude to challenge a plan or diff.
• $claude advise asks Claude for a quick second opinion.
• $claude do gives Claude a prepared coding, exploration, verifier, scout, or
  synthesis task.
• $claude rescue hands Claude a debugging or implementation task. It is
  read-only unless you pass --write.
• $claude monitor polls a background Claude job and reports whether Claude is
  active, stale, or finished.
• $claude status, $claude result, and $claude cancel manage Claude jobs.

Longer jobs can run in the background:

$claude advise --background should this VAD tuning loop collect N=5 now?
$claude do --background --model sonnet map the auth module and return file:line citations
$claude rescue --background investigate the flaky integration test
$claude monitor <job-id>
$claude result <job-id>

Slash-style aliases are best-effort. Codex plugin manifests do not yet expose a
documented custom slash-command API, so $claude is the portable form. If your
Codex build passes slash-style text to skills, these forms map to the same
commands:

/claude setup
/claude:advise should this plan use a background worker?
/claude:do --background --model sonnet map the auth module
/claude:rescue --background investigate the flaky integration test
/claude:review --base main
/claude:adversarial-review challenge the state management assumptions

When To Use It

A good default pattern is simple:

• Run $claude review for a normal second pass.
• Run $claude adversarial-review when the change is high stakes.
• Run $claude advise --background when you want another model to check a
  plan, tradeoff, or evidence bundle.
• Run $claude do --background when the user wants Claude to perform a
  specific prepared task.
• Run $claude rescue --background when Codex stalls or you want Claude to
  take a deeper pass.

Adversarial review is especially useful for migrations, auth changes, infra
scripts, refactors, and work where the danger is hidden assumptions rather than
syntax errors.

Requirements

• Codex with plugin marketplace support.
• Claude Code installed and authenticated on the same machine.
• Node.js 18.18 or newer.

Local Development

From a local checkout:

codex plugin marketplace add ./

After installation, new Codex sessions should load the skill as
claude-code-advisor:claude. Codex writes an enabled plugin entry similar to:

[plugins."claude-code-advisor@claude-plugin-codex"]
enabled = true

Usage

Use $claude in a Codex thread:

$claude setup
$claude advise --background should this plan use a background worker?
$claude do --background --model sonnet map this package and cite file:line call sites
$claude do --background --model opus debug this cross-module failure with a prepared task
$claude rescue --background investigate the flaky integration test
$claude monitor <job-id>
$claude rescue --write fix the failing test with the smallest safe patch
$claude review --base main
$claude adversarial-review challenge the state management assumptions
$claude status
$claude result <job-id>
$claude cancel <job-id>

If your Codex build shows /claude in the slash menu, it is an alias for the
same skill.

Monitoring

Use background mode when Claude may need more than one short answer:

$claude rescue --background investigate the flaky integration test
$claude monitor <job-id>

MCP is off by default. If the workspace has a .mcp.json, the companion
refuses background mode because Claude Code can still open an interactive MCP
permission picker before returning an answer. Use foreground mode, or pass
--allow-mcp only after the user explicitly asks Claude to use MCP.

The monitor checks Claude every 30 seconds by default. It keeps raw logs in
JSON output, but the human view shows the useful signal: whether Claude is
active, the last meaningful line, how long output has been stale, and what to
do next.

status and monitor save the latest useful Claude output, so result can
recover it later even if you cancel the job or Claude's live log socket is gone.

Foreground advise and rescue calls have a two-minute timeout. If one times
out, the companion records the timed-out attempt and starts one background job
for the same prompt. Use --background up front for real advisor work; use
--no-background-fallback only when you want a timeout to fail fast.

Safety

Review and adversarial review are read-only. advise and rescue are also
read-only unless you pass --write. Write-capable Claude work is recorded as a
separate job type.

$claude do --model sonnet is for prepared junior-agent work. Before using it,
Codex should apply tasks-for-sonnet and turn the request into a bounded task:
role, absolute paths, word cap, What Must Be True, Known Constraints, Mechanical
Verification, and Stop Conditions. Use it for scouts, mappers, verifiers,
single-concern reviewers, synthesis, or fully specified scaffolding. Do not use
Sonnet for broad application code that needs judgment.

$claude do --model opus is the backup for complex Claude tasks: ambiguous
debugging, broad refactors, architecture changes, auth, money, migrations, PII,
provider reliability, AI runtime paths, or work that needs the same level of
judgment you would reserve for GPT-5.5. Still prepare a specific task with
paths, constraints, allowed write scope, verification, and stop conditions.

Managed Claude jobs ignore inherited MCP server config by default. This keeps
advisor and rescue runs from blocking on an interactive "enable MCP servers?"
prompt inside Codex.

The companion enforces this with strict non-interactive flags:

--mcp-config '{"mcpServers":{}}' --strict-mcp-config --no-chrome

Background mode has an extra guard: if the current workspace contains
.mcp.json, background launch is blocked unless you pass --allow-mcp.
Do that only after the user explicitly asks Claude to use MCP.

The plugin does not force Sonnet for advisor, review, adversarial-review, or
rescue work. It lets Claude Code use your configured default model unless you
explicitly pass another model. It uses xhigh effort by default for Claude
advisor work. Sonnet belongs in junior-agent delegation workflows, not in the
default advisor path.

The companion runtime tracks jobs by workspace and Codex thread ID when Codex
provides one. If it cannot safely infer a thread, it requires an explicit job
ID before resuming work.

Claude Code must already be installed and authenticated on the host:

claude auth login

Privacy

This plugin does not run a hosted service. It runs the local Claude Code CLI on
your machine. Your local Claude Code installation and Anthropic account handle
prompts, file context, and command output sent to Claude Code.

The plugin stores job metadata and results under your local Codex home directory
so $claude status, $claude result, and $claude cancel can work across
turns. It does not intentionally collect analytics, phone home, or send data to
the repository owner.

Terms

This project is provided under the MIT License. You are responsible for how you
use Codex, Claude Code, and any data you send through those tools.

How It Works

The claude skill routes each request to:

node "<plugin root>/scripts/claude-companion.mjs" <subcommand> <args>

The companion owns:

• command parsing
• Claude CLI invocation
• capability detection
• job state
• foreground and background lifecycle
• review JSON validation
• safety boundaries for read-only versus write-capable work

Development

npm test
npm run validate

Optional smoke test against the installed Claude CLI:

npm run test:smoke
CLAUDE_PLUGIN_CODEX_RUN_BG_SMOKE=1 npm run test:smoke

Optional end-to-end smoke test against an installed Codex plugin:

npm run test:e2e:codex

This requires codex plugin marketplace add ./, Claude installed from
Codex's plugin directory, and a logged-in Claude Code CLI. It starts a fresh
codex exec session and verifies that $claude advise --model sonnet routes
through the installed skill. Sonnet is used only for this small routing test.

Current Limits

• The plugin depends on the installed Claude Code CLI contract. Run
  $claude setup after upgrading Claude Code.
• Background mode is optional. If the companion cannot verify claude --bg,
  claude agents, claude logs, claude attach, and claude stop, it
  degrades to foreground-only behavior.
• Background mode refuses workspaces with .mcp.json unless --allow-mcp is
  explicit. This avoids Claude Code's interactive MCP picker inside Codex.
• $claude monitor checks a background job every 30 seconds by default. It
  reads claude logs and claude agents, filters routine terminal noise, and
  marks repeated output as stale after two minutes.
• Structured review depends on Claude returning valid JSON inside the
  --output-format json result envelope. The companion validates and retries
  once before failing.

Troubleshooting

If Codex shows Unable to load skill contents after an update, restart Codex
or start a new thread. Codex may still point at an older cached skill path after
a plugin version bump. If the error remains, remove and reinstall the
claude-plugin-codex marketplace.

License

MIT.