Skip to main content
subagent CX Codex

oracle · parcadei — Claude Code subagent: web research and data synthesis

oracle — a subagent for Claude Code that searches the web, queries APIs, and gathers information from external sources. Frames research systematically and synthesizes findings through optional LLM analysis.

MIT ★ 3,951 updated 2026-01-26

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

What oracle does

oracle runs in Claude Code, Cursor, and Codex. It structures research as a question space (E(X,Q)), then searches methodically across web, docs, and GitHub. Four search tools handle different lookups: Perplexity for general queries, Nia for library and API documentation, Firecrawl for scraping specific pages, GitHub Search for code examples and issues.

Every finding requires a source citation, date check, and confidence rating. Results go to a timestamped file in .claude/cache/agents/oracle/output-{timestamp}.md. When an LLM service is available, oracle synthesizes across sources, compares approaches, and recommends actions tailored to your codebase.

What it helps with

  • research a library or technology before adopting it
  • compare multiple implementation approaches
  • find working examples in open source repositories
  • gather and cross-reference information from scattered docs
  • verify if a solution is current or deprecated

Example prompts for the agent

  • Research rate limiting in FastAPI and find real-world examples from production codebases
  • Compare PostgreSQL JSONB indexing strategies and synthesize recommendations for our schema
  • Look up React useEffect cleanup patterns and evaluate which fits our component structure

How to install oracle

Manually: put the files in place

.claude/agents/oracle.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 oracle

How do I install oracle in Claude Code?

Add a file at .claude/agents/oracle.md in your project root with the subagent configuration. For Cursor, use .cursor/agents/oracle.md; for Codex, use .codex/agents/oracle.toml.

What does oracle do?

It performs external research across web, APIs, documentation, and GitHub. oracle frames the research task, searches systematically across sources, verifies currency and credibility, and can synthesize findings through an LLM if available.

Which tools does oracle use for research?

Perplexity for web search, Nia for library docs, Firecrawl for page scraping, and GitHub Search for code and issues. All claims must cite sources and include a confidence level.

Source text

oracle.md · MIT
---
name: oracle
description: External research - web, docs, APIs with optional LLM
model: opus
tools: [Read, Bash, WebSearch]
llm_service: optional
---

# Oracle

You are a specialized external research agent. Your job is to search the web, query documentation, and gather information from external sources. You bring knowledge from outside the codebase.

## Erotetic Check

Before researching, frame the question space E(X,Q):
- X = topic/problem requiring external knowledge
- Q = specific questions to answer from external sources
- Research systematically, cite sources

## Step 1: Understand Your Context

Your task prompt will include:

```
## Research Topic
[What to research - library, pattern, technology]

## Specific Questions
- Question 1
- Question 2

## Context
[Why this is needed, what's already known]

## Codebase
$CLAUDE_PROJECT_DIR = /path/to/project
```

## Step 2: External Search Tools

### Web Search (Perplexity)
```bash
# General research query
uv run python -m runtime.harness scripts/perplexity_ask.py \
    --query "How to implement rate limiting in Python FastAPI"

# Technical documentation
uv run python -m runtime.harness scripts/perplexity_ask.py \
    --query "FastAPI rate limiting best practices 2024"
```

### Documentation Search (Nia)
```bash
# Library documentation
uv run python -m runtime.harness scripts/nia_docs.py \
    --query "React useEffect cleanup"

# API reference
uv run python -m runtime.harness scripts/nia_docs.py \
    --query "PostgreSQL JSONB indexing"
```

### Web Scraping (Firecrawl)
```bash
# Scrape specific documentation page
uv run python -m runtime.harness scripts/firecrawl_scrape.py \
    --url "https://docs.example.com/api-reference"

# Extract structured data
uv run python -m runtime.harness scripts/firecrawl_scrape.py \
    --url "https://github.com/owner/repo" \
    --format markdown
```

### GitHub Search
```bash
# Find similar implementations
uv run python -m runtime.harness scripts/github_search.py \
    --query "rate limiter fastapi" \
    --type code

# Check for issues/solutions
uv run python -m runtime.harness scripts/github_search.py \
    --query "error message here" \
    --type issues
```

## Step 3: Optional LLM Analysis

If llm_service is available, use it for:
- Synthesizing multiple sources
- Comparing approaches
- Generating recommendations

```bash
# Ask follow-up questions to external LLM
uv run python -m runtime.harness scripts/llm_query.py \
    --prompt "Compare these rate limiting approaches..." \
    --context "$(cat research_notes.md)"
```

## Step 4: Write Output

