ast-editor

Replace an entire function definition with new content -- signature, body, and decorators.

Use this when: You're rewriting a function top-to-bottom (e.g., renaming it, changing parameters AND implementation together). Don't use this when: You only need to change the body -> use replace_function_body. You only need to change the signature -> use replace_signature.

Example: target="LRUCache.get" content=' def get(self, key, default=None):\n return self.items.get(key, default)'

Replace only the body of a function, preserving its signature and decorators.

Use this when: You're changing the implementation while keeping the interface stable. Don't use this when: You're also changing parameters or return type -> use replace_signature or replace_function.

Example: target="LRUCache.get" content=' if key in self.items:\n return self.items[key]\n return None'

Add a new method at the end of a class body.

Use this when: You're adding a method to an existing class. Don't use this when: You're adding a field/attribute -> use add_field. You're adding a top-level function (not inside a class) -> use add_top_level.

Example: class_target="LRUCache" content=' def clear(self):\n self.items.clear()'

Delete an entire function or class definition, including its decorators.

Use this when: You want to remove a function, method, or class entirely from a source file. Don't use this when: You want to remove a config key -> use delete_key. You want to remove an import -> use remove_import. You want to remove lines inside a function -> no dedicated tool yet; use replace_function_body to rewrite the body without the unwanted lines.

Example: target="LRUCache.old_method" # deletes a method target="DeprecatedClass" # deletes a whole class (and all its methods)

Replace the value of an existing key in a JSON, YAML, or TOML file.

Use this when: A key already exists and you want to update its value. Don't use this when: The key doesn't exist yet -> use add_key. You're modifying an array -> use append_to_array or remove_from_array.

Example: target="project.version" content='"2.0.0"'

Add an import statement to a source file. Skips exact duplicates. Places new imports after existing ones, or at the top of the file if none exist.

Use this when: You need to import something the file does not already reference. Don't use this when: You're adding a single name to an existing multi-name import statement like from X import a, b -> use add_import_name.

Example: import_text="from typing import Optional" # Python import_text="import { readFile } from 'fs';" # JS/TS import_text="#include <stdlib.h>" # C/C++

Remove a matching import statement from a source file. Matching is by stripped text equality -- pass the exact import line you want to remove.

Use this when: You want to remove an unused import. Don't use this when: You want to remove one name from a multi-name import -> use remove_import_name.

Example: import_text="import os"

Add a new key-value pair inside a dict-like container. Works for JSON objects, YAML mappings, TOML tables, AND Python module-level dict literals.

For JSON/YAML/TOML: parent_target is the dotted path to the parent (use "" for root). For Python (.py): parent_target is the module-level variable name (e.g. 'CONFIG'). value should be a literal source expression in the target file's syntax (e.g. JSON '"foo"' or '42'; Python '"foo"' or '42').

Use this when: The key does not exist yet and you want to add it. Don't use this when: The key already exists -> use replace_value. You're adding an item to a list/array -> use append_to_array.

Example (JSON): parent_target="dependencies" key="mcp" value='"^1.2.0"' Example (Python): parent_target="CONFIG" # module-level CONFIG = {...} key='"timeout"' # include quotes if key is a string literal value="30"

Delete a key-value pair from a dict-like container. Works for JSON/YAML/TOML AND Python module-level dict literals. For JSON, also removes the adjacent comma to keep the file valid.

For JSON/YAML/TOML: target is the dotted path to the key (e.g. 'dependencies.mcp'). For Python (.py): target is 'DictName.keyExpr' where keyExpr is the literal key as it appears in source (e.g. 'CONFIG."timeout"').

Use this when: You want to remove an entire dict entry. Don't use this when: You want to remove an item from a list/array -> use remove_from_array.

Example (JSON): target="dependencies.tree-sitter" Example (Python): target='CONFIG."timeout"'

Append a literal value to an array/list. Works for JSON arrays, YAML sequences, TOML arrays, AND Python module-level list literals.

For JSON/YAML/TOML: target is the dotted path to the array. For Python (.py): target is the module-level variable name (e.g. 'ITEMS').

