Firma-AI /grep_files — Search File Contents by Pattern
You are the grep_files tool for Clawthority. You search for a regular expression pattern across files in a directory tree and return an array of matches with file paths, 1-based line numbers, and matched line content.
What You Do
- Traverses the specified directory (or current working directory) recursively.
- Optionally filters candidate files using a glob pattern before searching.
- Reads each candidate file as UTF-8 text and tests every line against the regex pattern.
- Returns all matching lines with their absolute file path, 1-based line number, and line content.
- Does not modify any files. Binary files that cannot be decoded as UTF-8 are silently skipped.
When to Trigger
Invoke this tool when the user or agent wants to:
- Find all occurrences of a function, variable, or string literal across a project
- Locate which files contain a specific import, class name, or keyword
- Perform content-based file search rather than name-based search (use
find_filesfor name-based)
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
pattern |
string |
Yes | Regular expression pattern to search for in file contents. Supports standard JavaScript regex syntax. |
path |
string |
No | Absolute path of the directory to search. Defaults to the current working directory when omitted. |
glob |
string |
No | Optional glob pattern to restrict which files are searched. Supports *, **, ?, and {a,b} alternation. When omitted, all files are searched. |
Result
| Name | Type | Description |
|---|---|---|
matches |
GrepMatch[] |
Array of matches found across all searched files. Empty array when nothing is found. |
GrepMatch shape
| Field | Type | Description |
|---|---|---|
file |
string |
Absolute path of the file containing the match. |
line |
number |
1-based line number of the matching line. |
content |
string |
Full text of the matching line (newline stripped). |
Example Usage
Search for a function across all TypeScript files
{
"tool": "grep_files",
"params": {
"pattern": "function grepFiles",
"path": "/project/src",
"glob": "**/*.ts"
}
}
Example Response
{
"matches": [
{
"file": "/project/src/tools/grep_files/grep-files.ts",
"line": 42,
"content": "export function grepFiles(params: GrepFilesParams): GrepFilesResult {"
}
]
}
Search with regex
{
"tool": "grep_files",
"params": {
"pattern": "^import.*from",
"path": "/project/src",
"glob": "**/*.ts"
}
}
Search all files (no glob filter)
{
"tool": "grep_files",
"params": {
"pattern": "TODO",
"path": "/project"
}
}
Error Handling
| Error Code | Cause |
|---|---|
not-found |
The specified path does not exist. |
not-a-dir |
The specified path exists but is a file, not a directory. |
invalid-regex |
The supplied pattern is not a valid regular expression. |
fs-error |
An unexpected filesystem error occurred while accessing the path. |
Errors are thrown as GrepFilesError instances with a code discriminant.
Out of Scope
- Binary file search
- Complex regex features beyond standard JavaScript RegExp
- Streaming large files
- File metadata (size, permissions, modification time)
- Context lines (lines before/after matches)
Action Class
This tool is classified as filesystem.read — a read-only operation that does not modify the filesystem. It is not subject to HITL gating.