Code Surgery: How AI Assistants Make Precise Edits to Your Files

Applying code changes generated by AI assistants directly to files is a core capability, yet it often proves surprisingly difficult. An assistant might propose a valid code modification, but fail when attempting to integrate it, reporting errors like “Cannot find matching context” and requiring manual intervention.

Many developers using AI coding assistants encounter this. While the AI understands the code’s intent, translating that understanding into precise, automated file modifications presents significant technical challenges.

Why Precise File Editing Matters

Effective file editing is central to the value proposition of coding assistants. If these tools cannot reliably modify code files, their utility diminishes, reducing them to suggestion engines that require manual implementation. An assistant capable of dependable automated editing saves developers considerable time and cognitive load compared to one prone to failures.

The fundamental challenge lies in the indirect nature of the operation: Large Language Models (LLMs) lack direct file system access. They must describe intended changes via specialized tools or APIs, which then interpret these instructions and attempt execution. This handoff between the LLM’s representation and the file system state is a frequent source of complications.

Users of tools like GitHub Copilot, Aider, or RooCode may have observed these struggles: edits failing to locate the correct insertion point, incorrect indentation, or the tool ultimately requesting manual application.

What You Will Learn

This post examines the file editing mechanisms of several coding assistant systems: Codex, Aider, OpenHands, RooCode, and Cursor. For the open-source systems (Codex, Aider, OpenHands, RooCode), the insights presented here are derived from analyzing their respective codebases. For Cursor, which is closed-source, the insights come from public discussions and interviews with their team. We will explore their approaches, presented roughly in order of increasing complexity, while noting that their development involved parallel evolution and mutual influence.

For each system, we will analyze:

1. How it receives edit instructions from the AI.
2. How it interprets and processes these instructions.
3. How it applies the changes to files.
4. How it handles errors and edge cases.
5. How it provides feedback on the outcome.

Understanding these mechanisms provides insight into the difficulties of automated code editing and the increasingly sophisticated solutions different systems employ.

Key Concepts in AI Code Editing

Before proceeding, let’s define some terms frequently used in this domain:

