File Reading and Writing

8.2. File Reading and Writing — Structured File Operations

Four core tools

read_file, write_file, patch, search_files — agent-friendly replacements for cat/grep/sed, with clear structure instead of raw text output.

write_file vs patch

write_file overwrites the entire file content — use it when creating a new file or when you genuinely want to replace everything. patch only changes exactly the part that needs changing (targeted find-and-replace) — avoiding unintended loss of content. General rule: prefer patch when you only need to change a part of a file.

Fast searching over large codebases

search_files runs on ripgrep — pattern searching is far faster than plain grep on large projects, and file writes come with syntax linting so syntax errors are caught at write time.

Notes

• Before writing (write_file/patch) to a sensitive file, the destination path is checked against the denylist (covered in chapter 6.4) — a blocked write returns an error immediately, with no way to override from the chat interface.
• For large multi-file refactors, prefer search_files to determine the blast radius before you start editing — it avoids missing a location that needs changing.
• If the agent reports “done editing” but the file content did not change as expected, check the file-mutation verification footer (when display.file_mutation_verifier is on) — it is more trustworthy than the model’s closing summary of its reply.