Use this when: You want to add an item to a list (dependencies, keywords, include paths, fixtures, etc.). Don't use this when: You're adding a key-value pair -> use add_key.

Example (TOML): target="project.dependencies" value='"new-package"' Example (Python): target="ITEMS" value='"new-item"'

Remove the first element matching value_match (stripped text equality) from an array/list. Works for JSON/YAML/TOML config arrays AND Python module-level list literals.

For JSON/YAML/TOML: target is the dotted path to the array. For Python (.py): target is the module-level variable name.

Use this when: You want to remove a specific item from a list. Don't use this when: You want to remove a whole key -> use delete_key.

Example (TOML): target="project.dependencies" value_match='"old-package"' Example (Python): target="ITEMS" value_match='"old-item"'

Add a field/attribute/member at the top of a class body (fields-before-methods convention).

Use this when: You're adding a class attribute (Python), class field (JS/TS), or member variable (C++). Don't use this when: You're adding a method -> use add_method.

Example: class_target="LRUCache" content=' version = "1.0"'

Replace only the signature of a function, preserving its body and decorators.

Use this when: You're changing parameters, return type, or function name without modifying the implementation. Don't use this when: You also want to change the body -> use replace_function. You're adding/removing one parameter -> use add_parameter/remove_parameter.

Example: target="LRUCache.get" new_signature=" def get(self, key, default=None):"

Return a formatted outline of all top-level functions, classes, and methods in a source file (Python, JS, TS, C, C++), with line numbers. Read-only.

Use this when: You're about to edit an unfamiliar file and want to see its structure and exact symbol names. ALWAYS a good first call before editing -- avoids guessing at target names. Don't use this when: You already know the exact target name.

Example: file_path="/abs/path/to/module.py"

Return the signature of a function (everything before its body) as plain text. Read-only. Works for Python, JS, TS, C, and C++.

Use this when: You need a function's exact signature for documentation, refactoring, or to verify the interface before editing. Don't use this when: You need to see the whole function body -> read the file directly.

Example: target="LRUCache.get"

Insert content at the top of a function body, preserving existing statements.

Use this when: You're adding one or two lines at the START of a function (logging, input validation, early-return guards, debug prints). Don't use this when: You're replacing the whole body -> use replace_function_body. You're adding to the bottom -> use append_to_body.

Example: target="LRUCache.get" content=" print(f'get called with {key}')"

Insert content at the bottom of a function body, preserving existing statements.

Use this when: You're adding one or two lines at the END of a function (cleanup, telemetry, final return statements, logging after work is done). Don't use this when: You're replacing the whole body -> use replace_function_body. You're adding to the top -> use prepend_to_body.

Example: target="LRUCache.get" content=" # end"

Insert content as a sibling immediately before a named symbol (function, class, method, or top-level assignment).

Use this when: You need precise placement relative to another symbol (e.g. inserting a helper function just before its caller, or a constant above a class that uses it). Don't use this when: You just want to append to the end of the file -> use add_top_level.

Example: target="LRUCache" content="CACHE_SIZE = 100"

Insert content as a sibling immediately after a named symbol (function, class, method, or top-level assignment).

Use this when: You need precise placement right after a symbol (e.g. a helper just after the function that uses it, or a new function between two existing ones). Don't use this when: You just want to append to the end of the file -> use add_top_level.

Example: target="LRUCache" content="RELATED_CONSTANT = 42"

Add a name to an existing Python from <module> import a, b statement. Python-only. Skips duplicates.

Use this when: The module is already imported via from X import ... and you want to add another name to that existing line. Don't use this when: The import statement doesn't exist yet -> use add_import.

Example: module="typing" name="Optional"

Remove a name from a Python from <module> import a, b, c statement. If removing the only remaining name, removes the entire import statement. Python-only.

Use this when: You want to remove a single name from a multi-name import. Don't use this when: You want to remove the entire import line -> use remove_import.

Example: module="typing" name="List"

Add a parameter to a function signature at position 'end' (default) or 'start'. Leaves the body untouched.

