claude-plugin-codex

Consult Claude Code from inside Codex.

English | 한국어 | 日本語 | 简体中文 | 繁體中文

This plugin is for Codex users who want an easy way to consult Claude Code from the workflow they already have. Describe a task in plain language and Claude runs in the same repository — with the Claude login you already have — and reports back with a careful second pass.

It is a companion to openai/codex-plugin-cc, which connects the same two tools in the other direction. If you work with both agents, the two plugins complete the circle.

you   ▸ have claude redesign the landing page and make sure it still builds

codex ▸ claude-code.consult(prompt=…, edit=true, background=true, verify="auto")
        Started background consult job job-a1b2c3.

codex ▸ 🤝 Claude Code made changes in ~/projects/site.
        Redesigned src/app/page.tsx with a bolder hero and …
        Files Claude touched:
        - src/app/page.tsx
        🔍 Verification: `node --check 'src/app/page.tsx'` → ✅ exit 0
        ( 14 turns · 3m41s · ≈$0.42 of plan usage )

What You Get

A claude-code MCP server (Node, zero dependencies) with six tools:

• consult — hand a task to Claude Code, advisory by default
• review — a careful, read-only review of your uncommitted changes or branch
• consult_status / consult_result / consult_cancel — manage background jobs
• setup — check that Claude Code is installed and signed in

You don't call these directly. The bundled skill teaches Codex to pick the right tool and options (edit, background, verify, resume) from what you say.

Requirements

• Claude Code, installed and signed in:

  curl -fsSL https://claude.ai/install.sh | bash
  claude   # run once to sign in
  

  Consults run through your existing Claude login, so usage draws on your Claude plan — there is no separate bill. Results include an estimate such as ≈$0.42 of plan usage for transparency. (Only if you set ANTHROPIC_API_KEY are calls API-billed, and labeled accordingly.)

• Node.js 20+

• Codex with plugin support, on Linux or macOS.

Install

codex plugin marketplace add xavierchoi/claude-plugin-codex
codex plugin add claude-code@claude-plugin-codex

Then ask Codex: “Is Claude ready?” — it runs the setup tool and reports anything that needs fixing, with the exact commands to fix it.

Usage

Ask for a second opinion

Get a second opinion from Claude on this change.
Ask Claude why this query is slow.

By default Claude runs in plan mode: it investigates and advises without touching files.

Ask for a review

Have Claude review my changes.
Have Claude review this branch against main — focus on the retry logic.

The server collects the git diff itself — your uncommitted changes, or everything since a base branch — and Claude reviews it read-only: a short summary, what works well, findings by severity with file:line references, and an honest verdict.

Let Claude make changes

Have Claude clean up the data layer and check it still compiles.

When you ask for changes, Codex sets edit: true and, for code edits, verify: "auto" — after Claude finishes, the server runs a quick syntax check on the touched files and appends the outcome to the result.

Longer tasks

Have Claude redesign the dashboard — take its time.

Work beyond a quick pass runs as a background job. Codex reports the job id, waits efficiently (consult_status supports long-polling), and presents the result when it's done. You can ask for the status or cancel at any time, and every run writes a live log you can follow:

tail -f ~/.cache/cc-plugin-codex/logs/latest.log

[!NOTE] Foreground consults show no progress in the UI and are capped at 28 minutes. For anything substantial, background is the comfortable path — the skill steers Codex there on its own.

Continue where Claude left off

Have Claude refine that, and also fix the tests.

Session ids are remembered per directory, so follow-ups continue the same Claude conversation.

Use your Claude Code skills

Claude runs with the skills you have installed in Claude Code:

Have Claude use the frontend-design skill to redesign this page.

Choose model and effort

Have Claude take a quick, cheap look at this.        → effort: low
Ask Claude to think hard about this race condition.  → effort: high
Have opus review this design.                        → model: opus

Mention it and Codex passes it through (--model accepts aliases like sonnet/opus/fable or full names; --effort is low…max). When you don't, the default model is fable — the newest Claude — falling back automatically to opus, then sonnet, when a plan can't serve it. The result's meta line shows which model actually answered. To change the default, add to ~/.config/cc-plugin-codex/settings.json:

{ "model": "opus", "effort": "medium" }

Set "model": "inherit" to defer to your own Claude configuration instead.

Verification policy

The verify command runs from the MCP server without an approval gate, so it is policy-gated for safety. The default policy safe allows "auto" and plain invocations of well-known build/test tools (npm, pytest, cargo, go, make, …) with no shell operators. Configure in ~/.config/cc-plugin-codex/settings.json:

{ "verify": "safe" }

• "auto-only" — only verify: "auto" may run
• "safe" — the default, described above
• "all" — any command; use only if you trust everything that can reach the tool

Updating

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

Then start a fresh Codex session: sessions that were already open keep the old server process, and upgrading underneath them can close their bridge (tool calls would fail with "Transport closed").

How It Works

Codex ──(MCP: consult)──▶ claude-code MCP server (Node, zero deps)
                               │
                               ├─▶ claude -p  (headless, in your repo,
                               │              your login, plan mode unless edit)
                               ├─▶ optional verify command after the edits
                               └─▶ parsed result ──▶ back to Codex

Background jobs are detached workers with file-backed state: a 45-minute watchdog, a concurrency cap, stale-job reconciliation, and process-group cancellation — a cancelled or abandoned consult never leaves a Claude process running.

Development

npm test        # full suite against a fake claude binary — fast, no usage
npm run test:live   # opt-in smoke tests against the real claude

License

MIT