• Patch: A formal specification of changes (additions, deletions) for a file, often including metadata like file paths and context for application.
• Diff: A format highlighting line-by-line differences between text versions, typically using + and - indicators, focusing on content changes.
• Search/Replace Block: An editing instruction format using delimiters (e.g., <<<<<<< SEARCH, >>>>>>> REPLACE) to explicitly define text to find and its replacement.
• Context Lines: Unmodified lines included in patches or diffs surrounding changes, used to accurately locate the modification point.
• Hunk: A contiguous block of changes within a patch or diff, comprising context lines and modifications.
• Fuzzy Matching: Algorithms (e.g., using Levenshtein distance) to find approximate matches for text strings, handling minor variations.
• Indentation Preservation: Maintaining consistent whitespace prefixes (spaces, tabs) during file edits, critical for syntax and readability.
• Fence: Delimiters (e.g., triple backticks ```) clearly marking the boundaries of code blocks in text or instructions.

The File Editing Workflow

Most AI code editing systems follow a general workflow:

LLM (generates change description) → Tool (interprets & applies) → File System (state change) → Feedback (Tool reports outcome) → LLM (processes feedback)

While straightforward conceptually, several challenges arise in practice:

Challenge 1: Locating the Edit Target

The LLM often operates on a potentially outdated or incomplete view of the target file. Accurately finding the intended edit location becomes difficult when:

• The file has been modified since the LLM last accessed it.
• The file contains multiple similar code sections.
• The file exceeds the LLM’s context window capacity.

Context mismatches are common when the file state diverges. Robust systems provide detailed error feedback, enabling the LLM to adapt. Some may provide the current file state upon error.

Challenge 2: Handling Multi-File Changes

Code modifications frequently span multiple files, introducing complexities:

• Ensuring consistency across related edits.
• Managing dependencies between files.
• Applying changes in the correct sequence.

Most systems address this by processing edits sequentially, file by file.

Challenge 3: Maintaining Code Style

Developers require adherence to specific formatting conventions. Automated edits must preserve:

• Indentation style (tabs vs. spaces, width).
• Line ending conventions.
• Comment formatting.
• Consistent spacing patterns.

Challenge 4: Managing Failures

A robust editing system should handle failures gracefully:

• Provide clear explanations for the failure.
• Offer diagnostic information to aid correction.
• Potentially attempt alternative strategies upon initial failure.

Common Edit Description Formats

AI systems use various formats to communicate intended changes:

1. Patches: Detailed add/delete instructions, often based on standard patch formats.
2. Diffs: Showing differences between original and desired states.
3. Search/Replace Blocks: Explicitly defining find/replace operations.
4. Line Operations: Specifying edits by line number (less common due to fragility).
5. AI-Assisted Application: Employing a secondary AI model specifically for applying complex changes.

Let’s examine how specific systems implement these concepts.

Codex: A Straightforward Patch-Based System

OpenAI’s Codex CLI utilizes a relatively simple, structured patch format. Its effectiveness stems partly from OpenAI’s ability to train its models specifically to generate this format reliably.

The Codex Patch Format

The LLM communicates changes using this structure:

*** Begin Patch
*** [Operation] File: [filepath]
@@ [text matching a line near the change]
  [context line (unchanged, starts with space)]
- [line to remove (starts with -)]
+ [line to add (starts with +)]
  [another context line]
*** End Patch

Key features:

• Operation: Add File, Update File, or Delete File.
• @@: Followed by text content from a line near the edit (e.g., function/class definition) used for locating the change. Crucially, this avoids direct reliance on line numbers.
• Context lines (start with space ` `): Must match existing file content and remain unchanged; used for precise anchoring.
• - prefixed lines: Marked for deletion.
• + prefixed lines: Marked for addition.

Consider this example modifying a print statement:

*** Begin Patch
*** Update File: main.py
@@ def main():
   # This is the main function
-  print("hello")
+  print("hello world!")
   return None
*** End Patch

Here, @@ def main(): helps locate the function, while the space-prefixed context lines (# This is..., return None) pinpoint the exact edit location.

The system attempts to match the @@ line and context lines exactly. If this fails, it employs fallback strategies: first matching with trimmed line endings, then matching with all whitespace trimmed. This flexibility accommodates minor discrepancies between the LLM’s view and the actual file. A single patch can contain multiple @@ sections to target different parts of a file.

Patch Parsing and Application

Upon receiving a patch via the apply_patch tool, the system performs these steps:

1. Validates the basic patch structure (*** Begin Patch / *** End Patch).
2. Identifies the target file(s).
3. Loads the current content of the target file(s).
4. Parses the patch into discrete operations (create, update sections, delete).
5. Attempts to apply the changes to the loaded file content.

Fuzzy Matching for Robustness

The progressive matching strategy for context lines enhances robustness:

1. Attempt exact match.
2. If failed, attempt match ignoring line endings.
3. If failed, attempt match ignoring all whitespace.

This helps overcome small variations between the expected and actual file content.

Error Handling and Feedback Mechanisms

Codex provides structured JSON feedback upon failure, aiding the LLM’s correction attempts:

Context Line Mismatch:

{
  "exit_code": 1,
  "stderr": "Error: context line 3, \"  const response = await fetch(`/api/users/${userId}`);\" does not match \"  const response = await fetch(`/api/users/${userId}`, { headers });\""
}

(Clearly indicates the mismatch and the differing lines.)

File Not Found:

{
  "exit_code": 1,
  "stderr": "Error: File not found: src/api.js"
}

(Unambiguous file access error.)

Invalid Patch Format:

{
  "exit_code": 1,
  "stderr": "Error: Patch must start with *** Begin Patch"
}

(Specific format violation feedback.)

This detailed, structured feedback allows the LLM to diagnose the failure and potentially retry with a corrected approach (e.g., re-fetching the file or adjusting the patch context).

Example: Real-World Edit Scenario

Let’s examine how Codex handles a real-world edit scenario. Imagine we need to add error handling to a function that fetches user data:

Original code in src/api.js:

async function fetchUserData(userId) {
  const response = await fetch(`/api/users/${userId}`);
  const data = await response.json();
  return data;
}

LLM generates a patch:

*** Begin Patch
*** Update File: src/api.js
@@ async function fetchUserData(userId) {
-  const response = await fetch(`/api/users/${userId}`);
-  const data = await response.json();
-  return data;
+  try {
+    const response = await fetch(`/api/users/${userId}`);
+    if (!response.ok) {
+      throw new Error(`Failed to fetch user data: ${response.status}`);
+    }
+    const data = await response.json();
+    return data;
+  } catch (error) {
+    console.error(`Error fetching user ${userId}:`, error);
+    throw error;
+  }
 }

@@ function formatUserData(data) {
-  return data;
+  return {
+    id: data.id,
+    name: data.name,
+    email: data.email,
+    formattedDate: new Date(data.createdAt).toLocaleDateString()
+  };
 }
*** End Patch

This example shows a patch that modifies two different functions in the same file, each with its own @@ context marker.

OpenAI’s Patch Format Standardization

With the release of GPT-4.1 (April 2025), OpenAI published a “prompt cookbook” detailing this recommended patch format and a reference implementation (apply_patch.py). They indicated significant training effort for GPT-4.1 on this format, contributing to its effective use within the Codex CLI ecosystem.

OpenAI’s commentary highlighted that successful formats often avoid line numbers and clearly provide both the code to be replaced and its replacement, using distinct delimiters. This suggests core principles for reliable AI-driven editing. OpenAI’s ability to co-develop the LLM and the editing tool allows for tight integration and optimization.

Aider: A Multi-Format Editing System

Aider employs a more flexible approach, supporting multiple edit formats. It can select the format best suited to the task or the specific LLM being used.

Pluggable Edit Format Architecture

Aider uses a system of “coder” classes, each responsible for handling a specific edit format:

class Coder:
    # ... attributes like edit_format identifier ...

    def get_edits(self): # Parses AI response into edit operations
        raise NotImplementedError

    def apply_edits(self, edits): # Applies parsed edits to files
        raise NotImplementedError

This modular design allows for easy extension and selection of different editing strategies.

Supported Edit Formats in Aider

Aider supports several formats, choosing based on the model or user configuration (--edit-format):

1. EditBlock Format (Search/Replace): Intuitive format clearly showing search/replace blocks.

   file.py
   <<<<<<< SEARCH
   # Code block to find
   =======
   # Code block to replace with
   >>>>>>> REPLACE
   

2. Unified Diff Format (udiff): Standard diff format (diff -U0 style), suitable for complex changes.

   --- file.py
   +++ file.py
   @@ -10,7 +10,7 @@
    def some_function():
   -    return "old value"
   +    return "new value"
   

3. OpenAI Patch Format: Aider implemented OpenAI’s reference format, leveraging GPT-4.1’s training on this syntax.

   *** Begin Patch
   *** Update File: file.py
   @@ class MyClass:
       def some_function():
   -        return "old"
   +        return "new"
   *** End Patch
   

4. Additional Formats:

   • whole: LLM returns the complete modified file content. Simple but potentially inefficient for large files.
   • diff-fenced: Diff format variant where the filename is inside the code fence (```), used with models like Gemini.
   • editor-diff / editor-whole: Streamlined versions for specific internal modes.

