How Research Subagents Are Defined and Invoked in Feynman: A Technical Deep Dive

Research subagents in Feynman are defined as markdown-based specifications in .feynman/agents/ and invoked programmatically via Pi’s subagent tool using runs.all() for parallel execution or runs.one() for single tasks.

Feynman orchestrates complex research workflows through bundled Pi subagents, with the researcher subagent serving as the primary autonomous information-gathering component. This architecture enables parallel literature reviews, web searches, and data extraction while maintaining strict orchestration control within the Pi framework. Understanding how these subagents are defined and invoked is essential for extending Feynman’s capabilities or debugging research pipelines.

Defining Research Subagents in Feynman

The researcher subagent follows a declarative configuration pattern that separates agent capabilities from execution logic.

The Markdown-Based Agent Specification

Agent definitions reside in the hidden .feynman/agents/ directory as markdown files. The core researcher specification lives at website/src/content/docs/agents/researcher.md, which delineates the agent’s purpose, search strategy, extraction pipeline, and dependent workflows. This file acts as the canonical contract between the orchestration layer and the research implementation.

According to the source, the markdown definition describes how the researcher queries AlphaXiv for academic papers, performs web searches for documentation, and interfaces with Hugging Face repositories. The specification includes structured directives that tell the Pi framework which tools to inject—specifically web_search and fetch_content—when initializing the subagent.

Loading via the Subagent Extension

At runtime, Pi loads these definitions through the subagent extension. The extension’s configuration (located in the subagents section of Pi’s main settings) points to the bundled prompts stored in the .feynman/agents/ directory. Feynman’s setup scripts ensure these prompts are properly registered by patching Pi’s configuration file at ~/.pi/agent/extensions/subagent/config.json.

The patching logic is implemented in scripts/lib/pi-subagents-patch.mjs, which validates that the bundled researcher definition is included in the extension’s load path. This ensures that when workflows invoke agent: 'researcher', Pi can resolve the specification to the correct markdown prompt and inject the appropriate search tools.

Invoking Research Subagents in Workflows

Workflow scripts invoke the researcher through Pi’s subagent tool, using either parallel or singular execution patterns depending on the research scope.

Parallel Execution with runs.all

For comprehensive research tasks requiring multiple information sources, lead agents spawn parallel researcher instances using runs.all. This method accepts an array of task configurations, each specifying the target agent, task description, and output file path.

The following example from the deep research workflow demonstrates parallel invocation for web and academic sources:

await runs.all([
  {
    key: 'web',
    agent: 'researcher',
    task: 'Read outputs/.plans/xyz-T1.md and write xyz-research-web.md.',
    output: 'xyz-research-web.md',
  },
  {
    key: 'papers',
    agent: 'researcher',
    task: 'Read outputs/.plans/xyz-T2.md and write xyz-research-papers.md.',
    output: 'xyz-research-papers.md',
  },
]);

Each entry in the array executes concurrently, with the key providing a unique identifier for result aggregation. The task string is interpreted by the researcher’s prompt logic to determine whether to prioritize AlphaXiv queries, general web searches, or repository mining.

Single Agent Calls with runs.one

For scoped research tasks, workflows use runs.one to invoke a single researcher instance. This approach is common in literature review commands or targeted audits where parallelization is unnecessary.

await runs.one({
  key: 'lit',
  agent: 'researcher',
  task: 'Gather literature on "graph neural networks".',
  output: 'gnn-literature.md',
});

Task Interpretation and Output Handling

The researcher subagent processes the task parameter to determine search strategy and scope. Upon completion, the agent writes structured findings to the path specified in the output field. The lead agent validates these output paths before proceeding to downstream processing agents such as the verifier or writer, ensuring data integrity across the pipeline.

Configuration and Customization

Users can customize researcher behavior without modifying core prompt files through Pi’s settings override system.

Agent Overrides in Settings JSON

Configuration overrides reside in the settings JSON under subagents.agentOverrides.researcher. These overrides allow adjustment of thinking levels, extension permissions, and custom tool injection. The configuration file is read from Pi’s home directory and dynamically patched by Feynman’s initialization scripts to ensure bundled prompts remain the default while user preferences take precedence.

For example, users can restrict the researcher to specific academic databases or enable additional content extraction tools by modifying the agentOverrides object before the subagent extension initializes.

Integration with High-Level Commands

The researcher subagent serves as a required dependency for Feynman’s high-level CLI commands. Commands including /deepresearch, /lit, /review, /audit, /replicate, /recipe, /compare, and /draft declare the researcher as a mandatory subagent in their workflow definitions.

When these commands execute, the lead agent evaluates topic breadth to determine whether to spawn one or multiple researcher instances. For broad survey tasks, the system automatically parallelizes research across web and academic sources, while narrow technical queries trigger single-agent invocations. This dynamic orchestration ensures optimal resource utilization while maintaining the structured output requirements of each command.

Summary

• Research subagents in Feynman are defined via markdown specifications in .feynman/agents/researcher.md, which describe search strategies and tool requirements.
• Pi’s subagent extension loads these definitions at runtime and injects tools like web_search and fetch_content for AlphaXiv and repository queries.
• Workflows invoke researchers using runs.all for parallel tasks or runs.one for singular investigations, specifying tasks and output paths in the invocation object.
• High-level commands (/deepresearch, /lit, etc.) automatically orchestrate researcher subagents based on topic complexity.
• Customization occurs through subagents.agentOverrides.researcher in Pi’s settings JSON, enabling tool and strategy adjustments without modifying core prompt files.

Frequently Asked Questions

Where is the researcher subagent defined in the Feynman repository?

The researcher subagent is defined in website/src/content/docs/agents/researcher.md, which specifies the agent’s purpose, search strategies, and workflow dependencies. This markdown file resides in the hidden .feynman/agents/ directory structure and is loaded by Pi’s subagent extension at runtime.

How does Feynman execute multiple research tasks in parallel?

Feynman uses Pi’s runs.all method to execute researcher subagents concurrently. Workflow scripts pass an array of configuration objects, each containing an agent: 'researcher' declaration, a specific task string, and an output file path. This pattern enables simultaneous web searches and academic paper reviews while maintaining isolated output files for aggregation.

Can I customize the researcher subagent’s behavior without editing core files?

Yes. Users can override researcher behavior through the subagents.agentOverrides.researcher section in Pi’s settings JSON located at ~/.pi/agent/extensions/subagent/config.json. These overrides allow modification of thinking levels, tool availability, and search strategies while preserving the base prompt definitions in the Feynman repository.

Which Feynman commands rely on the researcher subagent?

The researcher subagent is required for multiple high-level commands including /deepresearch, /lit, /review, /audit, /replicate, /recipe, /compare, and /draft. Each command implements specific orchestration logic that determines whether to invoke a single researcher instance or parallelize tasks across multiple subagents based on the query scope.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}