find_replace
Search and replace text across files in a directory tree. Preview changes with dry-run before applying edits, with optional regex and glob filters.
Instructions
Grep-equivalent: find text across files with optional replacement. Search and replace text across files in a directory tree.
Defaults to dry_run=true so you can preview the diff before committing. Set dry_run=false to write changes.
When the [edits].show_write_diff config flag is on (the default), the response appends a per-file unified diff — in both preview and applied modes — for up to the first 20 changed files, with a "+N more file(s)" summary beyond that. Set show_write_diff=false to suppress it.
Skips binary files (detected via null-byte sniff of the first 8 KB). Skips files larger than max_file_bytes (50 MiB default). Honours .gitignore. Use 'glob' to limit which files to touch (e.g. ".go", "**/.md"); a glob with a literal directory prefix (e.g. "src/**/*.go") prunes sibling directories from the walk entirely. Files are processed in parallel; output is sorted by path.
For identifier refactors use rename_symbol (scope- and type-aware); find_replace is for plain-text edits (doc strings, license headers, hostnames, version strings, non-code files).
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| glob | No | File glob filter, e.g. '*.go' or '**/*.md'. Empty = all non-binary files. | |
| path | No | Directory to walk, or a single file. Absolute path, file:// URI, or workspace-relative path; defaults relative to the workspace root. | |
| dry_run | No | If true (default), preview only; do not write files. | |
| pattern | No | Search pattern. Plain text by default; regex if use_regex=true. | |
| dirty_ok | No | Allow editing files that have uncommitted changes in their git repository. Default false — the replacement is refused if any target file is dirty. Pass true to proceed anyway. | |
| max_files | No | Cap on number of files modified. | |
| use_regex | No | Treat pattern as a regular expression (Go RE2). Default false — pattern is literal text, so regex syntax such as | or \. matches itself. | |
| replacement | No | Replacement text. With regex, supports $1, $2 backreferences. | |
| format_after | No | After writing changes, run the workspace formatter (gofumpt for Go, ruff format for Python) on each modified file. Formatter errors are reported as warnings and do not fail the call. | |
| case_sensitive | No | Default: smart-case (case-insensitive iff pattern is all lowercase). | |
| max_file_bytes | No | Skip files larger than this many bytes. Default 50 MiB. |