Flexible Search Strategies

When applying Search/Replace blocks, Aider attempts multiple matching strategies sequentially:

1. Exact match.
2. Whitespace-insensitive match.
3. Indentation-preserving match.
4. Fuzzy match using difflib.

This layered approach increases the likelihood of successfully applying edits even with minor imperfections in the SEARCH block.

Detailed Error Reporting

Aider excels at providing highly informative feedback when edits fail:

# 1 SEARCH/REPLACE block failed to match!

## SearchReplaceNoExactMatch: This SEARCH block failed to exactly match lines in src/api.js
<<<<<<< SEARCH
async function fetchUserData(userId) {
  const response = await fetch(`/api/users/${userId}`);
  const data = await response.json();
  return data;
}
=======
...
>>>>>>> REPLACE

Did you mean to match some of these actual lines from src/api.js?


async function fetchUserData(userId) {
    const response = await fetch(`/api/users/${userId}`);
    // Some comment here
    const data = await response.json();
    return data;
}

The SEARCH section must exactly match an existing block of lines including all white space, comments, indentation, docstrings, etc

# The other X SEARCH/REPLACE blocks were applied successfully.
Don't re-send them.
Just reply with fixed versions of the blocks above that failed to match.

This feedback is significantly more detailed than simple failure messages. It explains the mismatch, suggests potential correct targets, reiterates the matching rules, and instructs the AI on how to proceed (only resend failed blocks). This detailed guidance greatly improves the AI’s ability to correct its edits.

