research-swarm

MCP server that launches parallel claude -p workers to research a topic. Each worker independently searches different aspects, validates output quality, retries failures, and optionally synthesizes results.

Workers run on your Claude Max subscription at $0 marginal cost.

Requirements

• Node.js 18+
• Claude Code CLI installed and authenticated
• Claude Max subscription (workers use claude -p)

Install

cd research-swarm
npm install
npm run build

Register as MCP server

Add to your project's .mcp.json:

{
  "mcpServers": {
    "research-swarm": {
      "command": "node",
      "args": ["/path/to/research-swarm/dist/index.js"],
      "env": {
        "RESEARCH_SWARM_OUTPUT": "/path/to/output"
      }
    }
  }
}

Restart Claude Code. Four tools will be available.

Tools

| Tool | Description | |------|-------------| | research | Start a research job. Returns job_id immediately. Workers spawn in background. | | research_status | Non-blocking status check. Reads from disk. Always instant. | | research_results | Get completed output (synthesis or concatenated worker results). | | research_cancel | Kill all worker processes for a job. |

Use

From any Claude Code session:

> research swarm on [topic]

Or invoke tools directly:

• research(topic, questions, depth?) — Start a job. Depth: quick (3 workers), standard (5 + synthesis), thorough (8 + synthesis).
• research_status(job_id?) — Check progress. Shows phase, worker status, quality scores.
• research_results(job_id?) — Get the report when complete.
• research_cancel(job_id?) — Kill workers and stop the job.

Expect 5-8 minutes for quick depth, 8-12 for standard.

Configuration

| Environment variable | Default | Description | |---------------------|---------|-------------| | RESEARCH_SWARM_OUTPUT | ~/.research-swarm/jobs/ | Job output directory |

How it works

Claude Code session
  └─ MCP server (TypeScript, stdio transport)
       └─ launch-worker.sh (clean env, detached process)
            └─ claude -p worker (--allowedTools, --strict-mcp-config)

1. Plan — Partitions the research space into non-overlapping worker domains
2. Research — Launches workers with 10s stagger. Each independently searches and writes structured findings
3. Validate — Scores each output on a 0-100 rubric
4. Retry — Workers scoring below 40/100 get one retry
5. Synthesize — A final worker cross-references and deduplicates (standard+ depth)
6. Store — Results saved with full metadata

Non-blocking design

The Python predecessor froze because orchestration blocked the MCP event loop. This version:

• Spawns workers as detached child processes (detached: true + proc.unref())
• Monitors via setInterval polling (non-blocking)
• Status reads state.json from disk — always instant
• No blocking awaits in any tool handler

Worker architecture

Workers are claude -p processes launched with:

• --allowedTools — Read, Write, Edit, Glob, Grep, WebSearch, WebFetch
• --strict-mcp-config — Empty config prevents loading project MCP servers
• Clean environment — CLAUDECODE stripped to defeat the nesting guard
• Process isolation — detached: true creates a new process group per worker

Quality scoring rubric

| Check | Points | |-------|--------| | File exists and >500 bytes | 20 | | Has >= 3 Finding sections | 20 | | Has source citations (URLs) | 20 | | Has confidence ratings | 10 | | Has YAML frontmatter | 10 | | Addresses assigned questions | 20 |

Retry threshold: <40. Pass threshold: >=60.

Worker domains

Quick (3 workers)

| Worker | Domain | Strategy | |--------|--------|----------| | 01-web-broad | General web | 5-8 diverse search queries | | 02-web-deep | Technical/forums | Reddit, HN, Stack Exchange, blogs | | 03-data | Structured data | Reports, .gov, .edu, industry data |

Standard (5 workers + synthesis)

Quick plus: | Worker | Domain | |--------|--------| | 04-academic | Research papers, peer-reviewed studies | | 05-contrarian | Dissenting opinions, failure cases |

Thorough (8 workers + synthesis)

Standard plus: | Worker | Domain | |--------|--------| | 06-recent | Last 6-12 months only | | 07-practitioners | Case studies, real-world examples | | 08-adjacent | Transferable insights from neighboring fields |

Project structure

research-swarm/
├── src/
│   ├── index.ts          # MCP server entry point (4 tools)
│   ├── orchestrator.ts   # Job lifecycle, worker spawning
│   ├── workers.ts        # Process management, monitoring
│   ├── quality.ts        # Output quality scoring
│   ├── prompts.ts        # Domain-based prompt generation
│   └── types.ts          # TypeScript interfaces
├── scripts/
│   ├── launch-worker.sh  # Clean-env wrapper for claude -p
│   ├── CLAUDE.md         # Worker behavioral instructions
│   └── empty-mcp.json    # Empty MCP config for fast startup
├── dist/                 # Compiled output (npm run build)
├── _python_archive/      # Previous Python implementation
├── package.json
└── tsconfig.json

License

MIT