Edit Tool

Script: powers/edit.py Dependencies: pydantic

Surgical file editing using search-and-replace, line insertions, range replacements, batch edits, and regex patterns -- without requiring the agent to rewrite entire files.

edit_replace

Replace exact text in a file. The old_text must match precisely, including whitespace and indentation.

Input

Output

Examples

// Replace a variable assignment
{"file": "main.py", "old_text": "x = 1", "new_text": "x = 2"}

// Replace a config value
{"file": "config.json", "old_text": "\"debug\": false", "new_text": "\"debug\": true"}

// Replace all occurrences
{"file": "main.py", "old_text": "old_name", "new_text": "new_name", "count": 0}

Notes

• Always read the file first to find the exact text to replace
• The match is exact -- whitespace, indentation, and newlines must match precisely
• Returns an error if old_text is not found in the file

insert_lines

Insert text at a specific line number in a file.

Input

Output

Examples

// Add imports at the top
{"file": "main.py", "line_number": 1, "text": "import os\nimport sys"}

// Append to the end
{"file": "main.py", "line_number": -1, "text": "# End of file"}

// Insert at the very beginning (before line 1)
{"file": "main.py", "line_number": 0, "text": "#!/usr/bin/env python3"}

Notes

• line_number: 0 prepends at the start of the file
• line_number: -1 appends at the end of the file
• A trailing newline is automatically added if missing

replace_lines

Replace a range of lines in a file with new text. The replacement can be more or fewer lines than the original range.

Input

Output

Examples

// Replace lines 5-10 with a single comment
{"file": "main.py", "start_line": 5, "end_line": 10, "new_text": "# replaced block"}

// Replace a function definition (lines 20-35) with a new implementation
{
  "file": "main.py",
  "start_line": 20,
  "end_line": 35,
  "new_text": "def process(data):\n    return data.strip().lower()"
}

Notes

• Read the file first to identify the exact line range
• Line numbers are 1-based and inclusive on both ends
• The replacement text can span any number of lines

multi_edit

Apply multiple search-and-replace edits to a single file in one operation. Edits are applied sequentially.

Input

Each edit in the list:

Output

Examples

// Multiple edits in one call
{
  "file": "main.py",
  "edits": [
    {"old_text": "import os", "new_text": "import os\nimport sys"},
    {"old_text": "x = 1", "new_text": "x = 42"},
    {"old_text": "DEBUG = False", "new_text": "DEBUG = True"}
  ]
}

Notes

• Edits are applied sequentially -- each edit sees the result of the previous one
• If an edit fails (old_text not found), it is skipped and reported in failed, but remaining edits still proceed
• The file is only written if at least one edit was applied

regex_replace

Replace text in a file using a regular expression pattern. Supports capture groups.

Input

Output

Examples

// Add self parameter to all methods
{"file": "main.py", "pattern": "def (\\w+)\\(\\):", "replacement": "def \\1(self):"}

// Update version string
{"file": "config.py", "pattern": "VERSION = \"[^\"]+\"", "replacement": "VERSION = \"2.0.0\""}

// Replace first occurrence only
{"file": "main.py", "pattern": "TODO.*$", "replacement": "DONE", "count": 1}

Notes

• Uses Python re module syntax
• Returns an error if the regex pattern is invalid
• Returns an error if the pattern is not found in the file
• Capture groups use \1, \2, etc. in the replacement string

Tips

• Prefer edit_replace over write_file when making small changes -- it's safer because it only changes what you specify
• Always read the file first to find exact text for replacement
• Use multi_edit when you need to make several changes to the same file -- it's more efficient than multiple edit_replace calls
• Use regex_replace for pattern-based changes like renaming variables, updating version strings, or fixing formatting
• Use replace_lines when you know the exact line range to change (pair with read_file line numbers)