While adopting OpenAI’s format, Aider enhances it with greater flexibility and substantially more informative error handling.

OpenHands: Blending Traditional and AI-Assisted Editing

OpenHands primarily relies on traditional edit application methods while also incorporating an optional LLM-based editing capability.

Traditional Edit Application

OpenHands primarily uses traditional editing approaches. It has built-in support for detecting different patch formats – including unified diffs, git diffs, context diffs, ed scripts, and RCS ed scripts – using regular expression patterns. Based on the detected format, it applies the appropriate parsing and application logic. The system supports several traditional editing methods:

1. String replacement.
2. Line-based operations (by number).
3. Standard patch application utilities.

It includes features like whitespace normalization to handle variations in patch indentation.

Optional LLM-Based Editing Feature

OpenHands allows configuring a separate “draft editor” LLM for a distinct editing workflow:

1. Target Identification: The primary LLM specifies the target line range for the edit.
2. Content Extraction: The tool extracts this specific code section.
3. LLM Rewrite: The extracted section and a description of the desired change are sent to the specialized “draft editor” LLM. This editor LLM can have different configurations (model, temperature) optimized for editing.
4. File Reconstruction: The tool receives the modified section from the editor LLM and integrates it back into the file, replacing the original lines.

To ensure the draft editor LLM produces the correct output for integration, it is given a specific system prompt instructing it to:

