codebase-search — Claude Code subagent: what it does, how to install
codebase-search finds where a feature lives in your repo and hands back absolute paths plus a short explanation of the flow.
no license ★ 1,064 updated 2026-01-21
.claude/agents/codebase-search.mdWhat codebase-search does
Ask it where something lives and it goes looking. The first move is several tool calls at once: grep for text, glob for filenames, LSP for definitions. One request covers matches and symbols together.
It runs on haiku and never writes or deletes files. The main agent handles the patch; this one maps the ground. GitHub examples arrive through the grep-app MCP server, with context7 and exa wired in alongside. Treat those hits with care, since they can come from a different library version, and the agent checks them against local search before reporting.
Every reply closes with a <results> block: absolute paths, an answer to the underlying need, and suggested next steps.
What it helps with
- locate the auth implementation
- list every call site of a function before a refactor
- work out which files handle payment processing
- get absolute paths you can open straight from the terminal
- see how open-source repos solved the same problem
Example prompts for the agent
- Find where the login flow is implemented and explain it
- List every file that calls
validateUser - Which files handle payment processing?
How to install codebase-search
Manually: put the files in place
.claude/agents/codebase-search.mdFor all projects use ~/.claude/agents/. Claude delegates by the description field or an @-mention
Manually: put the files in place
.codex/agents/codebase-search.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
.cursor/agents/codebase-search.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 codebase-search
How do I install codebase-search in Claude Code?
Drop the agent file at .claude/agents/codebase-search.md inside your project.
What does codebase-search do?
It locates code and files on request, then answers with absolute paths, a short explanation and next steps.
What powers the GitHub search?
Public repo results come through the grep-app MCP server; context7 and exa are connected the same way. Without those servers you are left with local Grep, Glob and LSP.