magi-researchers

---

Like the MAGI system in Evangelion — three supercomputers cross-verifying each other — this plugin orchestrates Claude, Gemini, and Codex for rigorous, multi-perspective research.

Why MAGI?

Single-model research has blind spots. One model hallucinates a citation or misses a critical constraint — and nobody catches it.

	Single Model	MAGI (3 Models)
Brainstorming	One perspective	Three independent perspectives
Verification	Self-review (unreliable)	Cross-model peer review
Blind spots	Undetected	Caught by competing models
Output	Raw text	Structured report with consensus & divergence analysis

• Claude (MELCHIOR) — The Scientist. Active third MAGI personality — synthesis, planning, implementation, and original analytical contributions.
• Gemini — The Critic. Creative brainstorming, cross-verification, broad knowledge.
• Codex — The Builder. Feasibility analysis, code review, implementation focus.

Case Study: Damped Oscillator Equation Discovery

We gave all three single models and MAGI the same physics problem: discover an unknown damping function from noisy sensor data. No single model proposed combining classical diagnostics with modern ML — only MAGI's cross-verification caught that gap.

Source	Score	Highlight
MAGI	90	Staged pipeline: rapid diagnostics → symbolic discovery → validation → fallback
Claude	84	Best code coverage — runnable snippets for every approach
Codex	80	Elegant physics-informed neural ODE constraints
Gemini	67	Most accessible for general audience

• Task: Discover $f(\dot{x})$ in $m\ddot{x} + f(\dot{x}) + kx = 0$ from noisy displacement data
• Setup: Identical prompt → 4 sources → anonymized blind evaluation via MAGI
• Evaluation: Two MAGI evaluator personas scored, cross-reviewed, and debated before synthesis
• Limitations: N=1 case study, self-evaluation (MAGI evaluated MAGI), ~7:1 compute ratio
• Full report: examples/damped_oscillator_comparison/evaluation_report.md
• Raw outputs: examples/damped_oscillator_comparison/

Get Started

Prerequisites: Claude Code + Python 3.11+ with uv + Gemini CLI + Codex CLI

1. Install the plugin (inside Claude Code):

/plugin marketplace add Axect/magi-researchers
/plugin install magi-researchers@magi-researchers-marketplace

2. Set up MCP servers (one-time):

claude mcp add -s user gemini-cli -- npx -y gemini-mcp-tool
claude mcp add -s user codex-cli -- npx -y @cexll/codex-mcp-server
claude mcp add -s user context7 -- npx -y @upstash/context7-mcp@latest

3. Run your first research:

/magi-researchers:research "your research topic" --domain physics

MAGI generates cross-verified hypotheses, writes implementation code, renders publication-quality plots, and synthesizes a structured report — all saved to outputs/{topic}/.

git clone https://github.com/Axect/magi-researchers.git
claude --plugin-dir /path/to/magi-researchers
uv add matplotlib SciencePlots numpy

Features

Research Pipeline

Phase	What Happens	Output
Brainstorm	Three models generate and cross-review ideas with expert personas	brainstorm/
Plan	Concrete research plan with execution metadata, stress-tested by a hostile reviewer	plan/
Implement	Language-agnostic implementation with dry-run verification and frontmatter update	src/
Execute	Deterministic code execution from plan frontmatter; generates result artifacts	results/
Test & Visualize	Workspace-aware two-tier testing + publication-quality plots	tests/ + plots/
Report	Structured report with cross-verified claim-evidence integrity	report.md

Highlights

• MAGI-in-MAGI — --depth max scales to N domain specialists, each running a full mini-MAGI brainstorm in parallel with adversarial meta-debate
• Adversarial review — Models debate, cross-verify, and attack each other's plans (murder board) before synthesis
• Resume anywhere — --resume picks up from existing artifacts. No state files — your outputs are the checkpoints.
• Publication-quality output — matplotlib + scienceplots (Nature theme), LaTeX math, PNG 300 dpi + vector PDF, structured reports with MAGI traceability

Quality Assurance

