---

name: exploring-codebase description: Locate code, trace flows, and find usages in codebases. Use proactively for "where is", "how does", "find", "called", "used", or any code search question.

Codebase Explorer

Explore and understand codebases by locating files, tracing flows, and finding usages.

Quick Reference

Goal	Tool	When
Natural language search	warpgrep_codebase_search	Default choice
Semantic/conceptual search	finder	Fallback if warpgrep unclear
Exact string/pattern	Grep	Last resort, precise matches

Complexity Guide

Query	Approach
Simple (≤3 searches)	Call tools directly
Complex (>3 searches)	Spawn Task subagent

Examples

Simple: Find a function

User: "where is the auth middleware?"
→ warpgrep_codebase_search(search_string='where is auth middleware defined')
→ Return: file paths with line numbers

Moderate: Trace a flow

User: "how does the search API work?"
→ warpgrep_codebase_search(search_string='search API endpoint handler')
→ Read relevant files
→ warpgrep_codebase_search(search_string='search service calls database')
→ Return: summary with file paths

Complex: Debug investigation

User: "why is the background job failing?"
→ Task(
    description: "Investigate background job failure",
    prompt: "Find all code related to background job execution.
    Use warpgrep_codebase_search for: job scheduler, job handler, error handling.
    Read relevant files and trace the flow.
    Return: summary of job lifecycle with file paths and potential failure points."
  )

Fallback Chain

Issue	Action
No results	Broaden query, remove specific terms
Too many results	Add file path filter, use Grep for exact match
Wrong results	Rephrase with different terminology
Warpgrep unavailable	Use finder, then Grep

Output Format

• Always include file paths with line numbers
• Group findings by file
• End with concise summary for complex investigations