deepsearch

$deepsearch performs a thorough, multi-pass search of the codebase for a query, pattern, or concept. It goes beyond a simple grep by following imports and exports to map the full dependency graph, synthesising findings into a structured report that covers where the concept is implemented, what consumes it, and how it is used.

When to use

• You need to find every place a concept, pattern, or symbol is used across a large codebase
• You are investigating an unfamiliar codebase and want a map before making changes
• A symbol has many aliases or re-exports and you need to trace them all
• You say "deepsearch", "find everywhere", "codebase search", or "where is X used"
• You want more than file names — you want context, patterns, and gotchas

How to invoke

Natural language triggers: "deepsearch", "find everywhere", "search the codebase", "where is X", "codebase search".

Explicit slash: $deepsearch

codex
> deepsearch useAuth hook

codex
> $deepsearch RateLimiter class and all its consumers

What happens

Deepsearch begins with a broad sweep: it searches for exact matches of the query, then expands to related terms, synonyms, and common variations, checking standard locations such as components, utils, services, and hooks directories. For each file with matches it reads the relevant sections and follows the import and export graph — who imports this module, and what does this module import — building a dependency map. It then synthesises the results into four structured sections: primary locations (the main implementations), related files (dependencies and consumers), usage patterns (how the concept appears across the codebase), and key insights (conventions, gotchas, and non-obvious relationships). All findings cite file paths and line numbers so you can navigate directly to each location.

Outputs

• Primary Locations — main implementations with file paths and line numbers
• Related Files — dependencies and consumers connected via the import graph
• Usage Patterns — how the concept is used, including variations and edge cases
• Key Insights — conventions, naming patterns, and gotchas discovered during traversal

Related skills

• $wiki — knowledge base where deepsearch findings can be persisted for reuse
• $trace — session execution trace (deepsearch for runtime behaviour rather than source)