• Produce a complete and accurate version of the modified code section.
• Replace any placeholder comments (like # no changes needed before this line) with the actual, unchanged code from the original section if parts were meant to be preserved.
• Ensure correct and consistent indentation is maintained throughout the block.
• Output the final, complete edited content precisely wrapped in a designated code block format for easy parsing by the tool.

Potential benefits of a separate editor LLM:

• Task-Specific Tuning: Optimize parameters specifically for code modification.
• Model Flexibility: Use different models for reasoning vs. editing.
• Focused Prompting: Provide the editor LLM with a narrow, edit-specific prompt.

The reconstruction process carefully combines the content before the edit, the LLM-edited block, and the content after the edit. Optional validation steps like linting can be performed.

This LLM-based editing appears to be an optional, potentially experimental feature within OpenHands, often disabled by default.

RooCode: Advanced Search and Format Preservation

RooCode utilizes the search/replace block format. Its strengths lie in its advanced search algorithm for locating the target block and its meticulous handling of code formatting during replacement.

Advanced Search Strategy: Middle-Out Fuzzy Matching

When an exact match for the search block fails, RooCode employs a ‘middle-out’ fuzzy matching approach via its MultiSearchReplaceDiffStrategy:

1. Estimate Region: Start searching near the expected location (potentially hinted by line numbers).
2. Expand Search: Search outwards from this central point.
3. Score Similarity: Use algorithms like Levenshtein distance to score the similarity between the search block and potential matches in the file.
4. Select Best Match: Choose the highest-scoring match that exceeds a defined threshold.

This strategy is effective for large files or when line numbers are slightly inaccurate, providing robustness against minor context shifts.

Emphasis on Indentation Preservation

Incorrect indentation is a common frustration with automated edits. RooCode implements a sophisticated system to preserve formatting:

1. Capture Original Indentation: Record the exact leading whitespace (spaces/tabs) of the matched lines in the original file.
2. Analyze Relative Indentation: Calculate the indentation of each line within the replacement block relative to its first line or surrounding block.
3. Apply Original Style with Relative Structure: Re-apply the captured original indentation style while maintaining the calculated relative indentation structure of the replacement code.

This detailed attention to indentation is crucial for code readability and syntactic correctness (especially in languages like Python).

RooCode Edit Process Example

<<<<<<< SEARCH
:start_line:10
-------
function calculateTotal(items) {
  return items.reduce((sum, item) => sum + item, 0);
}
=======
function calculateTotal(items) {
  // Add 10% tax
  return items.reduce((sum, item) => sum + (item * 1.1), 0);
}
>>>>>>> REPLACE

1. RooCode parses the diff:

   • Extracts the start line (10)
   • Extracts the search block (function calculateTotal...)
   • Extracts the replace block (function calculateTotal...)

2. RooCode applies the diff:

   • Reads the current content of the file
   • Uses fuzzy matching to find the best match for the search block
   • Applies the replacement with proper indentation preservation
   • Shows a diff view for user approval
   • Applies the changes if approved

3. Feedback to LLM:

   • If successful: “Changes successfully applied to file”
   • If failed: Detailed error message with the reason for failure

RooCode combines robust fuzzy matching with a strong focus on maintaining code formatting integrity.

Cursor: Specialized AI for Change Application

While other systems refine edit formats or matching algorithms, Cursor introduces a dedicated AI model specifically for the application step of the edit process.

This directly addresses the observation that even powerful LLMs, skilled at code generation and reasoning, may struggle to produce perfectly formatted, precisely located diffs that apply cleanly via simple algorithms, particularly in complex files.

Cursor’s approach involves a two-step AI process:

1. Sketching: A primary, powerful LLM generates the intended change, focusing on the core logic rather than perfect diff syntax. This might be a code block or a rough description.
2. Applying: A separate, custom-trained “Apply” model receives this sketch. This specialized model is trained to intelligently integrate the sketch into the existing codebase, handling nuances of context, structure, and potential imperfections in the input sketch. It performs more than simple text matching; it aims for intelligent code integration.

This strategy separates high-level change generation from the detailed mechanics of application. The primary LLM focuses on what to change, while the specialized Apply model focuses on how to integrate that change robustly and accurately into the file system.

You can hear the Cursor team discuss this approach:

Evolution and Convergence of Edit Formats

Examining these systems reveals interesting patterns in format development:

1. Search/Replace Lineage: Aider’s EditBlock format (<<<<<<</>>>>>>>) established an intuitive approach later adopted by Cline, which RooCode then built upon.
2. OpenAI’s Patch Influence: The specific patch format released with GPT-4.1 gained traction due to focused model training. Used natively by Codex, it was also adopted as an option by Aider.
3. Underlying Principles: Despite different origins, successful formats converge on key ideas noted by OpenAI: avoiding line numbers and clearly delimiting the original and replacement code. These features appear fundamental for reliable AI-driven editing.

Conclusion and Key Learnings

Investigating how AI coding assistants edit files reveals complex processes involving sophisticated techniques and evolving strategies.

Key Learnings:

1. Format Matters: Formats avoiding line numbers and clearly separating before/after code (like OpenAI’s patch or search/replace blocks) are prevalent and effective, especially when models are trained on them.
2. Robust Matching is Essential: Successful systems employ layered matching strategies (exact, then increasingly fuzzy) to balance precision with the ability to handle minor discrepancies.
3. Indentation Integrity is Crucial: Careful preservation of whitespace and indentation (as emphasized by RooCode) is vital for code correctness and developer acceptance.
4. Informative Feedback Enables Correction: Detailed error messages (like Aider’s) are critical for enabling the AI (or user) to diagnose and fix failed edits effectively.
5. Specialization Shows Promise: Using dedicated AI models for specific sub-tasks like change application (Cursor) represents an advanced approach to improving reliability.

Considerations for Tool Builders

Developing robust AI editing tools involves several considerations:

1. Implement Layered Matching: Start with strict matching and add fallback fuzzy strategies.
2. Prioritize Indentation Preservation: Invest effort in accurately maintaining formatting.
3. Design Actionable Error Feedback: Provide specific, informative error messages.
4. Leverage Existing Formats and Implementations: Consider established formats and study open-source systems (Aider, OpenHands, RooCode/Cline).