modify_file
Edit existing files by describing changes in natural language. Generates a unified diff for approval before writing, with optional direct write and backup safety.
Instructions
Edit an existing file by describing the change in natural language. The local LLM reads the file, applies the edit using SEARCH/REPLACE blocks (with a size-ratio safety net that refuses writes <50% of the original), and returns a unified diff for Claude to approve (review:true, default) or writes directly (review:false). Use for non-trivial edits where the AI does the work. For a known string→string replacement Claude can do itself, use native Edit. For writing a fully-specified content string to a file, use write_files_atomic. For the same instruction across MANY files, use batch_modify. For symbol renames + cross-file reference updates, use refactor. ⚠️ DESTRUCTIVE when review:false: writes directly to filePath. A backup at <path>.backup.<timestamp> is created unless backup:false is also passed (a warning is logged in that case). dryRun:true produces the diff without writing. Returns: shape depends on mode. review (default): {success, status:'pending_review'|'pending_review_truncated', filePath, diff, modifiedContent, summary, stats, warnings, was_truncated, approval_options, retry_attempts}. dryRun: {success, status:'dry_run', filePath, diff, summary, stats, warnings, backend_used, processing_time}. auto-write: {success, status:'written', filePath, diff, summary, stats, backupCreated, backend_used, processing_time, tokens_saved}.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| options | No | ||
| filePath | Yes | Path to the file to modify | |
| instructions | Yes | Natural language edit instructions (e.g., "Add rate limiting to the login function") |