Deep Research

Academic-grade multi-agent research pipeline for Claude Code.

npx deep-research-cc

3-stage pipeline: Research Agents -> Synthesis Agents -> Report Builder

"Point it at a question, walk away, come back to an academic-grade research report with citations."

How It Works · Prerequisites · Installation · Usage · Architecture

The Problem

Manual research with AI tools is shallow. You search, read, forget context, search again. Sources get lost. Analysis stays surface-level. And if your context window fills up, everything collapses.

Deep Research fixes that. It decomposes your question into independent research domains, dispatches parallel agents to investigate each one, synthesizes findings through dedicated analysis agents, and produces a comprehensive report with full citations. All three stages write to disk, so nothing is lost to context limits.

How It Works

Stage 1: Research Agents (parallel)

You provide a topic. The pipeline decomposes it into 3-6 independent research domains and launches parallel agents, each investigating one domain using Firecrawl MCP for web search and scraping.

Each agent writes a raw research document to docs/plans/YYYY-MM-DD-{domain}-research.md.

Stage 2: Synthesis Agents (parallel)

After all research agents complete, synthesis agents launch in parallel. Each synthesis agent reads exactly ONE research file (strict 1:1 mapping) and produces a distilled domain summary with evidence quality assessment, gap analysis, and organized findings.

Each agent writes to docs/plans/YYYY-MM-DD-{domain}-synthesis.md.

Stage 3: Report Builder (single agent)

A single report builder agent reads ALL synthesis files and produces a comprehensive, externally-shareable research report following an academic template.

Final report: docs/plans/YYYY-MM-DD-{topic}-report.md

What You Get

A structured research report with:

• Executive Summary with confidence assessment
• Methodology documenting search strategy and source evaluation
• Domain Findings with citations and evidence quality ratings
• Cross-Cutting Analysis identifying themes, contradictions, and risks
• Synthesis and Recommendations with alternatives table
• Limitations and suggested follow-up research
• Full References organized by domain with source type and relevance ratings

Every factual claim traces back to a cited source. The report stands alone: someone with no prior context can read and learn from it.

Prerequisites

| Requirement | Details | |-------------|---------| | Claude Code | Anthropic's CLI for Claude | | Node.js | v18+ (for npx installer) | | Firecrawl MCP | Paid API key from firecrawl.dev |

Note: Firecrawl is a paid service that provides web search and scraping capabilities. Deep Research requires it for all web-based research. Visit firecrawl.dev/pricing for current plans.

Installation

Quick Install (recommended)

npx deep-research-cc

The installer copies the skill files into ~/.claude/ and backs up any existing files.

npx deep-research-cc --global   # Install to ~/.claude/
npx deep-research-cc --local    # Install to ./.claude/

Use --global (-g) or --local (-l) to skip the interactive prompt.

Clone the repository and use symlinks for live editing:

git clone https://github.com/desland01/deep-research.git ~/deep-research
cd ~/deep-research
chmod +x install.sh
./install.sh

Changes in ~/deep-research/ are live immediately via symlinks.

Firecrawl MCP Setup

Deep Research uses Firecrawl MCP for all web search and scraping. You must configure it before using the skill.

Step 1: Get an API Key

Sign up at firecrawl.dev and get your API key from the dashboard.

Step 2: Add Firecrawl MCP to Claude Code

claude mcp add firecrawl-mcp -e FIRECRAWL_API_KEY=your-key-here -- npx -y firecrawl-mcp

Step 3: Restart Claude Code

Restart Claude Code to load both the new skill and the Firecrawl MCP server.

Verify Setup

Start Claude Code and type /deep-research. If the skill loads, you're ready.

Usage

In any Claude Code session:

/deep-research What are the best approaches to real-time voice AI for mobile apps?

The pipeline will:

1. Decompose your question into 3-6 research domains
2. Launch parallel research agents (each writes to disk)
3. Launch parallel synthesis agents (each reads one research file, writes synthesis)
4. Launch a report builder (reads all syntheses, writes final report)
5. Report the file location and top-level findings

