| name | chunked-edit |
| description | Use when editing a long file (100+ lines of changes) or when an Edit call freezes, times out, or silently fails - requires splitting large edits into multiple smaller sequential Edit calls |
Chunked Edit
Split large edits into small sequential batches to avoid freezing.
The Problem
The Edit tool can freeze or timeout when applying large changes to a long file in a single call. This is a known platform bug.
Symptoms: Edit call hangs, connection reset, repeated silent failures, or the tool never returns.
The Rule
Never edit more than ~50-100 lines in a single Edit call. Each call should stay under ~1000 tokens.
When you need to make large changes to a file:
- Plan edit boundaries - identify natural split points (between functions, blocks, sections)
- Edit top-down - start from the top of the file and work downward, so line numbers don't shift for upcoming edits
- One batch per Edit call - each call handles one cohesive chunk (~50-100 lines)
- Wait for confirmation - ensure each Edit succeeds before the next
When This Applies
- Refactoring or rewriting a large portion of a file
- Adding/replacing 100+ lines of code in one file
- Any time a previous Edit call froze or timed out
- Generating or regenerating long files
When This Does NOT Apply
- Small edits (under 50 lines) - just edit normally
- Creating new files with Write - use the chunked Write approach from CLAUDE.md instead
Quick Reference
| Scenario | Approach |
|---|
| Change < 50 lines | Single Edit, no splitting needed |
| Change 50-100 lines | Single Edit is OK, split if it fails |
| Change 100-300 lines | Split into 2-4 Edit calls |
| Change 300+ lines | Split into many calls, ~50-100 lines each |
| Edit freezes | Retry with a smaller chunk |
Red Flags
- You're about to paste 200+ lines into
new_string - STOP, split it
- An Edit just timed out - split the remaining work into smaller chunks
- You're rewriting most of a file - consider multiple targeted edits instead of one giant replacement
