Claude Second Opinion

CI npm License: MIT

A focused local MCP server that lets Codex, or any MCP client, ask a fresh Claude Code session for an independent second opinion without blocking the calling agent.

It is designed for consequential uncertainty: plans, architecture, difficult debugging, security/correctness risks, substantial code changes, and final completion checks. It is not intended to become a mandatory ritual for routine work.

What makes it different

• start_claude_review returns immediately with a review ID.
• get_claude_review checks or retrieves the result later while the caller continues other work.
• cancel_claude_review terminates the Claude process group.
• Every review runs at --effort max.
• The model is configurable; the default best selector can use Fable when available, with Claude Code's native fallback to Opus.
• A zero-cost capacity failure that performed no model work gets one explicit fallback attempt within the original timeout and budget; work is never replayed after model usage, spend, or permission denials.
• The result reports the requested model plus every matching reviewer model in Claude's usage telemetry. The singular field is null when telemetry contains both the configured primary and fallback, avoiding guessed provenance.
• Denied tool calls are surfaced by name and force an insufficient_context verdict instead of allowing a falsely complete review.
• Claude output must match a strict review schema and pass consistency checks.
• Packet-only reviews remain tool-disabled and isolated from the workspace.
• Workspace-aware reviews can inspect a trusted repository with Claude Code's built-in tools and a configurable permission mode.
• The default authentication policy requires first-party Claude.ai Max login and strips alternate-provider overrides to avoid accidental API billing.
• Runtime, input, output, concurrency, and subprocess cleanup are bounded.

Review modes

Packet-only

Omit workspace. Claude receives only the supplied task, artifact, question, and focus fields. Tools are disabled, safe mode is forced on, and the review runs from a temporary directory.

This mode is useful for reviewing a plan, proposal, diagnosis, or draft answer without granting repository access.

Workspace-aware

Supply an absolute workspace path underneath one of the roots configured in CLAUDE_SECOND_OPINION_WORKSPACE_ROOTS_JSON. The path is canonicalized and validated before the background job is accepted. Claude starts in that directory with normal built-in tools.

By default, workspace reviews use:

• --safe-mode
• --permission-mode plan
• a clean child-process environment
• no project CLAUDE.md, hooks, skills, plugins, or project MCP servers

This preserves an independent reviewer while still allowing Claude to inspect files and diffs. Every effective execution profile is returned with the job snapshot.

Safety model

Safe mode, permission mode, and sandboxing solve different problems:

• Safe mode controls Claude Code customizations. It does not disable built-in tools and is not a sandbox.
• Permission mode controls which tool actions Claude Code authorizes.
• OS sandboxing controls what the subprocess can actually reach. A working directory or configured workspace root is not an OS boundary.

bypassPermissions, including the accepted --dangerously-skip-permissions alias, disables Claude Code permission checks. Anthropic recommends it only in externally isolated containers or VMs. In that mode Claude can potentially read or modify files outside the selected workspace, execute commands, use the network, invoke MCP tools, or expose credentials available to the OS user.

The reviewer system prompt prohibits intentional edits, deployments, publishing, contacting people, and external state changes. A prompt is not a security boundary. Use plan or an external sandbox when those actions must be technically prevented.

The packet scanner refuses several common secret formats, but it cannot protect secrets stored in files once workspace tools are enabled. Material Claude reads may be sent to Anthropic. Review SECURITY.md before enabling workspace access.

Requirements

• Node.js 22 or newer
• npm 10 or newer
• Claude Code 2.1.207 or newer available on PATH
• Claude Code authentication compatible with the configured auth policy
• An MCP client such as Codex

Install

Install the command from npm:

npm install --global claude-second-opinion-mcp

To install from source instead:

git clone https://github.com/Borge-Labs/claude-second-opinion-mcp.git
cd claude-second-opinion-mcp
npm ci
npm run build
npm test
npm run smoke

dist/ is generated locally and intentionally not committed.

Codex configuration

Add a server entry to ~/.codex/config.toml, replacing the workspace root with an absolute path on your machine:

[mcp_servers.claude_second_opinion]
command = "claude-second-opinion-mcp"
enabled = true
enabled_tools = ["start_claude_review", "get_claude_review", "cancel_claude_review"]
startup_timeout_sec = 20
tool_timeout_sec = 75

[mcp_servers.claude_second_opinion.env]
CLAUDE_SECOND_OPINION_CLAUDE_BIN = "claude"
CLAUDE_SECOND_OPINION_MODEL = "best"
CLAUDE_SECOND_OPINION_FALLBACK_MODEL = "opus"
CLAUDE_SECOND_OPINION_AUTH_POLICY = "max"
CLAUDE_SECOND_OPINION_ENV_POLICY = "clean"
CLAUDE_SECOND_OPINION_WORKSPACE_ROOTS_JSON = '["/absolute/path/to/projects"]'
CLAUDE_SECOND_OPINION_PERMISSION_MODE = "plan"
CLAUDE_SECOND_OPINION_SAFE_MODE = "true"

If you prefer not to install globally, use command = "npx" and args = ["--yes", "claude-second-opinion-mcp@latest"]. A source checkout can still use command = "node", its built dist/index.js, and the checkout as cwd.

Restart Codex after adding the server or rebuilding it so the MCP process and tool inventory are refreshed.

Explicit full-agent configuration

If the Claude process already runs inside a trusted external sandbox and you want project customizations plus unrestricted tool authorization:

[mcp_servers.claude_second_opinion.env]
CLAUDE_SECOND_OPINION_WORKSPACE_ROOTS_JSON = '["/absolute/path/to/projects"]'
CLAUDE_SECOND_OPINION_PERMISSION_MODE = "bypassPermissions"
CLAUDE_SECOND_OPINION_SAFE_MODE = "false"

