How the Surgical File Editor Works in Code-Graph-RAG: Precision Code Modification Explained

The surgical file editor in Code-Graph-RAG performs atomic, single-block replacements by validating file paths, locating exact code strings, generating minimal diffs with diff-match-patch, and applying changes only when all patch operations succeed.

The surgical file editor is a low-level utility in the vitali87/code-graph-rag repository that enables AI agents to modify source files with granular precision. Unlike bulk find-and-replace utilities, it targets specific code blocks while preserving surrounding context intact, making it essential for automated refactoring workflows where accuracy is critical.

Core Architecture and Validation Logic

The editor's implementation centers on the FileEditor class in codebase_rag/tools/file_editor.py. Its design prioritizes safety and precision through a four-stage pipeline that ensures only intended modifications occur.

Path Validation and Security Checks

Before any file operation begins, the editor validates the supplied file_path against the project root to prevent directory traversal attacks. According to the source code in FileEditor.replace_code_block, the implementation resolves the path and confirms the target exists within the repository boundary (lines 15-18). If the resolved path escapes the root directory—such as when ../../../etc/passwd is supplied—the editor immediately raises a ValueError (lines 54-56). This sandboxing ensures the tool cannot manipulate files outside the intended codebase.

Block Discovery and Single-Occurrence Matching

Once validation passes, the editor reads the original file contents and performs an exact string search for the target_block. The implementation at lines 22-27 checks for the presence of the target code; if the string is absent, the editor logs an error via the shared logs module and aborts the operation. This strict matching prevents fuzzy replacements that could inadvertently modify the wrong logic.

The Surgical Replacement Process

The actual modification follows a single-occurrence replacement strategy using Python's str.replace(..., 1) method, ensuring only the first instance of the target block is modified even if duplicates exist elsewhere in the file.

Generating Atomic Patches with diff-match-patch

At lines 30-46, the editor leverages the diff-match-patch library to create surgical modifications. The process unfolds as follows:

1. Diff Generation: The editor creates a patch object using self.dmp.patch_make(original_text, modified_text)
2. Application: It applies the patch via self.dmp.patch_apply() to verify the operation succeeds
3. Validation: The editor checks that all patch operations succeed before proceeding to write

If the target code block appears multiple times in the file, the editor emits a warning but proceeds with the single-occurrence replacement (lines 30-46). The use of diff-match-patch ensures minimal changes to the file, preserving whitespace, comments, and formatting outside the target block.

Atomic Write Operations and Concurrency Safety

The editor respects a global async write lock (self._write_lock) that prevents race conditions during concurrent modifications. This locking mechanism guarantees that simultaneous edit requests from multiple agents cannot corrupt file contents. Only after the lock is acquired and the patch is verified does the editor write the modified text back to disk (lines 41-48).

MCP Integration and Tool Registration

The surgical editor integrates with the Multiple-Code-Planner (MCP) architecture as an agentic tool, exposing its capabilities to higher-level planning agents.

Exposing replace_code_block as an Agentic Tool

In codebase_rag/tools/file_editor.py, the function create_file_editor_tool wraps the low-level FileEditor class into a callable tool interface:

def create_file_editor_tool(file_editor: FileEditor) -> Tool:
    async def replace_code_surgically(file_path, target_code, replacement_code):
        success = file_editor.replace_code_block(file_path, target_code, replacement_code)
        if success:
            return cs.MSG_SURGICAL_SUCCESS.format(path=file_path)
        return cs.MSG_SURGICAL_FAILED.format(path=file_path)

This wrapper converts the boolean result from replace_code_block into human-readable status messages defined in codebase_rag/constants/mcp.py.

Registry Binding in MCPToolsRegistry

The resulting Tool object is registered in MCPToolsRegistry under the constant name SURGICAL_REPLACE_CODE (defined in codebase_rag/constants/mcp.py). The registration occurs in codebase_rag/mcp/tools.py, where the MCP delegates surgical replacement calls to the FileEditor.replace_code_block method. When a planner agent invokes surgical_replace_code, the MCP returns structured success or failure messages based on the editor's execution.

Practical Implementation Examples

Direct FileEditor Usage

For standalone scripts or testing, import the FileEditor class directly:

from codebase_rag.tools.file_editor import FileEditor

fe = FileEditor(project_root="my_project")
target = """def foo():\n    return 1"""
replacement = """def foo():\n    return 42"""

ok = fe.replace_code_block(
    file_path="src/example.py",
    target_block=target,
    replacement_block=replacement,
)

print("✅ Surgical replace succeeded" if ok else "❌ Replace failed")

MCP Tool Invocation

When operating within the agentic framework, use the registry interface:

from codebase_rag.mcp.tools import create_mcp_tools_registry
from codebase_rag.ingestor import MemgraphIngestor
from codebase_rag.cypher_generator import CypherGenerator

registry = create_mcp_tools_registry(
    project_root="my_project",
    ingestor=MemgraphIngestor(),
    cypher_gen=CypherGenerator(),
)

result_msg = await registry.surgical_replace_code(
    file_path="src/example.py",
    target_code=target,
    replacement_code=replacement,
)

print(result_msg)

Error Handling

The editor raises ValueError for path traversal attempts and logs errors for missing target blocks:

try:
    await registry.surgical_replace_code("outside/evil.py", "...", "...")
except ValueError as exc:
    print(f"Security violation: {exc}")

Summary

• The surgical file editor resides in codebase_rag/tools/file_editor.py and provides atomic code block replacement through the FileEditor.replace_code_block method.
• Security validation prevents directory traversal by resolving paths against the project root and raising ValueError for escapes (lines 15-18, 54-56).
• Precision matching uses exact string comparison to locate target blocks, with str.replace(..., 1) ensuring single-occurrence replacement (lines 22-27, 30-46).
• Diff generation employs the diff-match-patch library to create minimal patches, applying changes only when all patch operations succeed.
• Concurrency protection uses self._write_lock to serialize file writes and prevent corruption during simultaneous access.
• MCP integration exposes the functionality as surgical_replace_code via codebase_rag/mcp/tools.py, returning human-readable status messages.

Frequently Asked Questions

How does the surgical file editor prevent partial file corruption?

The editor uses a two-phase commit strategy. First, it generates a patch using self.dmp.patch_make() and applies it in-memory with self.dmp.patch_apply(). According to the implementation in codebase_rag/tools/file_editor.py (lines 41-48), the editor only writes to disk if all patch operations return success. This ensures that malformed replacements or encoding issues never result in partially written files.

What happens if the target code block appears multiple times in a file?

When duplicate instances exist, the editor emits a warning via the logging system but proceeds with the replacement. The str.replace(..., 1) call at line 30 guarantees that only the first occurrence is modified. This behavior prevents accidental bulk modifications while alerting developers to potential ambiguity in the target specification.

Can the surgical file editor handle concurrent modification requests?

Yes, the editor implements an async write lock (self._write_lock) that serializes access to the file system. As implemented in the FileEditor class, concurrent calls to replace_code_block wait for the lock to release before proceeding with read-modify-write cycles. This mechanism eliminates race conditions when multiple agents attempt simultaneous edits.

How does the MCP layer expose the surgical editor to AI agents?

The create_file_editor_tool function in codebase_rag/tools/file_editor.py wraps the core logic into a Tool object registered as surgical_replace_code in codebase_rag/mcp/tools.py. When the Multiple-Code-Planner invokes this tool, the MCP delegates to FileEditor.replace_code_block and returns formatted success or failure messages defined in codebase_rag/constants/mcp.py, creating a clean abstraction between low-level file operations and high-level planning agents.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}