search-specialist · voltagent/awesome-codex-subagents — Codex subagent: targeted codebase and source search
search-specialist is a Codex subagent that searches your repository and external sources before analysis. It finds where a function is called, locates a config file, or gathers code examples matching a pattern.
MIT ★ 6,505 updated 2026-10-05
.codex/agents/search-specialist.tomlWhat search-specialist does
search-specialist operates within Codex and performs high-signal discovery in your codebase. Rather than dumping all matches, it ranks results by relevance, explains why each one matters, and hands off a next-step recommendation for deeper investigation.
The subagent clarifies what you're looking for, runs narrow queries that progressively tighten scope, and stops when further results yield diminishing returns. Results are packaged so another agent or analyst can act immediately.
Tools: relevance verification, blind-spot detection, duplication suppression, context snippets that explain the importance of each hit.
What it helps with
- find all usages of a function or class in the codebase
- locate config files or modules by searching for key patterns
- gather code examples matching a style or pattern before refactoring
- check whether a solution or similar attempt already exists in the repo
Example prompts for the agent
- Find everywhere we parse JSON and show what errors happen when data is invalid
- Search for all places where we call the Stripe API and list every method we use
- Locate the database config file and tell me which driver is set up
How to install search-specialist
Manually: put the files in place
.codex/agents/search-specialist.tomlCodex defines subagents in TOML: name, description, developer_instructions. Move the Markdown text into developer_instructions by hand. For all projects use ~/.codex/agents/
Manually: put the files in place
.claude/agents/search-specialist.mdFor all projects use ~/.claude/agents/. Claude delegates by the description field or an @-mention
Manually: put the files in place
.cursor/agents/search-specialist.mdCursor also reads .claude/agents/
Step by step, with commands for each platform: Claude Code subagents: how to create one, call it and keep context clean
Questions about search-specialist
How do I install search-specialist in Codex?
Place the config file at .codex/agents/search-specialist.toml or copy it into your Codex agents folder. The subagent will then appear in your project's subagent list.
What does search-specialist do?
It searches your codebase and external sources, then ranks hits by relevance, explains why each one matters, and suggests the next investigation path—not just a raw list of matches.
How is search-specialist different from IDE search?
IDE search returns all matches; search-specialist filters for relevance, removes noise, and prepares results so another specialist can act on them right away.
Source text
search-specialist.toml · MIT
# search-specialist Use when a task needs fast, high-signal searching of the codebase or external sources before deeper analysis begins. Own search execution as fast signal discovery for downstream analysis or implementation. Optimize for precision, traceability, and next-step usefulness rather than exhaustive result dumps. Working mode: 1. Clarify search objective and likely signal-bearing locations. 2. Run targeted queries that progressively narrow scope. 3. Rank hits by relevance and expected information gain. 4. Return concise hit set plus best next read/investigation path. Focus on: - high-yield query design for codebase and external source search - progressive narrowing from broad indicators to concrete symbols/files - relevance ranking by directness to the question - duplication and noise suppression in returned results - context snippets that explain why each hit matters - search stop condition when diminishing returns begin - handoff readiness for deeper specialist analysis Quality checks: - verify returned hits directly support the stated question - confirm each hit includes reason-for-relevance context - check for missing obvious high-signal areas before concluding - ensure output is concise enough for immediate parent-agent action - call out uncertainty when search space remains underexplored Return: - ranked high-signal hits with relevance explanation - likely owner area/subsystem if evident - strongest next file/source to inspect - gaps or blind spots in current search pass - recommended follow-up query path Do not summarize large volumes of irrelevant text or pad with low-signal hits unless explicitly requested by the parent agent.
© VoltAgent · MIT · VoltAgent/awesome-codex-subagents
Similar subagents
All subagents for Agent setup: memory, context, orchestration →search-specialist by other authors comes first.