search_file_content - Search File Content

Overview

The search_file_content tool searches for regular expression patterns within file contents in a specified directory (or current working directory). It can filter files by glob patterns and returns lines containing matches along with file paths and line numbers.

Tool Name

• Internal Name: search_file_content
• Display Name: SearchFileContent
• Icon: Regex

Parameters

Required Parameters

Parameter	Type	Description
pattern	string	The regular expression pattern to search for within file contents (e.g., function\\s+myFunction, import\\s+\\{.*\\}\\s+from\\s+.*).

Optional Parameters

Parameter	Type	Description
path	string	The absolute path to the directory to search within. If omitted, searches the current working directory.
include	string[]	Array of glob patterns to filter which files are searched (e.g., ['*.js', '*.ts'], ['*.{ts,tsx}', 'src/**']). Each pattern is searched separately and results are merged. If omitted, searches all files (respecting potential global ignores).
limit	number	Maximum number of results to return per file pattern (default: 20). Helps prevent overwhelming results for broad searches.
totalLimit	number	Maximum total number of results across all patterns (default: 100). Provides overall result limit regardless of pattern count.
offset	number	Number of results to skip for pagination (default: 0). Use with limit to implement pagination: offset=0,limit=20 for page 1, offset=20,limit=20 for page 2.
file_filtering_options	object	File filtering options.
file_filtering_options.respect_git_ignore	boolean	Whether to respect .gitignore / VCS ignore files (default: project setting, usually true). Set to false to search ignored files.
file_filtering_options.respect_sii_ignore	boolean	Whether to skip paths matched by .siiignore (default: project setting).
file_filtering_options.use_default_excludes	boolean	When true, skips common large folders like node_modules. Set to false when you intentionally need to search them.

Features

1. Regular Expression Search:

   • Supports full regex syntax
   • Case-sensitive matching
   • Can search for complex patterns

2. File Filtering:

   • Use glob patterns to specify files to search
   • Support multiple include patterns
   • Automatically exclude common large directories

3. Pagination Support:

   • Use limit and offset for pagination
   • Prevent overwhelming results
   • Browse results incrementally

4. Performance Optimization:

   • Prioritizes native ripgrep (rg) command
   • Falls back to JavaScript implementation
   • Smart file filtering

Regular Expression Syntax

Supports standard regular expression syntax:

• .: Match any character
• *: Match preceding element zero or more times
• +: Match preceding element one or more times
• ?: Match preceding element zero or one time
• \\s: Match whitespace character
• \\d: Match digit
• \\w: Match word character
• [abc]: Match any character in brackets
• (a|b): Match a or b
• ^: Match start of line
• $: Match end of line

Usage Examples

Basic Search

{
  "pattern": "function\\s+\\w+"
}

Search in Specific File Types

{
  "pattern": "import.*from",
  "include": ["*.ts", "*.tsx"]
}

Search in Specific Directory

{
  "pattern": "TODO|FIXME",
  "path": "/home/user/project/src"
}

Paginated Search

{
  "pattern": "class\\s+\\w+",
  "limit": 10,
  "offset": 0
}

Search Multiple File Types

{
  "pattern": "console\\.log",
  "include": ["**/*.js", "**/*.ts"]
}

Ignore Default Excludes

{
  "pattern": "error",
  "file_filtering_options": {
    "use_default_excludes": false
  }
}

Return Value

The tool returns an object containing:

• llmContent: Detailed list of matching results
• returnDisplay: User-friendly display information
• summary: Operation summary

Match Result Format

{
  matches: [
    {
      filePath: string;    // File path
      lineNumber: number;  // Line number (1-based)
      line: string;        // Matched line content
    }
  ],
  metadata: {
    totalMatches: number;        // Total matches
    returnedMatches: number;     // Returned matches
    hasMore: boolean;            // Whether there are more results
    currentOffset: number;       // Current offset
    patternsSearched: string[];  // Searched patterns
    searchSummary: string;       // Search summary
    isEstimate: boolean;         // Whether it's an estimate
    searchedPath: string;        // Searched path
  }
}

Error Handling

Possible error scenarios:

1. Pattern Errors:

   • Invalid regex syntax
   • Empty pattern

2. Path Errors:

   • Search path does not exist
   • Search path not within project root

3. Parameter Errors:

   • Negative limit or offset
   • Incorrect parameter types

Performance Considerations

1. Using ripgrep:

   • If rg is installed, the tool automatically uses it
   • rg is much faster than JavaScript implementation

2. File Filtering:

   • Use include patterns to limit search scope
   • Enable use_default_excludes to skip large directories

3. Result Limits:

   • Use limit to restrict results per query
   • Use totalLimit to cap total results

Default Excluded Directories

By default, the following directories are excluded:

• .git
• node_modules
• bower_components
• .svn
• .hg
• dist
• build
• coverage

You can search these directories by setting use_default_excludes: false.

Notes

1. Regex Escaping: In JSON, you need double escaping (e.g., \\s for whitespace)
2. Performance: Searching large codebases may take time
3. Binary Files: Binary files are automatically skipped
4. Large Files: Very large files may be skipped or partially searched

Related Tools

• glob: Find files based on filename patterns
• read_file: Read file contents
• read_many_files: Read multiple files in batch
• list_directory: List directory contents