chunked-edit

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:

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