claude-consult-mcp

Let OpenAI Codex (CLI and desktop app) consult your local Claude Code while it analyzes problems: co-analysis, adversarial second opinions, and read-only file review — over the Model Context Protocol.

Claude is advisory only by design: it reads files and researches the web, but it can never modify anything. Implementation always stays with Codex.

Codex CLI / Desktop app  (shared ~/.codex/config.toml)
   |  spawns: cmd /c npx -y claude-consult-mcp   (Windows)
   |          npx -y claude-consult-mcp          (macOS / Linux)
   v
MCP stdio server (this package)
   |  9 tools by default; 10 with the opt-in consultation journal
   |  zod-validated, read-only allowlist, injection-hardened argv
   v
claude -p --output-format json   (your existing Claude Code login)

Verified in release tests against: Claude Code CLI 2.1.163, Codex CLI 0.142.0, MCP SDK 1.x.

Prerequisites

• Node.js >= 20

• Claude Code installed and logged in on each machine: npm install -g @anthropic-ai/claude-code, then run claude once

• Codex CLI >= 0.142 (npm install -g @openai/codex) and/or the Codex desktop app

Related MCP server: codex-in-claude

Quick start

npx -y claude-consult-mcp setup

That runs the platform-correct codex mcp add for you (on Windows it wraps the launcher in cmd /c, which Codex requires for npx-based servers). Then add the recommended timeouts to ~/.codex/config.toml under the server section — codex mcp add has no flags for them:

[mcp_servers.claude-consult]
startup_timeout_sec = 60
tool_timeout_sec = 600

Restart the Codex desktop app so it picks up the new server. Verify with:

npx -y claude-consult-mcp doctor          # environment checks (free)
npx -y claude-consult-mcp doctor --live   # plus one real claude call (costs tokens)
codex mcp list

Manual registration

# Windows
codex mcp add claude-consult -- cmd /c npx -y claude-consult-mcp

# macOS / Linux
codex mcp add claude-consult -- npx -y claude-consult-mcp

快速開始（繁體中文）

1. 每台機器先安裝並登入 Claude Code：npm install -g @anthropic-ai/claude-code，執行一次 claude 完成登入

2. 執行 npx -y claude-consult-mcp setup 自動註冊進 Codex（Windows 會自動加上 cmd /c 包裝）

3. 依上方說明把 startup_timeout_sec = 60、tool_timeout_sec = 600 加進 ~/.codex/config.toml

4. 重啟 Codex 桌面 app；用 npx -y claude-consult-mcp doctor 檢查狀態

The tools: nine by default, ten with journal

claude_continue also accepts stance: "critical" for follow-ups after an adversarial review or debate so Claude keeps its reviewer discipline.

