# researcher

The researcher subagent examines code, documentation, and module relationships, then organizes findings into a research summary. Use it to map an unfamiliar project or spot gaps in its docs.

- subagent · `type=agent` · Claude Code, Codex, Cursor · ★ 850 repo stars
- Author: ruvnet
- License: not stated · policy=link-only · description only; the file stays with the author
- Source: https://github.com/ruvnet/agentic-flow/tree/HEAD/agentic-flow/.claude/agents/core/researcher.md
- Updated: 2026-10-26
- Security check: automated, 2026-11-16 (text) — no signs of malicious code found.
- HTML: https://affpapa.org/en/nevibecode/agents/researcher

## What it does

researcher inspects code and documentation, identifies recurring approaches and anti-patterns, and traces links between internal modules and external packages. Its findings are organized into a summary covering project structure, dependencies, recommendations, and gaps.

The instructions describe file searches, cross-checking definitions against their usages, and reviewing Git history. Before and after a task, hooks use `npx claude-flow` to look up related research and save results. Those hook steps depend on `claude-flow` and its memory features being available; otherwise, they cannot run as described.

For Claude Code, install the subagent at `.claude/agents/researcher.md`. It is set up to investigate and report on a codebase, not to make code changes automatically.

## Install

### Claude Code (native platform)

**Manually: put the files in place**
- File: `.claude/agents/researcher.md` — For all projects use ~/.claude/agents/. Claude delegates by the description field or an @-mention

### Codex

**Manually: put the files in place**
- File: `.codex/agents/researcher.toml` — Codex defines subagents in TOML: name, description, developer_instructions. Move the Markdown text into developer_instructions by hand. For all projects use ~/.codex/agents/

### Cursor

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

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/ruvnet/agentic-flow/tree/HEAD/agentic-flow/.claude/agents/core/researcher.md

## When to use it
- map the structure of a codebase
- spot recurring patterns and anti-patterns
- trace dependencies between modules
- compare project documentation with implementation
- compile findings and gaps into recommendations

## Example prompts
- Research this project's structure and describe its main architectural patterns.
- Trace dependencies between the modules and show where they are used.
- Compare the documentation with the code and list the gaps you find.

## Similar
- [wiki-researcher](https://affpapa.org/en/nevibecode/agents/wiki-researcher.md) — subagent · ★ 3232 repo stars
- [code-explorer](https://affpapa.org/en/nevibecode/skills/code-explorer.md) — skill · 146 installs
- [technical-researcher](https://affpapa.org/en/nevibecode/agents/technical-researcher.md) — subagent · 3344 installs
- [analyze-project](https://affpapa.org/en/nevibecode/skills/analyze-project.md) — skill · 363500 installs
- [docs-researcher](https://affpapa.org/en/nevibecode/agents/docs-researcher.md) — subagent · ★ 6505 repo stars
- [gsd-phase-researcher](https://affpapa.org/en/nevibecode/agents/gsd-phase-researcher.md) — subagent · ★ 3785 repo stars

## Other versions with the same name
- [researcher · thoreinstein](https://affpapa.org/en/nevibecode/agents/thoreinstein-researcher.md) — ★ 102 repo stars

From the same set: [ruvnet/agentic-flow](https://affpapa.org/en/nevibecode/by/ruvnet/agentic-flow.md) — 76 cards

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