Three-model code review consensus — disagreement is the value, not consensus.
Three independent AI models cross-examine your code. They challenge each other's blind spots, hunt for what the others missed, and surface every disagreement instead of burying it. Built on five Constitutional Physics invariants and a four-phase operating protocol. Provider-agnostic across OpenAI, DeepSeek, Anthropic, Ollama, LM Studio, vLLM, and MLX.
Quick Start · Constitutional Physics · Install · IDE Compatibility · Pairs With
Would you wing a complicated surgery with one surgeon?
Then why are you shipping code reviewed by one AI?
Every AI coding tool has the same flaw: one model, one perspective, one set of blind spots. Claude confabulates confidently where GPT hedges. GPT over-engineers where a local model stays lean. A single AI reviewer is a single point of failure — and you'd never accept that in a real operating room.
3-Surgeons puts three independent AI models on the same operating table. They don't just review — they cross-examine, challenge assumptions, and hunt for what the others missed. Your code ships only when all three agree it's ready.
| Surgeon | Role | Default Model | |
|---|---|---|---|
| 🔪 | Atlas (Head Surgeon / Judge) | Synthesizes findings, weighs evidence, decides, implements — never overrides without grounds | Claude (your IDE session) |
| 🩺 | Cardiologist (External Skeptic) | External-model perspective from a different training distribution. Surfaces what Atlas can't see | DeepSeek-chat (drop-in OpenAI also supported) |
| 🧠 | Neurologist (Local Devil's Advocate) | Runs locally for privacy and corrigibility. Forces counter-position before consensus locks in | DeepSeek-chat via local proxy (Qwen3-4B legacy) |
A single AI reviewer is a single point of failure. Three reviewers, hunting independently, force the truth into the open.
3-Surgeons is built on one belief: the bottleneck in AI-assisted coding is no longer speed — it's calibration. A confidently wrong answer ships faster than a careful right one. Three independent surgeons make confidence earnable — every claim survives cross-examination or it dies on the table.
| Scale | What it unlocks |
|---|---|
| 1 model | One opinion. Fast. Possibly wrong, but you wouldn't know. |
| 2 models | A check. Often agree. Disagreement = stop and look. |
| 3 models | Triangulation. Truth becomes recoverable. The blind spot of any one model is exposed by the other two. |
| 5+ models | A specialty board. Each surgeon brings a different training distribution. Convergence under independent attack is evidence, not opinion. |
| Continuous review | Every diff cross-examined. Every claim audited. Every blind spot named. Calibration compounds across the codebase. |
The protocol scales linearly with the number of surgeons. The architecture is provider-agnostic. The only ceiling is your tolerance for groupthink.
Five principles that govern every surgical operation. These are invariants — no tool call, no config flag, no shortcut overrides them.
| # | Principle | What it means |
|---|---|---|
| 1 | Preserve Determinism | Same inputs must produce the same output. Non-deterministic paths trigger safe mode and are flagged before shipping. |
| 2 | No Discovery at Injection | Retrieval only during context injection — no new reasoning, no live inference. Prevents hallucinations from contaminating shared state. |
| 3 | Respect SOP Integrity | Standard Operating Procedures change only when backed by reproducible evidence from at least two surgeons. Opinion alone is not enough. |
| 4 | Evidence Over Confidence | Outcomes are the ground truth. A confident answer that contradicts observed behavior is wrong. |
| 5 | Prefer Reversible Actions | Checkpoint before risk. Every destructive or irreversible action requires explicit surgeon consensus and a rollback path. |
Most AI tools optimize for confidence. 3-Surgeons optimizes for correctness.
The core principle: no surgeon can conclude an opinion until an objective test of the opposing view yields legitimate data — only then is the opinion merited.
This isn't just "get a second opinion." It's an iterative consensus loop:
- Each surgeon hunts independently — different prompts, different search strategies, different biases
- Cross-examination — each surgeon reviews the others' findings and challenges weak points
- Open exploration — "What are we ALL blind to? What assumptions remain unchallenged?"
- Consensus only when saturated — disagreements are preserved, not suppressed
Feel the difference between code that was generated and code that survived.
┌─────────────┐ ┌──────────────┐ ┌─────────────┐ ┌───────────┐
│ 1. TRIAGE │───▶│ 2. OPERATE │───▶│ 3. REVIEW │───▶│ 4. CLOSE │
│ Assess risk │ │ Independent │ │ Cross-exam │ │ Consensus │
│ Set gates │ │ analysis │ │ Challenge │ │ or dissent│
└─────────────┘ └──────────────┘ └─────────────┘ └───────────┘
Triage — Sentinel scans your change for complexity vectors and calibrates review intensity. Operate — Each surgeon analyzes independently. No groupthink. Review — Cross-examination. Each surgeon attacks the others' blind spots. Close — Consensus with confidence scores. Disagreements surfaced, never hidden.
Not every change needs a full surgery. 3-Surgeons adapts review intensity to risk:
| Risk Level | Gate Intensity | When | Time |
|---|---|---|---|
| Light | Sentinel scan only | Docs, config, cosmetic changes | <30s |
| Standard | Sentinel + cross-exam + gains-gate | Feature work, refactors | <120s |
| Full | All gates + counter-position + A/B | Architecture, security, schema, API changes | <300s |
Risk is measured across blast radius, reversibility, security exposure, data impact, and external coupling. The highest-risk dimension determines the gate.
Python 3.10+ is required for the MCP server (cross-examination tools in your IDE).
# Check your version
python3 --version
# If below 3.10, install via Homebrew (macOS)
brew install python@3.12
# Or via pyenv (any platform)
pyenv install 3.12
pyenv global 3.12The 3s init wizard will check your Python version and guide you if it's too old.
# 1. Install (Claude Code)
/plugin marketplace add supportersimulator/3-surgeons
/plugin install 3-surgeons@supportersimulator/3-surgeons
# 2. Run the setup wizard
3s init
# 3. Set your API key(s)
export OPENAI_API_KEY=sk-...
# 4. Verify all surgeons are reachable
3s probe
# 5. Your first cross-examination
3s cross-exam "Should we use Redis or PostgreSQL for session storage?"/plugin marketplace add supportersimulator/3-surgeons
/plugin install 3-surgeons@supportersimulator/3-surgeonsImportant: This uses VS Code's Agent Plugin system (Chat panel), NOT the traditional Extension Marketplace. You will NOT find it by searching in the Extensions sidebar.
Step 1: Install GitHub Copilot Chat
Install the GitHub Copilot Chat extension from the VS Code Marketplace (not the legacy "GitHub Copilot" extension). Sign into GitHub with a Copilot-entitled account.
Step 2: Enable plugins and add the marketplace
Open Settings (Cmd+, / Ctrl+,) and add these to your settings.json:
{
"chat.plugins.enabled": true,
"chat.plugins.marketplaces": ["supportersimulator/3-surgeons"]
}Step 3: Reload and verify
- Reload window (
Cmd+Shift+P→ "Developer: Reload Window") - Open the Chat panel (not Extensions sidebar)
- Type
@agentPluginsto verify the plugin appears
Step 4: Set up the Python runtime
The MCP tools need Python 3.10+ with the package installed:
git clone https://github.com/supportersimulator/3-surgeons.git ~/3-surgeons
cd ~/3-surgeons
python3 -m venv .venv && .venv/bin/pip install -e '.[mcp]'Local path fallback (if marketplace discovery doesn't resolve):
Add the cloned path directly in settings.json:
{
"chat.plugins.paths": {
"/Users/you/3-surgeons": true
}
}cursor plugin add supportersimulator/3-surgeonsgit clone https://github.com/supportersimulator/3-surgeons.git ~/.3surgeons/plugin
cd ~/.3surgeons/plugin
python3 -m venv .venv && .venv/bin/pip install -e '.[mcp]'
codex mcp add 3-surgeons -- ~/.3surgeons/plugin/bin/3surgeons-mcpSee CODEX.md for full setup, config options, and troubleshooting.
gemini extensions install https://github.com/supportersimulator/3-surgeonsSee GEMINI.md for full setup, backend configuration, and troubleshooting.
git clone https://github.com/supportersimulator/3-surgeons.git ~/.claude/plugins/3-surgeons
cd ~/.claude/plugins/3-surgeons
python3 -m venv .venv && .venv/bin/pip install -e '.[mcp]'| IDE | Transport | Status |
|---|---|---|
| Claude Code | MCP (native) | ✅ Full support |
| Cursor | HTTP bridge | ✅ Full support |
| VS Code | HTTP bridge | ✅ Full support |
| Windsurf | HTTP bridge | ✅ Full support |
| Zed | HTTP bridge | ✅ Full support |
| OpenCode | HTTP bridge | ✅ Full support |
| Codex CLI / IDE | MCP (native) | ✅ Full support — see CODEX.md |
| Gemini CLI | MCP (extension) | ✅ Full support — see GEMINI.md |
All tools available via 3s serve HTTP bridge. See three_surgeons/config/ide-adapters/ for per-IDE configuration.
| Mode | Cardiologist | Neurologist | Needs | Cost |
|---|---|---|---|---|
| Hybrid (default) | OpenAI GPT-4.1-mini | Local Ollama qwen3:4b | 1 API key + Ollama | ~$0.003/query |
| API-Only | OpenAI GPT-4.1-mini | DeepSeek deepseek-chat | 2 API keys | ~$0.005/query |
| Local-Only | Ollama mistral:7b | Ollama qwen3:4b | Ollama installed | $0 |
Run 3s init to pick a mode, or copy a preset directly:
cp config/presets/api-only.yaml ~/.3surgeons/config.yamlAny endpoint implementing OpenAI's /v1/chat/completions API works with zero code changes:
Cloud: OpenAI, DeepSeek, Groq, Grok (xAI), Mistral
Local: Ollama, LM Studio, vLLM, MLX
See the full provider matrix for endpoints, models, and pricing.
| Command | Description |
|---|---|
/probe |
Health check all three surgeons |
/cross-exam |
Full 3-phase cross-examination |
/sentinel |
Scan for complexity risk vectors |
/gains-gate |
Infrastructure health gate |
/challenge |
Neurologist corrigibility skeptic |
3s probe # Health check
3s cross-exam "topic" # Full cross-examination
3s consult "topic" # Quick parallel query
3s consensus "claim" # Confidence-weighted vote
3s sentinel "content" # Complexity vector scan
3s gains-gate # Infrastructure health gate
3s neurologist-challenge "topic" # Corrigibility skeptic
3s ask-local "prompt" # Direct neurologist query
3s ask-remote "prompt" # Direct cardiologist query
3s research "topic" # Self-directed research
3s ab-propose PARAM A B "hyp" # Propose A/B testCompose surgical operations into named, replayable chains:
3s chain run full-review # Run a named chain preset
3s chain list # Show available presets
3s chain show full-review # Inspect chain segmentsBuilt-in presets: full-review, quick-check, deep-audit, pre-merge, security-scan. Chains are capability-adaptive — segments that require unavailable surgeons gracefully degrade or skip.
Config lives in ~/.3surgeons/config.yaml (user-level) or .3surgeons.yaml (project-level).
Run 3s init for guided setup, or copy a preset from config/presets/.
See config/3surgeons.example.yaml for the full schema.
The Cardiologist defaults to OpenAI gpt-4.1-mini. DeepSeek is a drop-in alternative — it speaks the same OpenAI-compatible /v1/chat/completions wire protocol, so no adapter changes are required.
Per-invocation CLI flag (preserves backward-compat defaults):
3s --cardio-provider=deepseek cross-exam "your topic"
3s --cardio-provider=openai probe # explicit defaultWhen --cardio-provider=deepseek is set, the Cardiologist routes to https://api.deepseek.com/v1 with model deepseek-chat. Common OpenAI model strings auto-translate:
| OpenAI model | DeepSeek equivalent |
|---|---|
gpt-4.1-mini, gpt-4o-mini, gpt-4.1-nano, gpt-4.1 |
deepseek-chat |
o1-mini, o3-mini, o4-mini |
deepseek-reasoner |
Persistent YAML config:
surgeons:
cardiologist:
provider: deepseek
endpoint: https://api.deepseek.com/v1
model: deepseek-chat # or deepseek-reasoner for o1-style reasoning
api_key_env: Context_DNA_DeepseekOr copy the ready-made preset:
cp config/presets/cardio-deepseek.yaml ~/.3surgeons/config.yamlAPI key resolution order (DeepSeek):
- The env var named in
api_key_env(defaultContext_DNA_Deepseek) DEEPSEEK_API_KEY(fallback — matches/ersim/prod/backend/DEEPSEEK_API_KEYin AWS Secrets Manager and.env.example)- macOS Keychain via the 3-Surgeons MCP launcher (
3surgeons-mcp)
If none are set and --cardio-provider=deepseek requires a live call, the CLI fails fast with an actionable message naming both env vars.
Status reporting: cap_status / 3s status surfaces the active provider under surgeons.cardiologist.provider, so IDE dashboards can render Cardiologist: OK [deepseek] vs [openai].
Default unchanged: omitting --cardio-provider and leaving surgeons.cardiologist.provider at its default preserves the original OpenAI gpt-4.1-mini behavior — no migration required.
- All API keys are loaded from environment variables — never hardcoded, never committed
- Local-Only mode: zero data leaves your machine. The Neurologist runs entirely on your hardware
.gitignoreexcludes all secret files, config files, and databases- See
.env.examplefor the full list of supported environment variables
3-Surgeons provides the epistemological layer (truth calibration through multi-model consensus). The Superpowers plugin provides the process layer (workflow discipline, TDD, debugging, planning skills). Together they form a complete surgical operating environment — rigorous process AND rigorous truth-testing.
3-Surgeons is the quality dimension. Multi-Fleet is the scale dimension. Run 3-Surgeons on a single machine and you get calibrated correctness. Run it across a Multi-Fleet of N machines and every surgeon-trio shares findings via NATS — disagreements surface fleet-wide, consensus compounds across nodes. Correctness × scale = a coding board of directors that never sleeps.
3-Surgeons works standalone. But it was built to be the scalpel in a much larger operating theater.
ContextDNA adds persistent memory, a priority-scheduled local LLM (your Neurologist on steroids), adaptive webhook injection, and a butler subconscious that learns your codebase across sessions. Think of it as upgrading from a field hospital to a world-class surgical suite.
3-Surgeons adapts to the sophistication of your codebase.
When you're ready:
from context_dna.adapters import priority_queue_adapter
provider = LLMProvider(config, query_adapter=priority_queue_adapter)See docs/CONTEXTDNA-IDE-UPGRADE.md for the full migration guide.
These are the load-bearing protocols. Each is a hard-gate — no surgeon can bypass them, no shortcut overrides them.
| Skill | When to invoke | What it protects against |
|---|---|---|
| architectural-gate | Before any architecture decision | Locking in a design before the other two surgeons have argued the opposite |
| counter-position | Before any opinion is concluded | Confirmation bias — forces a steelman of the opposing view before signing off |
| pre-implementation-review | After plan, before code | Building the wrong thing perfectly. Catches scope drift and missed requirements |
| post-implementation-verification | After code, before merge | "Looks done" claims that don't survive contact with reality. Demands evidence, not confidence |
| invariance-health | Continuously | Surgeon drift, stale API keys, model deprecations, silent provider degradation |
The skills compose. A high-risk change runs all five. A docs typo runs none. Risk tier (Light / Standard / Full) determines which fire automatically.
A recent change proposed flipping the Cardiologist default from OpenAI to DeepSeek. Atlas (Claude) called it a clean swap — same wire protocol, lower cost. Cross-examination surfaced what the head surgeon missed:
Atlas (Head Surgeon):
"Drop-in. DeepSeek implements /v1/chat/completions. Ship it."
Confidence: 0.92
Cardiologist (External Skeptic):
"Wire-compatible, yes. But o1-style reasoning models translate differently.
Add an auto-translation table (gpt-4.1-mini -> deepseek-chat,
o1-mini -> deepseek-reasoner) or downstream callers silently get the
wrong model."
Confidence: 0.78 — DISAGREES
Neurologist (Local Devil's Advocate):
"API key resolution will silently fall through to the wrong env var.
Add fallback chain: Context_DNA_Deepseek -> DEEPSEEK_API_KEY ->
macOS Keychain -> fail-fast with an actionable message."
Confidence: 0.81 — DISAGREES
Atlas (synthesis):
"Both objections valid. Adding model translation table + keychain fallback
before merging. New confidence: 0.96."
The shipped commit (93b01c8) includes both safeguards. Without the two dissenting surgeons, the rollout would have produced silent 401s and wrong-model responses. Disagreement was the value, not the consensus.
When all three surgeons agree immediately, that is a weak signal — it may mean groupthink, not correctness. When they disagree, that is the system working.
A disagreement surfaces:
- An assumption one model holds that the others don't
- A risk one model has been trained to weight differently
- A blind spot in the majority view
3-Surgeons never suppresses disagreements. Confidence scores in the final consensus output show exactly where the surgeons diverged and why. The human (or orchestrating agent) decides what to do with that signal — but they decide with full information.
The goal is not fast consensus. The goal is calibrated confidence.
- Fork the repo
- Create a feature branch
- Run tests:
python -m pytest tests/ -v - Submit a PR
3-Surgeons is production-tested at small scale. It powers the daily review loop on a 4-node ContextDNA fleet (mac1, mac2, mac3, cloud) — every commit, every cross-examination, every consensus claim ships through the protocol. It has survived provider outages, model deprecations, and partial-network partitions without dropping a verdict.
It is deliberately scoped: 3-Surgeons does cross-examination, nothing else. Process discipline pairs with Superpowers; fleet scale pairs with Multi-Fleet; orchestration pairs with whatever IDE you live in.
We invite you to test it at your scale.
MIT — do anything you want, just keep the copyright notice. See LICENSE.
Built for engineers who don't ship code reviewed by a single model.
⭐ Star this repo if you've ever shipped a bug all three would have caught.