1Makes multiple edits to a single file in one operation. Built on Edit tool for efficient multiple find-and-replace operations. Prefer over Edit tool for multiple edits to same file.
  2
  3<prerequisites>
  41. Use View tool to understand file contents and context
  52. Verify directory path is correct
  63. CRITICAL: Note exact whitespace, indentation, and formatting from View output
  7</prerequisites>
  8
  9<parameters>
 101. file_path: Absolute path to file (required)
 112. edits: Array of edit operations, each containing:
 12   - old_string: Text to replace (must match exactly including whitespace/indentation)
 13   - new_string: Replacement text
 14   - replace_all: Replace all occurrences (optional, defaults to false)
 15</parameters>
 16
 17<operation>
 18- Edits applied sequentially in provided order.
 19- Each edit operates on result of previous edit.
 20- PARTIAL SUCCESS: If some edits fail, successful edits are still applied. Failed edits are returned in the response.
 21- File is modified if at least one edit succeeds.
 22- Ideal for several changes to different parts of same file.
 23</operation>
 24
 25<inherited_rules>
 26All instructions from the Edit tool documentation apply verbatim to every edit item:
 27- Critical requirements for exact matching and uniqueness
 28- Warnings and common failures (tabs vs spaces, blank lines, brace placement, etc.)
 29- Verification steps before using, recovery steps, best practices, and whitespace checklist
 30Use the same level of precision as Edit. Multiedit often fails due to formatting mismatches—double-check whitespace for every edit.
 31</inherited_rules>
 32
 33<critical_requirements>
 341. Apply Edit tool rules to EACH edit (see edit.md).
 352. Edits are applied in order; successful edits are kept even if later edits fail.
 363. Plan sequence carefully: earlier edits change the file content that later edits must match.
 374. Ensure each old_string is unique at its application time (after prior edits).
 385. Check the response for failed edits and retry them if needed.
 39</critical_requirements>
 40
 41<verification_before_using>
 421. View the file and copy exact text (including whitespace) for each target.
 432. Check how many instances each old_string has BEFORE the sequence starts.
 443. Dry-run mentally: after applying edit #N, will edit #N+1 still match? Adjust old_string/new_string accordingly.
 454. Prefer fewer, larger context blocks over many tiny fragments that are easy to misalign.
 465. If edits are independent, consider separate multiedit batches per logical region.
 47</verification_before_using>
 48
 49<warnings>
 50- Operation continues even if some edits fail; check response for failed edits.
 51- Earlier edits can invalidate later matches (added/removed spaces, lines, or reordered text).
 52- Mixed tabs/spaces, trailing spaces, or missing blank lines commonly cause failures.
 53- replace_all may affect unintended regions—use carefully or provide more context.
 54</warnings>
 55
 56<recovery_steps>
 57If some edits fail:
 581. Check the response metadata for the list of failed edits with their error messages.
 592. View the file again to see the current state after successful edits.
 603. Adjust the failed edits based on the new file content.
 614. Retry the failed edits with corrected old_string values.
 625. Consider breaking complex batches into smaller, independent operations.
 63</recovery_steps>
 64
 65<best_practices>
 66- Ensure all edits result in correct, idiomatic code; don't leave code broken.
 67- Use absolute file paths (starting with /).
 68- Use replace_all only when you're certain; otherwise provide unique context.
 69- Match existing style exactly (spaces, tabs, blank lines).
 70- Review failed edits in the response and retry with corrections.
 71</best_practices>
 72
 73<whitespace_checklist>
 74For EACH edit, verify:
 75- [ ] Viewed the file first
 76- [ ] Counted indentation spaces/tabs
 77- [ ] Included blank lines if present
 78- [ ] Matched brace/bracket positioning
 79- [ ] Included 3–5 lines of surrounding context
 80- [ ] Verified text appears exactly once (or using replace_all deliberately)
 81- [ ] Copied text character-for-character, not approximated
 82</whitespace_checklist>
 83
 84<examples>
 85✅ Correct: Sequential edits where the second match accounts for the first change
 86
 87```
 88edits: [
 89  {
 90    old_string: "func A() {\n    doOld()\n}",
 91    new_string: "func A() {\n    doNew()\n}",
 92  },
 93  {
 94    // Uses context that still exists AFTER the first replacement
 95    old_string: "func B() {\n    callA()\n}",
 96    new_string: "func B() {\n    callA()\n    logChange()\n}",
 97  },
 98]
 99```
100
101❌ Incorrect: Second old_string no longer matches due to whitespace change introduced by the first edit
102
103```
104edits: [
105  {
106    old_string: "func A() {\n    doOld()\n}",
107    new_string: "func A() {\n\n    doNew()\n}", // Added extra blank line
108  },
109  {
110    old_string: "func A() {\n    doNew()\n}", // Missing the new blank line, will FAIL
111    new_string: "func A() {\n    doNew()\n    logChange()\n}",
112  },
113]
114```
115
116✅ Correct: Handling partial success
117
118```
119// If edit 2 fails, edit 1 is still applied
120// Response will indicate:
121// - edits_applied: 1
122// - edits_failed: [{index: 2, error: "...", edit: {...}}]
123// You can then retry edit 2 with corrected context
124```
125</examples>