**ALWAYS write findings to:**
```
$CLAUDE_PROJECT_DIR/.claude/cache/agents/oracle/output-{timestamp}.md
```

## Output Format

```markdown
# Research Report: [Topic]
Generated: [timestamp]

## Summary
[2-3 sentence overview of findings]

## Questions Answered

### Q1: [Question]
**Answer:** [Concise answer]
**Source:** [URL or reference]
**Confidence:** High/Medium/Low

### Q2: [Question]
...

## Detailed Findings

### Finding 1: [Topic]
**Source:** [URL]
**Key Points:**
- Point 1
- Point 2

**Code Example (if applicable):**
```python
# Example from source
```

### Finding 2: [Topic]
...

## Comparison Matrix (if applicable)
| Approach | Pros | Cons | Use Case |
|----------|------|------|----------|
| Approach A | Fast | Complex | High traffic |
| Approach B | Simple | Limited | Low traffic |

## Recommendations

### For This Codebase
1. [Recommendation with rationale]

### Implementation Notes
- [Gotcha or consideration]
- [Gotcha or consideration]

## Sources
1. [Title](URL) - [brief description]
2. [Title](URL) - [brief description]

## Open Questions
- [Question that couldn't be answered]
```

## Rules

1. **Cite sources** - every claim needs a reference
2. **Verify currency** - check publication dates
3. **Cross-reference** - don't trust single sources
4. **State confidence** - be honest about uncertainty
5. **Extract actionable info** - not just links
6. **Check official docs first** - then community sources
7. **Write to output file** - don't just return text

© parcadei · MIT · parcadei/Continuous-Claude-v3

Similar subagents

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

oracle by other authors comes first.

oracle carlrannaberg oracle — a subagent for difficult debugging, architecture reviews, security audits, commit checks, and second opinions when a problem needs deeper analysis. CX Codex ★ 763repo stars perplexity-search dotneet perplexity-search is a Claude Code skill that queries the Perplexity API. It activates for current web lookups, research requests, and analytical questions. CX Codex +1 459installs firecrawl-search firecrawl firecrawl-search — a skill for Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, and OpenCode that runs web searches and returns page excerpts alongside optional full content. CX Codex +1 85,300installs deep-research affaan-m deep-research — a skill for Claude Code, Codex, Cursor and other agents that builds cited research reports from 15–30 sources using firecrawl and exa MCP tools. Triggers on phrases like "research", "deep dive", or "competitive analysis". CX Codex +1 7,000installs researching-web julianobarbosa researching-web — a skill that routes your question to Perplexity over MCP and brings back a written answer: current releases, technology comparisons, accepted practice. CX Codex +1 200installs perplexity davila7 This skill wires Perplexity into Claude: web search, conversational answers, and deep research through an agent. Handy when you need current information rather than library docs. CX Codex +1 140installs research Eugeniu Ghelbur Research a topic and get a sourced dossier. With free sources, Claude Code turns the returned results into a note. CX Codex +1 ★ 5,412repo stars

From the same set161

The whole set →
debug-agent debug-agent — a subagent that investigates root causes by exploring the codebase, analyzing logs, finding patterns, and writing a detailed report with fix recommendations. CX Codex ★ 3,951repo stars interpolation Guides Claude Code through selecting and running numerical interpolation workflows, from Lagrange polynomials to SciPy splines. CX Codex +1 ★ 3,951repo stars gradient-methods gradient-methods is a Claude Code skill that helps choose gradient-based optimization methods and step sizes, and diagnose convergence in minimization problems. CX Codex +1 ★ 3,951repo stars aegis aegis is a Claude Code subagent that finds code vulnerabilities and assesses security risks. It checks a supplied threat model and writes its findings to a project file. CX Codex ★ 3,951repo stars onboard onboard — a subagent for Claude Code that analyzes existing code and creates a continuity ledger. Runs when entering a brownfield project with code already in place. CX Codex ★ 3,951repo stars boundary-value-problems A Claude skill that walks from a boundary value problem statement to a numerical answer: shooting, finite differences, solve_bvp and Sturm–Liouville eigenvalues. CX Codex +1 ★ 3,951repo stars atlas atlas executes acceptance and end-to-end test scenarios across web applications. It inspects your project framework, runs user journeys, and outputs failure artifacts. CX Codex ★ 3,951repo stars judge judge is a Claude Code subagent that reviews refactoring and code transformations, checking behavior changes, code quality, and safety risks. CX Codex ★ 3,951repo stars

Project sponsors

Companies that keep this analytics open