Example Output Files

For a research topic "voice AI providers for React Native":

docs/plans/
  2026-02-16-voice-ai-landscape-research.md
  2026-02-16-voice-ai-pricing-research.md
  2026-02-16-voice-ai-react-native-research.md
  2026-02-16-voice-ai-latency-research.md
  2026-02-16-voice-ai-privacy-research.md
  2026-02-16-voice-ai-landscape-synthesis.md
  2026-02-16-voice-ai-pricing-synthesis.md
  2026-02-16-voice-ai-react-native-synthesis.md
  2026-02-16-voice-ai-latency-synthesis.md
  2026-02-16-voice-ai-privacy-synthesis.md
  2026-02-16-voice-ai-providers-report.md      <- Final report

Architecture

/deep-research [topic]
       |
       v
   Decompose into 3-6 domains
       |
       v
  ┌────┬────┬────┬────┬────┐
  R1   R2   R3   R4   R5   R6    <- Research agents (parallel, background)
  |    |    |    |    |    |         Each writes *-research.md to disk
  └────┴────┴────┴────┴────┘
       |
       v  (wait for ALL to complete)
       |
  ┌────┬────┬────┬────┬────┐
  S1   S2   S3   S4   S5   S6    <- Synthesis agents (parallel, background)
  |    |    |    |    |    |         1:1 with research agents
  └────┴────┴────┴────┴────┘         Each reads one *-research.md, writes *-synthesis.md
       |
       v  (wait for ALL to complete)
       |
      [RB]                        <- Report builder (single agent, background)
       |                             Reads ALL *-synthesis.md files
       v                             Writes final *-report.md
   Final Report

Agent Limits

| Constraint | Value | |-----------|-------| | Max parallel research agents | 6 | | Max parallel synthesis agents | 6 (1:1 with research) | | Report builder agents | 1 (always single) | | Parent reads raw output | Never | | Parent reads final report | Yes (after verification) |

Why Disk-Based Handoff?

Raw research agent output can exceed 600K tokens. If the parent agent reads it via TaskOutput, context gets crushed and downstream agents never launch. Writing to disk files keeps each stage isolated and the parent context clean.

Anti-Patterns

| Don't | Do Instead | |-------|-----------| | Read TaskOutput from research/synthesis agents | Wait for completion, check files on disk | | Assign 2+ research files to one synthesis agent | Strict 1:1 mapping | | Skip the report builder for "simple" research | Always run all 3 stages | | Omit Firecrawl instructions from research agents | Agents don't inherit MCP context | | Omit source URLs | Every claim must trace to a URL |

Troubleshooting

Skill not found after install?

• Restart Claude Code to reload skills
• Verify files exist: ls ~/.claude/skills/deep-research/

Research agents failing?

• Check Firecrawl MCP is configured: look for firecrawl-mcp in your MCP server list
• Verify your API key is valid at firecrawl.dev/dashboard

Report missing sections?

• Check that all research and synthesis files were created in docs/plans/
• The report builder only runs after ALL synthesis agents complete

Context getting crushed?

• This usually means the parent is reading raw agent output. The skill prevents this by design, but if you've modified the protocol, ensure the parent never reads research or synthesis files directly.

Directory Structure

deep-research/
├── README.md
├── VERSION
├── LICENSE
├── .gitignore
├── package.json
├── install.sh                         # Dev install (symlinks)
├── bin/
│   └── install.js                     # npx entry point (copy-based)
└── skills/
    └── deep-research/
        ├── SKILL.md                   # 3-stage protocol
        ├── academic-report-template.md # Report format template
        └── firecrawl-reference.md     # Firecrawl MCP tool reference

Contributing

1. Clone the repo and run ./install.sh
2. Edit files in ~/deep-research/ (changes are live via symlinks)
3. Test with /deep-research in Claude Code
4. For protocol changes, verify all 3 stages produce expected output files

Claude Code is powerful. Deep Research makes it thorough.

Academic-grade research pipelines, so you can decide with confidence.