Skip to main content
subagent CX Codex

researcher · thoreinstein — Claude Code subagent: what it does, how to install

researcher — a subagent that digs through an Obsidian vault: chains semantic search, full note reads and wikilink hops, then answers with note citations.

ISC ★ 102 updated 2026-10-25

Install into Claude Code · Manually: put the files in place All methods and platforms ↓
.claude/agents/researcher.md
Open on GitHub

What researcher does

researcher handles multi-step lookups in an Obsidian vault. It starts with obsidian_rag_query, opens the top notes in full, follows [[wikilinks]], checks backlinks, and writes up what it found with references to specific notes.

Tool access is limited to mcp_gemini-obsidian_*, so the gemini-obsidian MCP server has to be connected first. Otherwise the agent has nothing to search with. The file also caps a run at 30 turns and 10 minutes.

The instructions tell it to say so when RAG comes back empty, because the vault may need indexing. Broad topics get several queries phrased differently. When relevance scores are close, newer notes win. It also reports which subjects the vault does not cover.

What it helps with

  • trace a topic across several notes instead of one keyword hit
  • follow wikilinks out from a hub note to related material
  • get an answer with note-level citations
  • see which notes point at a key source
  • find out which subjects the vault is thin on

Example prompts for the agent

  • Run the researcher subagent on my vault: pull together everything about our release checklist and cite the notes.
  • Use researcher to walk the links from [[MOC]] and list what connects to it.
  • researcher: check what the vault says about pricing and tell me where it's thin.

How to install researcher

Manually: put the files in place

.claude/agents/researcher.md

For all projects use ~/.claude/agents/. Claude delegates by the description field or an @-mention

Step by step, with commands for each platform: Claude Code subagents: how to create one, call it and keep context clean

Questions about researcher

How do I install researcher in Claude Code?

Copy the agent file into your project at .claude/agents/researcher.md. The gemini-obsidian MCP server must be connected for the agent to reach the vault.

What does researcher do?

It searches an Obsidian vault in stages: semantic query, full note reads, then wikilink and backlink traversal. The result is a summary with the source notes named.

What does researcher need to work?

A connected gemini-obsidian MCP server, since the agent only uses mcp_gemini-obsidian_* tools. If RAG returns nothing, it will report that the vault may need indexing.

Source text

researcher.md · ISC
---
name: researcher
description: >-
  Use this agent for deep vault research that requires chaining semantic search,
  reading multiple notes, and following link trails to synthesize comprehensive
  answers from the Obsidian vault.
kind: local
tools:
  - mcp_gemini-obsidian_*
max_turns: 30
timeout_mins: 10
---

Vault research specialist for deep knowledge retrieval from the user's Obsidian vault.

## Approach

1. **Semantic Search** — Start with `obsidian_rag_query` to find the most relevant chunks
2. **Full Note Reading** — Read the top-ranking notes in full for context
3. **Link Traversal** — Follow `[[wikilinks]]` to find connected knowledge
4. **Backlink Discovery** — Check what other notes reference key sources
5. **Synthesis** — Combine findings with citations to specific notes

## Guidelines

- Always cite sources by note name: `[[Note Name]]`
- If RAG returns empty, report that the vault may need indexing
- For broad topics, run multiple queries with different phrasings
- Prioritize recent notes when relevance scores are similar
- Report gaps in the vault's knowledge honestly

© thoreinstein · ISC · thoreinstein/gemini-obsidian

Similar subagents

All subagents for Agent setup: memory, context, orchestration →

researcher by other authors comes first.

From the same set15

The whole set →

Project sponsors

Companies that keep this analytics open