The value --dangerously-skip-permissions is accepted as an alias and is normalized internally to bypassPermissions. Environment values are parsed as configuration, never appended as raw command-line flags.

Calling the tools

Start a workspace-aware review:

{
  "kind": "final_check",
  "task": "Review the current implementation before release.",
  "workspace": "/absolute/path/to/projects/example",
  "artifact": "Focus on the current git diff and the stated release criteria.",
  "question": "Is any material correctness, security, or compatibility risk still unsupported by evidence?",
  "focus": ["correctness", "security", "test evidence"]
}

The start result includes a review_id and execution profile. Continue useful work, then call get_claude_review with that ID. Omit the ID to retrieve the most recently started review in the current MCP process.

Completed reviews include permission_denials. The bridge exposes only denied tool names, not tool inputs, and changes the verdict to insufficient_context whenever that list is non-empty.

MCP cannot reliably inject a completed background result into an already running model turn, so the caller must explicitly retrieve it later.

Suggested agent guidance

This belongs in user or project agent instructions, not in a hard-coded hook:

Use the optional Claude second-opinion MCP selectively when another model
perspective is likely to affect a consequential decision. Start a useful review
early, continue independent work while it runs, and retrieve and reconcile the
result before a relevant final handoff. Do not use it for routine or mechanical
work or repeat a review on materially unchanged input.

Configuration reference

Variable	Default	Purpose
CLAUDE_SECOND_OPINION_CLAUDE_BIN	claude	Claude Code executable
CLAUDE_SECOND_OPINION_MODEL	best	Primary model or selector
CLAUDE_SECOND_OPINION_FALLBACK_MODEL	opus	Native and zero-work capacity fallback model
CLAUDE_SECOND_OPINION_AUTH_POLICY	max	max, first_party, or any
CLAUDE_SECOND_OPINION_ENV_POLICY	clean	Reviewed operational/network allowlist or explicit inherit
CLAUDE_SECOND_OPINION_WORKSPACE_ROOTS_JSON	[]	JSON array of trusted absolute workspace roots
CLAUDE_SECOND_OPINION_PERMISSION_MODE	plan	Valid Claude Code permission mode or dangerous alias
CLAUDE_SECOND_OPINION_SAFE_MODE	true	Disable Claude customizations for workspace reviews
CLAUDE_SECOND_OPINION_ALLOWED_TOOLS_JSON	[]	JSON array passed as Claude allowed-tool rules
CLAUDE_SECOND_OPINION_DISALLOWED_TOOLS_JSON	[]	JSON array passed as Claude denied-tool rules
CLAUDE_SECOND_OPINION_TIMEOUT_MS	5400000	Review timeout, 90 minutes
CLAUDE_SECOND_OPINION_MAX_INPUT_BYTES	140000	Maximum serialized review packet size
CLAUDE_SECOND_OPINION_MAX_BUDGET_USD	2	Claude print-mode budget ceiling when applicable
CLAUDE_SECOND_OPINION_DEBUG	unset	Set to 1 for bounded Claude diagnostics on failures

--effort max is always passed, and the child environment is forced to CLAUDE_CODE_EFFORT_LEVEL=max so an inherited lower setting cannot override it.

Auth policies:

• max: require first-party Claude.ai Max and remove provider overrides.
• first_party: require first-party Claude.ai authentication and remove provider overrides.
• any: accept any logged-in Claude Code provider configuration. Combine this with ENV_POLICY=inherit only when intentionally using credentials supplied through environment variables.

The clean environment is a reviewed operational allowlist, not a secret-free boundary. It retains standard proxy, certificate, mTLS path, and CLAUDE_CONFIG_DIR settings needed for supported Claude installations. Proxy URLs can contain credentials. The mTLS key passphrase is deliberately omitted; set ENV_POLICY=inherit only when that credential is required. Use an external sandbox when workspace tools must not be able to observe process configuration.

Tool allow rules pre-authorize matching tools; they are not a filesystem sandbox. Deny rules and Claude Code sandbox settings provide additional layers.

Job lifecycle

• Only one review runs at a time.
• The default internal timeout is 90 minutes.
• Start/get/cancel MCP calls remain short.
• Job state is retained in memory for the active MCP process.
• Restarting or disconnecting the MCP client cancels active work and clears retained results.
• Timeout, cancellation, and shutdown send TERM and then KILL to the Claude process group on supported platforms.

Development

npm ci
npm test
npm run smoke
npm audit --omit=dev

The unit suite uses a fake Claude executable and makes no model calls. The optional live test consumes Claude usage:

npm run smoke:live

To exercise real workspace inspection, point the smoke test at a trusted root that is also covered by the configured workspace roots. The script creates and removes a temporary sentinel fixture, proves Claude read it, and verifies that the fixture was not modified. The live harness forces plan permission mode and safe mode for this check:

CLAUDE_SECOND_OPINION_WORKSPACE_ROOTS_JSON='["/absolute/path/to/projects"]' \
CLAUDE_SECOND_OPINION_SMOKE_WORKSPACE=/absolute/path/to/projects \
npm run smoke:live

See CONTRIBUTING.md for contribution guidance and CHANGELOG.md for release history.

Project and trademark notice

The public GitHub repository is a mirror of the canonical Gitea repository. GitHub issues and pull requests are welcome and are integrated upstream before being mirrored back.

This is an independent open-source project. It is not affiliated with, endorsed by, or sponsored by Anthropic or OpenAI. Claude, Claude Code, Codex, and related names are trademarks of their respective owners.

License

MIT License. See LICENSE.