Claude-calling tools also accept optional workspace_dir (absolute path; becomes Claude's working directory — reuse it when continuing a session) and model. Continuation-capable tools also accept session_id; claude_panel always starts fresh conversations. claude_sessions reads only the in-memory metadata ledger; claude_consult_history reads only the opt-in journal. Neither tool invokes Claude.

Losing a session? Call claude_sessions to list recent conversations from this server process, newest first, then pass the recovered session_id and same workspace_dir to claude_continue.

Want recall across restarts? Set CLAUDE_CONSULT_JOURNAL_DIR to a local absolute directory path. The server then registers claude_consult_history, which lists journal entries newest first and can filter by exact workspace_dir.

Every successful result ends with a machine-readable footer:

---
[claude-consult] session_id: <uuid> | cost_usd: 0.12 | duration_ms: 3400 | turns: 2

Example prompt to Codex: "Use the ask_claude tool to ask Claude what it thinks about this design, then continue the session and ask it to fact-check the API you plan to use."

Consultation journal

The journal is opt-in. Nothing is written unless CLAUDE_CONSULT_JOURNAL_DIR is set to a valid local absolute path; relative, UNC, and device paths are rejected. Journal files are JSONL, one file per month named consult-journal-YYYY-MM.jsonl under that directory.

Entries are metadata only: ISO timestamp, originating tool, Claude session_id, workspace directory when present, model when present, a whitespace-collapsed topic excerpt capped at 120 characters, total cost, and duration. The journal never stores full prompts, file contents, or Claude answers. Write failures are logged to stderr and swallowed, so a disk problem cannot fail the consultation.

claude_consult_history is available only when the journal is enabled. It never spawns Claude and it returns plain text without a session footer.

Gate your actions on Claude's verdict

claude_second_opinion, claude_debate_open, and claude_debate_reply request structured output, but Claude's schema compliance is model-dependent best-effort. Check the footer format field before parsing; format: prose means Claude answered directly and the body is wrapped for reading instead of JSON parsing:

const text = result.content[0].text;
const [body, footer = ""] = text.split("\n\n---\n");
const format = footer.match(/\| format: (json|prose)\b/)?.[1];

if (format === "json") {
  const verdict = JSON.parse(body) as { verdict: "agree" | "partial" | "disagree"; confidence: number };
  if (verdict.verdict === "disagree" || verdict.confidence < 0.7) {
    // Re-check the evidence before committing to the change.
  }
} else if (format === "prose") {
  const prose = body.match(/<prose-answer>\n([\s\S]*)\n<\/prose-answer>/)?.[1] ?? body;
  // Read prose directly, or retry once with model "sonnet" or "opus" if strict JSON fields are required.
} else {
  throw new Error("Claude result is missing a structured-output format footer.");
}

Verification workflows

The server ships MCP instructions and trigger-worded tool descriptions so calling agents include Claude in verification workflows without per-user prompt files. Use claude_second_opinion for plans or conclusions, claude_review_files when Claude should inspect code directly, and claude_panel when the user wants multiple perspectives in one call. Claude is instructed to cite precise evidence for every claim: file paths with line numbers it actually read, or URLs it actually fetched, and to verify accessible caller claims before relying on them. If Claude returns a Questions for you: section or a structured questions_for_caller array, answer those questions with claude_continue so the same conversation can produce a better conclusion. For implemented changes, use claude_review_diff so Claude reviews the actual git diff instead of only a summary. Clients that support MCP progress see a heartbeat during long calls.

Example Codex prompt: "Verify this plan with claude_panel using the security and correctness perspectives."

Automatic review gate

claude-consult-mcp review-gate reviews the current git worktree's uncommitted HEAD diff with Claude. It uses hardened git diff flags (--no-ext-diff --no-textconv), includes git status --porcelain, runs through the same advisory runner as the MCP tools, and records origin metadata as review-gate so the in-memory ledger and opt-in journal can show the run.

The gate is fail-open by design. Outside a git repo or on a clean tree it exits 0 silently. Oversized diffs exit 0 with stderr review-gate: diff too large (N bytes), skipped. Missing git, missing Claude, auth failures, timeouts, malformed Claude output, and other gate errors exit 0 with a one-line stderr review-gate: skipped (...) note. It never blocks the caller's workflow.

When it finds something to report, the gate records findings to CLAUDE_CONSULT_GATE_LOG or <CLAUDE_CONSULT_JOURNAL_DIR>/review-gate.log; it also prints them to stdout. Codex does not inject Stop-hook stdout into the next model turn's context. Treat automatic findings as out-of-band review notes: read the log file directly, or use the logged or journaled session_id with claude_continue for follow-up on that Claude conversation.

The default gate model is haiku because the hook can run after many turns. Override it per run with --model <m> or set CLAUDE_CONSULT_GATE_MODEL; the flag wins over the environment variable. Use --quiet to suppress the exact LGTM case:

npx -y claude-consult-mcp review-gate --quiet

To install it as a Codex stop hook:

npx -y claude-consult-mcp setup --install-review-gate
npx -y claude-consult-mcp setup --install-review-gate --gate-log <absolute-path>
npx -y claude-consult-mcp setup --install-review-gate --journal-dir <absolute-path>
npx -y claude-consult-mcp setup --remove-review-gate

Setup edits ~/.codex/hooks.json, creates a timestamped hooks.json.bak-YYYYMMDDHHMMSS backup before modifying an existing hooks file, preserves unrelated hooks, and replaces an existing claude-consult-mcp review-gate entry instead of duplicating it. Passing --gate-log or --journal-dir embeds the matching environment variable into the hook command; both paths must be local absolute paths. If neither flag is supplied, durable findings require Codex to already pass CLAUDE_CONSULT_GATE_LOG or CLAUDE_CONSULT_JOURNAL_DIR to hooks.

One-time trust: after setup --install-review-gate, Codex will not run the hook until you approve it once in an interactive Codex session. The trust prompt cannot be granted in headless codex exec. Review and approve the hook through Codex's hook trust flow when prompted.

Evidence debate workflow

Use claude_debate_open for high-impact architecture, migration, or security decisions where a simple second opinion would collapse too much nuance into agree/disagree. Bring a position plus evidence items: file refs such as src/cache.ts:40-60, URLs, captured command output, or reasoning. For file refs, the server extracts neutral snippets from inside workspace_dir and embeds them in the user prompt so both sides argue over the same bytes; out-of-tree, UNC, device, or oversized exhibit reads become unavailable exhibits rather than expanding file access.

Typical two-round sketch:

1. Open: Codex calls claude_debate_open with the decision, current position, and supporting evidence. Claude returns JSON with claim_verifications, counter_claims, concessions, remaining_disputes, verdict, confidence, and summary_markdown.

2. Reply: Codex verifies Claude's cited evidence, then calls claude_debate_reply with accept for persuasive rulings and rebut plus new evidence for contested claims. Stop when remaining_disputes is empty or after three rounds; report the per-claim outcome to the user.

Debate tools are deliberately slow and expensive compared with ask_claude; use them for decisions where convergence and claim-by-claim evidence matter.

Deep research depth

claude_review_files and claude_review_diff accept depth: "deep" when the machine owner has set CLAUDE_CONSULT_CAPABILITY=deep-research. Deep mode allows Claude to delegate read-only exploration to sub-agents for large scopes, then synthesize the result itself. It is slower and can use several times the turns of a standard review, so reserve it for broad audits, large directories, and risky changes.

Safety probe statement: before enabling this release, the Agent sub-agent token was verified with real haiku probes on Claude Code CLI 2.1.163 (2026-07-09). Under the previously assumed Task token no sub-agent tool exists at all; under Agent a sub-agent spawned, and every write attempt it made (Write, Bash, PowerShell) was denied by the default permission flow - probe.txt was never created. If your local Claude Code behavior differs, keep CLAUDE_CONSULT_CAPABILITY at the default research.

Model and capability policy

The machine owner sets policy ceilings via environment variables; Codex chooses the model per call within those ceilings and can never exceed them.

There is no write tier. The child claude process is only ever allowed Read, Glob, Grep (plus WebSearch, WebFetch at the default research tier; plus the verified Agent sub-agent token only at deep-research). Write, Edit, NotebookEdit, and Bash can never appear in the allowlist, and permission mode is always default. Fable models automatically run at --effort max.

No budget cap is set by default because this package assumes a Claude subscription login with no marginal cost per run. Machines billed through an API key can opt into a spending guard by setting CLAUDE_CONSULT_MAX_BUDGET_USD or running setup --max-budget-usd <n>.

Environment variables (all optional)

Set them at registration time so they live in the Codex config: npx -y claude-consult-mcp setup --model sonnet --capability readonly --allowed-models sonnet,haiku --max-budget-usd 1.

Security notes

• Read-only by design: the exact Claude Code write/execute tool tokens Write, Edit, NotebookEdit, and Bash are always rejected before the child process is spawned; permission mode is never bypassed.

• The deep-research tier adds only the verified Agent sub-agent token. It does not add Write, Edit, NotebookEdit, or Bash; the forbidden-token sweep remains unconditional.

• The prompt travels via stdin — never on the command line — so there is no argv escaping or injection surface; all dynamic argv values (session id, model, paths) are strictly validated.

• --strict-mcp-config keeps your own MCP servers out of the consult child process.

• No credentials are stored by this package. The child Claude process uses the machine's existing Claude Code login and inherits the server process environment like a normal child process.

• Diagnostics go to stderr only; stdout is reserved for the MCP protocol.

• On timeout or shutdown the whole claude process tree is terminated (taskkill on Windows, process-group signals on POSIX) so no orphan processes are left behind.

• UNC and device paths (\\host\share, \\?\..., //server/share) are rejected before any filesystem access, so a prompt-injected Codex cannot use claude_review_files to force NTLM authentication to a remote host.

File-read scope

claude_review_files grants Claude read access (Read/Glob/Grep) to the paths you pass, so it can read any file the OS user running Codex can read — this is the feature, but it is also its blast radius. Because a prompt-injected Codex could target sensitive paths (~/.ssh, ~/.aws, .env files, browser credential stores), treat the tool's reach as equal to that user account's read permissions. If that is a concern in your environment, run Codex (and therefore this server) under a least-privilege account, and only approve claude_review_files calls whose paths you recognize.

Troubleshooting

Cancelling a tool call in your client also terminates the underlying claude process; nothing keeps running in the background.

Development

npm ci
npm run typecheck
npm run build
npm test                 # unit + protocol + stdio E2E (needs a build)
npm run test:coverage    # 80% gate
CLAUDE_CONSULT_E2E=1 npx vitest run test/integration   # real claude round-trip (costs tokens)

License

MIT