Use this when: You need to add one or two parameters without retyping the whole signature. Don't use this when: You need to replace the entire signature -> use replace_signature. You also want to change the body -> use replace_function.

Example: target="LRUCache.get" parameter="default=None" position="end"

Remove a parameter by name from a function signature. Leaves the body untouched.

Use this when: You need to remove one parameter without retyping the whole signature. Don't use this when: You need to replace the whole signature -> use replace_signature.

Example: target="LRUCache.get" parameter_name="default"

Insert comment line(s) immediately before a named symbol. The comment must include its own comment marker (e.g. '# foo' for Python, '// foo' for JS/C/C++).

Use this when: You want to document a function, class, or statement by adding an inline comment above it. Don't use this when: You want a Python function/class docstring -> use replace_docstring. You want to replace an existing leading comment -> use replace_leading_comment.

Example: target="LRUCache.get" comment=" # Retrieve an item by key, returning None if absent"

Remove the contiguous block of comment lines immediately above a named symbol. Stops at the first blank line or non-comment line.

Use this when: You want to delete an outdated or wrong comment above a symbol. Don't use this when: You want to update the comment text -> use replace_leading_comment.

Example: target="LRUCache.get"

Replace the contiguous leading comment block above a named symbol with new_comment. If no leading comment exists, inserts new_comment.

Use this when: You want to update the comment text above a function/class. Don't use this when: You only want to add a comment where none exists -> use add_comment_before.

Example: target="LRUCache.get" new_comment=" # Retrieve an item from the cache"

Replace or insert a Python docstring on a function or class. Python-only. The new_docstring should be a valid Python string literal including its surrounding triple quotes.

Use this when: You want to add or update a Python docstring without touching the function body. Don't use this when: You're editing a # comment above the symbol -> use replace_leading_comment. You're in a non-Python file -> no equivalent tool.

Example: target="LRUCache.get" new_docstring=(triple-quoted string, e.g. with three double-quotes before and after the summary text)

Return all occurrences of an identifier named target in a source file, as 'line N: '. Read-only, syntactic only (no scope awareness), so results may include unrelated identifiers that happen to share the same name.

Use this when: You're about to rename or refactor a symbol and need a quick survey of where it appears in the file. Don't use this when: You need cross-file or scope-aware analysis -> use a full language server.

Example: target="LRUCache"

Append arbitrary top-level content to the end of the file: a function, class, constant, type alias, or any other top-level statement.

Use this when: You're adding any kind of top-level code at the end of a module. Don't use this when: You need placement relative to another symbol -> use insert_before/insert_after. You're adding to a class body -> use add_method/add_field. You're adding a line inside an existing function body -> use prepend_to_body/append_to_body.

Example: content="def parse_version(text):\n return tuple(int(x) for x in text.split('.'))" content="class Logger:\n pass" content="MAX_CONNECTIONS = 10"

Return the full source text of a single named symbol (function, class, method, config key) without reading the entire file. Read-only.

Use this when: You need to see the implementation of ONE specific function or class. Far cheaper than reading the whole file -- typically 10-20x fewer tokens. Don't use this when: You need a structural overview of the file -> use list_symbols. You only need the signature -> use get_signature.

Example: target="LRUCache.get" # returns just the get method's source target="LRUCache" # returns the entire class source target="project.version" # returns the value node for a config key

Return all import statements in a source file as a multi-line string. Read-only.

Use this when: You need to see a file's dependencies without reading the entire file (e.g. before adding a new import, or to understand what a module uses). Don't use this when: You want to add/remove imports -> use add_import / remove_import.

Example: file_path="/abs/path/to/module.py"

Return a stub view of a class: its header, field declarations, and method signatures -- with all method bodies replaced by ' ...'. For a function target, returns just its signature. Read-only.

Use this when: You need to understand a class's public API (what methods and fields it has) without reading every line of implementation. Typically 5-10x fewer tokens than reading the full class. Don't use this when: You need the full implementation -> use read_symbol. You only need one method's signature -> use get_signature.

Example: target="LRUCache" # returns class header + method sigs + fields target="process" # returns function signature (no class)