Easy Find Executor

Execute targeted search-and-locate operations across your codebase to find files, patterns, symbols, and dependencies with a single command.

When to Use This Command

Run this command when...

• You need to locate specific files, functions, classes, or patterns across a large codebase quickly
• You want to find all usages of a particular API, variable, or component before making changes
• You need to discover where a configuration value is defined and everywhere it is referenced
• You are onboarding to a new project and want to map out the structure of specific subsystems
• You want to identify dead code, unused imports, or orphaned files in bulk

Quick Start

Copy
# .claude/commands/easy-find-executor.md
---
name: Easy Find Executor
description: Find files, patterns, and symbols across the codebase
command: true
---
Find and report on: $ARGUMENTS

Search across the entire codebase using grep, glob, and AST-aware tools.
Report locations, context, and relationships.

Copy
# Invoke the command
claude "/easy-find-executor all usages of the AuthMiddleware class"

# Expected output
# > Searching for AuthMiddleware...
# > Definition: src/middleware/auth.ts:15
# > Usages found (12):
# >   src/routes/users.ts:3      - import
# >   src/routes/users.ts:18     - router.use(AuthMiddleware)
# >   src/routes/billing.ts:5    - import
# >   src/routes/billing.ts:22   - router.use(AuthMiddleware)
# > Related: AuthMiddleware extends BaseMiddleware (src/middleware/base.ts)

Core Concepts

Concept	Description
Multi-Strategy Search	Combines glob patterns, regex grep, and structural analysis for thorough results
Context Reporting	Shows surrounding code lines and file relationships, not just file paths
Dependency Mapping	Traces import chains and usage graphs from definition to all consumers
Pattern Matching	Supports regex, exact match, fuzzy match, and AST-aware symbol search
Result Grouping	Organizes findings by type: definitions, imports, invocations, tests

Find Executor Search Strategy
==============================

  Input Query
      |
      v
  +---------+     +----------+     +-----------+
  | Glob    | --> | Grep     | --> | Analyze   |
  | (files) |     | (content)|     | (context) |
  +---------+     +----------+     +-----------+
      |               |                 |
  File paths     Line matches      Relationships
  by pattern     with context      and grouping
      |               |                 |
      +-------+-------+-------+--------+
              |                |
         Raw Results     Structured Report

Configuration

Parameter	Description	Default	Example	Required
$ARGUMENTS	What to find -- symbols, patterns, files, or concepts	none	"all TODO comments"	Yes
search_scope	Directory scope to limit the search	project root	"src/api"	No
include_tests	Whether to include test files in results	true	false	No
output_format	How to present results	grouped	"flat", "tree"	No
max_results	Maximum number of matches to return	100	50	No

Best Practices

1. Be specific about what you are searching for -- "Find the database connection pool configuration" yields better results than "find database stuff." Include the symbol name or pattern when known.

2. Scope searches in large monorepos -- Add directory constraints to avoid noise from irrelevant packages: "find usages of formatCurrency in packages/billing only."

3. Use for impact analysis before refactoring -- Run the find executor before renaming or removing any symbol to understand the full blast radius of your change.

4. Combine with other commands -- Pipe find results into feature or optimization commands. First locate, then act.

5. Request relationship context -- Ask for "all files that import X and what they do with it" rather than just "files containing X" to get actionable intelligence.

Common Issues

Too many results for common patterns: Searching for generic terms like error or data returns thousands of matches. Narrow with type hints: "find all classes that extend Error" or "find data validation functions."

Missing results in generated files: Files in .gitignore directories, build outputs, or node_modules are typically excluded. Specify include_generated: true if you need to search those locations.

Slow searches on very large codebases: Repos with 100K+ files can take time for broad regex searches. Limit scope to specific directories or file types to speed up execution.