search_files

The search_files tool performs regex searches across multiple files in your project. It helps Roo locate specific code patterns, text, or other content throughout your codebase with contextual results.

Parameters

The tool accepts these parameters:

• path (required): The path of the directory to search in, relative to the current working directory
• regex (required): The regular expression pattern to search for (uses Rust regex syntax)
• file_pattern (optional): Glob pattern to filter files (e.g., '*.ts' for TypeScript files)

What It Does

This tool searches across files in a specified directory using regular expressions, showing each match with surrounding context. It's like having a powerful "Find in Files" feature that works across the entire project structure.

When is it used?

• When Roo needs to find where specific functions or variables are used
• When Roo helps with refactoring and needs to understand usage patterns
• When Roo needs to locate all instances of a particular code pattern
• When Roo searches for text across multiple files with filtering capabilities

Key Features

• Searches across multiple files in a single operation using high-performance Ripgrep
• Shows context around each match (1 line before and after)
• Filters files by type using glob patterns (e.g., only TypeScript files)
• Provides line numbers for easy reference
• Uses powerful regex patterns for precise searches
• Automatically limits output to 300 results with notification
• Truncates lines longer than 500 characters with "[truncated...]" marker
• Intelligently combines nearby matches into single blocks for readability

Limitations

• Works best with text-based files (not effective for binary files like images)
• Performance may slow with extremely large codebases
• Uses Rust regex syntax, which may differ slightly from other regex implementations
• Cannot search within compressed files or archives
• Default context size is fixed (1 line before and after)
• May display varying context sizes when matches are close together due to result grouping

How It Works

When the search_files tool is invoked, it follows this process:

1. Parameter Validation: Validates the required path and regex parameters
2. Path Resolution: Resolves the relative path to an absolute path
3. Search Execution:
   • Uses Ripgrep (rg) for high-performance text searching
   • Applies file pattern filtering if specified
   • Collects matches with surrounding context
4. Result Formatting:
   • Formats results with file paths, line numbers, and context
   • Displays 1 line of context before and after each match
   • Structures output for easy readability
   • Limits results to a maximum of 300 matches with notification
   • Truncates lines longer than 500 characters
   • Merges nearby matches into contiguous blocks

Search Results Format

The search results include:

• Relative file paths for each matching file (prefixed with #)
• Context lines before and after each match (1 line by default)
• Line numbers padded to 3 spaces followed by | and the line content
• A separator line (----) after each match group

Example output format:

# rel/path/to/app.ts
 11 |   // Some processing logic here
 12 |   // TODO: Implement error handling
 13 |   return processedData;
----

# Showing first 300 of 300+ results. Use a more specific search if necessary.

When matches occur close to each other, they're merged into a single block rather than shown as separate results:

# rel/path/to/auth.ts
 13 | // Some code here
 14 | // TODO: Add proper validation
 15 | function validateUser(credentials) {
 16 |   // TODO: Implement rate limiting
 17 |   return checkDatabase(credentials);
----

Examples When Used

• When asked to refactor a function, Roo first searches for all places the function is used to ensure comprehensive changes.
• When investigating bugs, Roo searches for similar patterns to identify related issues across the codebase.
• When addressing technical debt, Roo locates all TODO comments across the project.
• When analyzing dependencies, Roo finds all imports of a particular module.

Usage Examples

Searching for TODO comments in all JavaScript files:

<search_files>
<path>src</path>
<regex>TODO|FIXME</regex>
<file_pattern>*.js</file_pattern>
</search_files>

Finding all usages of a specific function:

<search_files>
<path>.</path>
<regex>function\s+calculateTotal</regex>
<file_pattern>*.{js,ts}</file_pattern>
</search_files>

Searching for a specific import pattern across the entire project:

<search_files>
<path>.</path>
<regex>import\s+.*\s+from\s+['"]@components/</regex>
</search_files>