• Holistic & weighted scoring — Default expert-judgment ranking; optionally supply explicit JSON weights or adaptive prompt-analyzed weights
• Dynamic persona casting — Each model gets a topic-specific expert identity, sharpening ideation
• Phase gates — Automated quality checkpoints with conditional MAGI mini-review before each user approval step

Resilience

• Artifact contracts — Each phase validates upstream files before running. Catches silent failures before they cascade.
• Agent substitution — --substitute "Gemini -> Opus" replaces a rate-limited model with Claude across all pipeline stages.
• Workspace anchor — .workspace.json locks the output directory path, preventing artifact drift after context compression.
• Gemini fallback chain — Resilient 3-tier model fallback: gemini-3.1-pro-preview → gemini-2.5-pro → Claude

More

• MAGI traceability review — All three models cross-verify the final report for orphaned claims and figures
• Report gap detection — Auto-generates missing visualizations from existing data
• Domain templates — Built-in context for Physics, AI/ML, Statistics, Mathematics, and Paper Writing
• Journal strategy — Venue recommendations for Physics, AI/ML, and Interdisciplinary research

• Plot manifest — Structured plot_manifest.json with metadata, section hints, and captions for automated report integration
• Common Restrictions — Phase 4 enforces four output-interface contracts: plot_manifest.json (fixed schema), PNG + PDF/SVG dual format, execution evidence, dependency spec file. Internal process is autonomous.
• Workspace Detection — Phase 3 and 4 detect languages and ecosystems from actual src/ files (package managers first, then file extensions). Priority: reality (src/) > plan intent > domain defaults.
• Two-tier testing — Tier 1 (unit, mock-based, always runs) and Tier 2 (integration, depends on results/, skipped gracefully if absent). Test frameworks match the detected workspace language.
• Deterministic execution — Phase 3.5 reads execution_cmd and dry_run_cmd directly from research_plan.md YAML frontmatter. No heuristics, no entry-point guessing.
• research_plan.md frontmatter — Carries languages, ecosystem, execution_cmd, dry_run_cmd, expected_outputs, and estimated_runtime fields as machine-readable metadata for downstream phases.
• Cross-phase artifact contracts — Each phase validates incoming artifacts before running (tool-based Glob/Read, not LLM guesswork)
• Depth-controlled token budget — --depth low skips cross-review for fast/cheap runs; --depth high enables full adversarial debate
• @filepath artifact references — MCP tool calls use @filepath syntax instead of inline content, so large artifacts are read directly from disk with zero truncation

Usage

Command	Description
/magi-researchers:research "topic"	Full pipeline (Brainstorm → Plan → Implement → Execute → Test → Report)
/magi-researchers:research-brainstorm "topic"	Brainstorming with cross-verification
/magi-researchers:research-write --source <dir>	Collaborative writing from research artifacts
/magi-researchers:research-explain "concept"	Concept explanation with Teacher/Critic pipeline
/magi-researchers:research-implement	Language-agnostic implementation (needs existing plan)
/magi-researchers:research-execute	Execute research code; generate results/ artifacts
/magi-researchers:research-test	Workspace-aware testing & visualization
/magi-researchers:research-report	Report generation

Depth Control

The --depth flag controls how thoroughly models review each other's work:

Depth	What Happens	Cost
low	Independent brainstorming, no cross-review	Cheapest
medium (default)	Cross-model peer review + synthesis	Standard
high	Full adversarial debate (defend/concede/revise)	Higher
max	MAGI-in-MAGI: N specialist subagents, each running a full mini-MAGI	Highest

Flag	Values	Default	Description
--domain	physics ai_ml statistics mathematics paper	auto-inferred	Research domain for context
--weights	JSON / adaptive	holistic	Scoring mode: omit for expert-judgment ranking, JSON for weighted, adaptive for prompt-analyzed
--depth	low medium high max	medium	Review thoroughness
--personas	2–5	auto	Number of domain-specialist subagents for --depth max
--resume	<output_dir>	—	Resume an interrupted pipeline from the last completed phase
--claude-only	flag	off	Replace Gemini/Codex with Claude subagents for single-model usage
--substitute	"Gemini -> Opus" "Codex -> Opus"	—	Replace a specific model with Claude when hitting rate limits