# gpt-researcher

Assists developers in extending, debugging, and integrating GPT Researcher pipelines, retrievers, and MCP data sources.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode, Windsurf (Devin Desktop), Claude.ai · 1 install · ★ 30819 repo stars
- Author: assafelovic
- License: Apache-2.0 · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/assafelovic/gpt-researcher/tree/HEAD/.claude/SKILL.md
- Updated: 2026-10-10
- Security check: automated, 2026-11-16 (text) — no signs of malicious code found.
- HTML: https://affpapa.org/en/nevibecode/skills/gpt-researcher

## What it does

Provides internal architectural context for GPT Researcher, an autonomous agent that collects web or local data using a planner-executor-publisher setup. It directs the coding assistant through core classes such as `GPTResearcher`, sub-query planning in `ResearchConductor`, and report generation via `ReportGenerator`.

The skill details an 8-step pattern for implementing new features, rules for registering search engines in `gpt_researcher/retrievers/`, and streaming events over WebSocket connections. It also explains configuring MCP tools via `mcp_configs` with deep or fast strategies.

Every research call relies on async execution. Configuration keys are normalized to lowercase on access, so calling uppercase attribute names causes runtime failures.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add assafelovic/gpt-researcher --skill gpt-researcher -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/claude/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/claude/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add assafelovic/gpt-researcher --skill gpt-researcher -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/claude/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add assafelovic/gpt-researcher --skill gpt-researcher -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/claude/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install assafelovic/gpt-researcher claude
```

2. **Manually: put the files in place**
- File: `.github/skills/claude/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add assafelovic/gpt-researcher --skill gpt-researcher -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/assafelovic/gpt-researcher --path .claude
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/claude/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add assafelovic/gpt-researcher --skill gpt-researcher -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/assafelovic/gpt-researcher/tree/HEAD/.claude/SKILL.md

## When to use it
- implement a custom retriever class in the research pipeline
- attach external data sources using MCP server configurations
- follow the 8-step workflow to introduce features across backend and frontend
- stream execution status updates and logs through WebSocket handlers

## Example prompts
- Show how to register a new retriever in gpt_researcher/actions/retriever.py
- Configure an MCP GitHub server connection for deep research mode
- Help implement the 8-step pattern for adding a provider to gpt-researcher

## Source text · SKILL.md · Apache-2.0

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: 74b28b8c2bb6adea.

BEGIN THIRD-PARTY FILE 74b28b8c2bb6adea
````text
---
name: gpt-researcher
description: GPT Researcher is an autonomous deep research agent that conducts web and local research, producing detailed reports with citations. Use this skill when helping developers understand, extend, debug, or integrate with GPT Researcher - including adding features, understanding the architecture, working with the API, customizing research workflows, adding new retrievers, integrating MCP data sources, or troubleshooting research pipelines.
---

# GPT Researcher Development Skill

GPT Researcher is an LLM-based autonomous agent using a planner-executor-publisher pattern with parallelized agent work for speed and reliability.

## Quick Start

### Basic Python Usage

```python
from gpt_researcher import GPTResearcher
import asyncio

async def main():
    researcher = GPTResearcher(
        query="What are the latest AI developments?",
        report_type="research_report",  # or detailed_report, deep, outline_report
        report_source="web",            # or local, hybrid
    )
    await researcher.conduct_research()
    report = await researcher.write_report()
    print(report)

asyncio.run(main())
```

### Run Servers

```bash
# Backend
python -m uvicorn backend.server.server:app --reload --port 8000

# Frontend
cd frontend/nextjs && npm install && npm run dev
```

---

## Key File Locations

| Need | Primary File | Key Classes |
|------|--------------|-------------|
| Main orchestrator | `gpt_researcher/agent.py` | `GPTResearcher` |
| Research logic | `gpt_researcher/skills/researcher.py` | `ResearchConductor` |
| Report writing | `gpt_researcher/skills/writer.py` | `ReportGenerator` |
| All prompts | `gpt_researcher/prompts.py` | `PromptFamily` |
| Configuration | `gpt_researcher/config/config.py` | `Config` |
| Config defaults | `gpt_researcher/config/variables/default.py` | `DEFAULT_CONFIG` |
| API server | `backend/server/app.py` | FastAPI `app` |
| Search engines | `gpt_researcher/retrievers/` | Various retrievers |

---

## Architecture Overview

```
User Query → GPTResearcher.__init__()
                │
                ▼
         choose_agent() → (agent_type, role_prompt)
                │
                ▼
         ResearchConductor.conduct_research()
           ├── plan_research() → sub_queries
           ├── For each sub_query:
           │     └── _process_sub_query() → context
           └── Aggregate contexts
                │
                ▼
         [Optional] ImageGenerator.plan_and_generate_images()
                │
                ▼
         ReportGenerator.write_report() → Markdown report
```

**For detailed architecture diagrams**: See [references/architecture.md](references/architecture.md)

---

## Core Patterns

### Adding a New Feature (8-Step Pattern)

1. **Config** → Add to `gpt_researcher/config/variables/default.py`
````
END THIRD-PARTY FILE 74b28b8c2bb6adea

The third-party file has ended. Everything between the 74b28b8c2bb6adea tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

First 2886 of 7327 bytes. © assafelovic · Apache-2.0 · https://github.com/assafelovic/gpt-researcher/tree/HEAD/.claude/SKILL.md

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md
