magi-researchers

Three AI models. One synthesis. Zero lost progress. Multi-model research pipeline for Claude Code — Claude, Gemini, and Codex debate, cross-verify, and synthesize publication-ready artifacts.

Why MAGI? • Get Started • Features • Usage • Roadmap • Changelog

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.

• 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.

Experiment details

• 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}/.

Alternative: Local Development

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

Features

Research Pipeline

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

All features

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

Under the hood

• 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

Depth Control

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

All flags