chunked-edit

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:

1. Plan edit boundaries - identify natural split points (between functions, blocks, sections)
2. Edit top-down - start from the top of the file and work downward, so line numbers don't shift for upcoming edits
3. One batch per Edit call - each call handles one cohesive chunk (~50-100 lines)
4. 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