Edit size

File size

vs whole-file rewrite

vs unified diff

vs search/replace

1-line tweak

100 LoC

3–5x

~1.5x

~1.5x

Function body rewrite

500 LoC

8–12x

2–3x

2–3x

Function body rewrite

4,000 LoC

15–20x

3–5x

3–5x

Add 2 lines to a function

any size

~20x (via insert_in_body(at="top") / insert_in_body(at="bottom"))

5–10x

3–5x

Read task

File size

AST reader tool

vs full file read

One function's source

500 LoC

read_symbol

~20x fewer tokens

One function's source

2,000 LoC

read_symbol

~50-100x fewer tokens

Class API (10 methods, no bodies)

500 LoC

read_symbol(depth="interface")

~10x fewer tokens

Import block only

any size

read_imports

~20-50x fewer tokens

Structural overview (names + line numbers)

any size

list_symbols

~15-30x fewer tokens

One function's signature

any size

read_symbol(depth="signature")

~50-200x fewer tokens

Language

Extensions

Structural edits

Comments

Docstrings

Notes

Python

.py

✅

✅ #

✅ function/class

Decorators preserved. Nested classes (decorated ones too) are listed with their members (class A.B, method A.B.m). Module-level dict/list literals editable via add_key / replace_value / delete_key / append_to_array (nested dicts addressed by key path, e.g. CONFIG."db"); comments in a list are not elements, so append_to_array puts the comma before them. Module-level variables (X = 1, Y: int = 2) are listed as variable and class attributes as field (A.x), at their first assignment; replace_value replaces their value. @overload stubs directly before their function are one symbol with it, listed once at the first stub. A name defined again (a redefinition, a @property setter) is listed again, and the name targets the first.

JavaScript

.js, .jsx, .mjs, .cjs

✅

✅ // + /* ... */

—

Exported declarations (export function, export class, export default function c) are listed and targeted by their own names, an anonymous export default function () {} / export default class {} as default; the export is part of the symbol, so read_symbol shows it and replace_function content should keep it. Generator functions (function* g()) and each name of a const/let/var bound to an arrow function or function expression (const f = (x) => {...}, exported or not) are listed and targeted as functions: read_symbol, replace_function, delete_symbol, the comment tools, insert_sibling and the parameter tools work on them, and the body tools on those with a { } body (one whose body is an expression, (x) => x * 2, is refused: rewrite it with replace_function). Their signature is const f = (x) =>, and replace_signature replaces from the const when the new signature starts with it, else only (x) =>; a lone unparenthesized parameter gets parentheses from the parameter tools (x => ... becomes (x, y) => ..., or () => ... when it is removed). Module-level const/let/var object literals (exported or not) editable via add_key / replace_value / delete_key; nested objects addressed by dotted path (CONFIG.server). Other data is listed too: each name of a const as constant and of a let/var as variable, and class fields as field (A.x, A.#y, static, decorated and declare ones), which the whole-symbol tools and replace_value (its value alone) take; a method or function wins over a class field or var of its name (static run = false; beside run() {}), and a setter beside its getter is not listed (the name targets the getter). Computed and quoted names are targets as listed (E.[Symbol.iterator], E.'a.b'). A comment after a symbol on its last line (function f() {} // f) is no part of it, as in the other languages. CommonJS require statements count as imports for add_import.

TypeScript

.ts, .tsx

✅

✅ // + /* ... */

—

Exports, generators and functions bound to names as for JavaScript. Abstract classes (abstract class A, exported or not) are classes for every tool, and their abstract methods are listed (an overloaded one once) and targeted (A.m) like the others, replace_signature included (the final ; stays); enums, type aliases and interfaces are listed as enum, type and interface and can be read, replaced, deleted, commented and used as insert_sibling targets. Interfaces are treated as classes for add_method / add_field, which refuse an enum or type alias (rewrite those with replace_function); a type alias has no depth="signature". A type alias or interface that shares its name with a value in one scope, as in zod's export const User = z.object(...) with export type User = z.infer<typeof User> (or an interface and a function), is targeted with its keyword, type User or interface Props (listed as type type User; with a dotted path the keyword goes first, type N.User), and the plain name targets the value. Overload signatures directly before their implementation (through export and declare, comments and the implementation's decorators between them; a run of signatures alone too) are one symbol with it, listed once at the first signature: read_symbol, replace_function and delete_symbol take them all, insert_sibling(position="before") and edit_leading_comment go above the first, and the signature depths, replace_signature, the parameter tools and the body tools work on the implementation. Namespaces (namespace N {}, module N {}) are listed as namespace with their classes and functions (N.C, N.f); one opened again, or merged with the class, function or enum of its name, is one container: the name targets the class, function or enum, its members and the namespace's are found and listed under it, and none of this is ambiguous. declare declarations are listed like plain ones (read_symbol shows the declare), and an abstract method reads with its ;. A namespace's interface ends with its }, without a comment after it. .tsx files are parsed with the TSX grammar, so JSX is valid there. Object literals editable as for JavaScript, including { ... } as const and satisfies T.

C

.c, .h

✅

✅ // + /* ... */ (single + multi-line)

—

.h defaults to C — use .hpp/.hxx/.hh for C++ headers (adding C++-only syntax to a .h file that parses as C is refused by the save-time syntax check). A struct, union or enum ends with the ; after its }: read_symbol shows it, replace_function content should end with };, and delete_symbol and insert_sibling(position="after") take it, also when it is on a line of its own. Listed as struct, union, enum, function, macro (#define, function-like ones over several lines too), type (typedefs; an anonymous typedef struct {...} P; lists its fields as P.x and takes add_field), field, variable and constant (const but not a pointer), including what #if/#ifdef blocks (include guards too) and extern "C" hold; a struct defined in a declaration or typedef is shown whole by read_symbol (struct S {...} s;, typedef struct N {...} N;). A definition wins over its forward declaration (struct S;), prototype or extern declaration in either order, and is what list and target; a prototype alone is a bodiless function (replace_signature and the parameter tools work on it). A definition outside #if/#ifdef blocks wins over one inside (#if 0), and of alternative definitions in #ifdef/#else branches the first is listed and targeted. A struct, union or enum that shares its name with a function, variable or typedef is targeted with its keyword (struct stat, listed as struct struct stat), and the plain name targets the other symbol (typedef struct N {...} N; stays one symbol, and a typedef of a struct declared apart, typedef struct Node Node;, is Node); add_method and add_field look only at containers, so stat is the struct there. Without overloading, f(int) only checks the parameter types. replace_value replaces the value of a global (int g = 1;, int a[] = {1}) or a macro's text (#define N 3), and gives one to a declaration without one (a C struct's field cannot have one and is refused); for a name that a macro shares with a function, the name is the macro and the function is name(types). A type that is only used (struct S *p;) and variables inside function bodies are not targets.

C++

.cpp, .cc, .cxx, .hpp, .hxx, .hh

✅

✅ // + /* ... */ (single + multi-line)

—

Supports class, struct, union, enum, namespace; Class::method qualified names resolve correctly. Classes end with their ; as in C. A template's template <...> header is part of its symbol, as decorators are: read_symbol shows it, replace_function content should include it, delete_symbol removes it, a leading comment and insert_sibling(position="before") go above it, and replace_signature keeps it unless the new signature starts with template. Template functions, classes and member templates are listed at the line of their header, an explicit specialization (template <> int id<int>(int)) under the name it specializes, and a definition outside its class (int A::f(), template <typename T> T Box<T>::get()) as a function under its qualified name (A::f, Box::get, A::A; the last name alone, or a shorter tail, still finds it when nothing else in the scope has that name). Overloads take their parameter types, written as declared without names, defaults or attributes, spacing free (A.m(int), A.m(const std::string &, int), A::A(int), A.operator()(int)), and method qualifiers where only those differ (A.get(int) const); spellings of one type match (unsigned and unsigned int, char const * and const char *, int[] and int *, a const on the parameter itself, struct S * and S *), so a prototype and a definition that spell it differently are one function. The bare name of an overloaded function, and a name several qualified names end with, are refused with the targets to use. A class or namespace declared with its scope (struct A::B {...}, namespace a::b {}) is A::B, and class X targets a class that shares its name with another symbol. Everything listed for C (constexpr variables as constant too), plus class, namespace (members as ns.f; a namespace opened again in its scope is listed once with the members of all its blocks, and a target finds a definition in any of them), nested classes (class A.B), using aliases as type, static members, methods declared in their class, and structured bindings (auto [x, y] = p;). Destructors and operators are named as written without spaces, ~A, operator==, operator(), operator bool, and targeted as A.~A or A.operator== (any spacing matches); find_references finds them.

Ruby

.rb

✅

✅ #

—

Classes, modules, instance methods, singleton_method (class methods via def self.foo). require/require_relative/load/autoload recognized as imports. A statement that opens a heredoc (X = <<~EOS) ends with the heredoc's body, for read_symbol and the whole-symbol edits. An endless method (def f = x) has no body for the body tools. Classes and modules nested in modules are listed with their members, private def m and class << self methods too (read_symbol shows the private). Embedded documents (=begin ... =end at column 0) stay at column 0 when content is re-indented, and an edit that would leave a =begin indented is refused; one directly above a method is its leading comment. A Sorbet signature directly above a method (sig { ... }, sig do ... end) is part of it, as a decorator is, and the signature depths start at its def. Constants are listed as constant and locals as variable. A class reopened in one scope is listed for each block, and the name targets the first; a dotted target finds a member in any of them. Interfaces show every method as its signature plus ..., empty and endless ones too.

Go

.go

✅

✅ // + /* ... */

—

struct, interface, functions, methods. Methods are addressed by receiver: Cache.Get resolves to the top-level func (c *Cache) Get(...). Grouped import (...) blocks supported. Type aliases (type T = int) are listed as type, and every name of a var/const as variable/constant. read_symbol shows the type, var or const of a declaration of one spec (a spec in a type (...) group alone) and a closure's key (RunE: func() error {...}). remove_parameter removes one name of a, b int, keeping the others' comments. A var x = func(...) {...} is a function for the parameter, body and signature tools (listed as variable; one of several values, var p, q = func() {}, func() {}, has its own signature). replace_value on a constant without a value that the constants below it repeat is refused, as a value would change theirs.

Java

.java

✅

✅ // + /* ... */ + Javadoc /** ... */

—

class, interface, enum, record; methods, constructors, fields. Annotations (@Override, @Deprecated) travel with their method on edits (wrapped in the modifiers node); replace_signature keeps them unless the new signature includes its own, and also works on interface and abstract methods, which have no body. Enum methods (nested in enum_body_declarations) discovered via BFS in list_symbols. Fields and interface constants are listed as field A.x and targetable; a field that shares its name with a method is the name's target, and the method is A.x(). Overloaded methods and constructors take their parameter types (A.m(int), A.m(String...), A.join(List<String>, String), A.A()), without modifiers and annotations; the bare name is refused with the targets to use. Nested classes, enums, interfaces and records are listed with their members, and a nested class whose name a field takes is left out, its members still listed (A.B.m).

JSON

.json

✅ (keys, values, arrays)

— (no comment syntax)

—

Numbers with a + in the exponent (6.02E+23), which the grammar cannot parse on its own, are read as whole values, so replace_value, delete_key and add_key beside them work as for any other number.

YAML

.yml, .yaml

✅ (keys, values, sequences)

✅ #

—

Block and flow sequences supported. Keys inside flow mappings are addressable by path (a: {x: 1} is a.x, nested ones too), so read_symbol, replace_value and delete_key work on them and they stay inline. add_key also adds to flow mappings ({a: 1}, {}) and to a key with no value (parent:). A key with no value can be read (as an empty string), commented, and given a value with replace_value (a: 3; content of several lines, or a block sequence or mapping, goes below the key one level deeper); an explicit key with no value (? a) gets its value on a : 3 line below it, in the column of the ?. In a multi-document file a path is looked up in each document in turn (add_key with parent_target="" adds to the first document with content). Quoted keys are matched by the name they spell, so 'it''s' is target it's and "caf\u00e9" is café. Removing the only item of a block sequence leaves key: [].

TOML

.toml

✅ (keys, values, arrays, tables)

✅ #

—

[table] headers (dotted and quoted ones too, [tool.uv], [a."b.c"]) addressable by their names for comment tools and add_key. Keys inside inline tables (t = { a = 1 } is t.a, nested ones too) and dotted keys (x.y = 1 is x.y) are addressable by path. add_key also adds to inline tables (t = { a = 1 }, t = {}).

Tool

Parameters

Description

replace_function

file_path, target, content

Replace a full function definition (signature + body + decorators, and a JS/TS export or C++ template <...> header): exactly what read_symbol returns, so its text can be edited and given back as is, and given back unchanged leaves the file byte for byte as it was; that shape may hold several members (a method replaced by two, a field by two fields, a method and a decorated one), each starting at the symbol's indentation once the one before has ended. Content written relative (first line at column 0, the rest indented from it) or at its file indentation is re-indented as before. When no line sits at the symbol's own indentation to tell these shapes apart, content whose later lines are all deeper than the symbol's indentation is taken as read_symbol's text and keeps them where they are (a 4-space method body for a 2-space class stays 4 spaces in); a decorator or annotation at the symbol's indentation counts only before the first line of code; at column 0 the shapes are one and content goes in as written. A comment before the symbol on its first line (/** @type {X} */ let x;) is no part of it and stays, and the content's later lines are indented as that line, or as the line where a block comment ending there ( */ void f() {) starts. A comment after the symbol on its last line stays unless the content ends with one, and so does a ; or , after it unless the content ends with it (a JS/TS class field's goes when the content is a method). A name declared together with others (int a = 1, b = 2;, struct S {...} s;) has that declaration replaced, and content that would drop the others is refused. A symbol that shares a line with other code has only its own text replaced (see Layout-aware deletion above). Refused in JSON, YAML and TOML files (use replace_value).

replace_function_body

file_path, target, content

Replace only the body of a function, preserving signature and decorators. A body written on one line with its signature or braces (function f() { return 1; }, def f(): return 1) is rebuilt over lines of its own, one level deeper than the function, as is content for an empty body ({ and } on lines of their own, and an empty Ruby method, def f over end or def h; end, or one holding only comments, which the content replaces); a comment that ends a one-line Python body stays at the end of the def's line (def b(): # old). A Ruby endless method (def f = x) is refused. In a Ruby method with rescue, else or ensure clauses only the code before the first clause is replaced and the clauses stay: def f\nrescue => e\n log(e)\nend with content 1 gives def f\n 1\nrescue => e\n log(e)\nend. With no code before the clause the content goes one level deeper than the def, as in an empty method; a clause on the same line as code moves to a line of its own; content with clauses of its own replaces the whole body, clauses included. When a one-line Ruby body is rebuilt, clauses that share a line with their code or the end are rebuilt too (def f; x; rescue; y; end becomes def f\n 1\nrescue\n y\nend); clauses already on lines of their own keep their text.

replace_signature

file_path, target, new_signature

Replace only the signature, preserving the body. new_signature is everything from the start of the definition up to its body (def get(self, key):, JS get(key, d) without the {). Existing decorators (Python, JS/TS), Java annotations and a C++ template <...> header are kept unless new_signature includes its own, which replace them. Indentation on the signature's first line is ignored, so "def get(self):" and " def get(self):" both work for a method; the lines after it may be indented relative to it ("@staticmethod\ndef get(key):") or written as read_symbol(depth="signature") returns them. For a JS/TS const f = (a) => {...}, "const f = (a, b) =>" replaces from the const on and "(a, b) =>" only the function's own part; likewise a closure's key (handler: (a) =>), a TS declare, a C/C++ typedef or extern "C", a Go type or var, a Ruby private and a Sorbet sig are replaced by a new signature that starts with its own, and kept otherwise (an export stays; a new closure key renames it). A TS overload group and a Python @overload group have the implementation's signature replaced, and a Ruby endless method keeps its = expression. A method declared without a body (a TS abstract method, a Java interface or abstract method, a C++ A() = default;, a Go function without one, a C/C++ prototype or a method declared in its class, int f(int);) is all signature but its final ;, which stays whether or not new_signature ends with one. A Go struct or interface type and an empty Ruby class, module or method take the header read_symbol(depth="signature") gives them (type A struct, class A < B); a variable or constant has no signature and is refused.

replace_in_body

file_path, target, old_snippet, new_snippet

Replace a snippet inside a function body, scoped to the target's body: its exact text at token boundaries, else its whole lines with their indentation shifted, matching exactly one place (see Body snippets and anchors above). new_snippet is indented as the snippet matched; '' deletes.

delete_in_body

file_path, target, snippet

Delete a snippet inside a function body, matched as replace_in_body matches one. Lines left without code go whole, with their indentation and line break; a comment after the snippet stays; a Python body keeps a statement.

insert_in_body

file_path, target, new_snippet, at | after | before

Insert a snippet inside a function body. Pass exactly ONE of: at="top" (prepend), at="bottom" (append), after=<snippet> (anchored), before=<snippet> (anchored). at inserts at the body's own indentation level even when the body ends in a nested block; a Python docstring stays first; a body written on one line with its signature or braces is refused (rewrite it with replace_function_body); an empty body (also an empty Ruby method) takes the content one level deeper than the function. An anchor is matched as a replace_in_body snippet; one that ends (after) or starts (before) its line gets the new text on lines of its own, indented like it and inside the block its line opens (see Body snippets and anchors above), else byte for byte, as does an anchor in a body on its signature's line. A line break at the start of new_snippet after an anchor that has none, and spaces after its last line break, are taken for the anchor line's own, and a final line break is added. In an empty body there is no code to anchor to (an anchor on its brace inserts byte for byte); use at="top" or at="bottom" there. after an anchor that ends with the body's closing brace is refused.

add_top_level

file_path, content, position="bottom"

Insert top-level content. position="bottom" appends at end of file (default), in a header inside its include guard, before the #endif; position="top" inserts after the preamble (as for a first import: package, #! and magic comments, directives, imports and includes, a header comment, the Python module docstring, a header's include guard) and before the first real declaration, without splitting a comment from the code it documents. The content is separated from its neighbours by one blank line, two in a Python module when either is a def or class (PEP 8); at the top, more blank lines the file had there stay below it; at the bottom, one-line content after one-line code that is stacked with the code above it is stacked too, but not after imports, includes or a package clause (unless it is an import itself). read_symbol's text of a nested symbol (recognised by its closing line or a decorator) is moved to column 0 as a whole.

add_method

file_path, class_target, content

Add a method at the end of a class body (in a C++ class, right after the last method when an access label follows it), indented like the class's members and separated as its methods are (see Layout-aware add_method / add_field above).

add_field

file_path, class_target, content

Add a field/attribute/member at the top of a class body (after a Python class docstring or a Java enum's constants, below the access label a C++ class body opens with), indented like the class's members.

insert_sibling

file_path, target, content, position

Insert content as a sibling of a named symbol. position="before" or "after"; "before" goes above the symbol's leading comment block, decorators, a JS/TS export and a C++ template <...> header. The new code goes into the gap between the target and the symbol on that side (with that symbol's comment, decorators and export) and is spaced like it: next to a function, class or other code over several lines, by that gap or the usual one when wider (one blank line, two at the top level of a Python module around a def or class, PEP 8); between one-line code (fields, constants, prototypes, macros) stacked without blank lines, stacked too (int f(void); int h(void); int g(void);), also after the last stacked field or before the first, and below stacked fields before a method; the end of a body or file, a C++ access label and a comment above the new code get no added blank lines. "before" keeps a #! line and encoding or magic comments first. "after" goes below comment lines right under the target that are indented deeper than it (they end its code), and below a block comment after the target on its last line that goes on over more lines. read_symbol's text is indented as a whole, also when it holds several members (see replace_function). Content is indented in tabs next to a tab-indented target, as for add_method. "before" is refused when other code comes before the target on its first line, "after" when other code follows it on its last line or the line starts with the code the target is part of (class A: x = 1), and empty content is refused, as is the tool in JSON, YAML and TOML files.

delete_symbol

file_path, target, include_leading_comments=True

Delete a function or class definition block (including decorators, a JS/TS export and a C++ template <...> header) and the blank lines that separated it (see Layout-aware deletion above). By default also consumes the contiguous leading comment block above the symbol and its decorators (Godoc, Javadoc /** ... */, # or // comments); pass include_leading_comments=False to keep it. A Ruby =begin document and a Sorbet sig above a method go too, and so do comment lines right below the symbol indented deeper than it. A comment before the symbol on its first line (/** @type {X} */ let x;) counts as a leading comment: by default it goes with the symbol, also when it is a block comment that began on an earlier line and when code follows the symbol on its line (/* c */ let x; let y; minus x is let y;); with include_leading_comments=False it stays, on a line of its own (/** @type {X} */ above the next line). A name declared together with others (int a, *b;, Java int x, y;, C++ auto [x, y] = p;, struct S {...} s;, Go var a, b = 1, 2, JS const a = 1, b = 2;) is refused, naming them, rather than deleted with them: give replace_function the declaration without that name instead. Refused in JSON, YAML and TOML files (use delete_key).

Tool

Parameters

Description

add_parameter

file_path, target, parameter, position="end"

Add a parameter to a function signature (position: "start" or "end"; any other value is refused). A list written one parameter per line (aligned under the first one too) gets the new one on a line of its own at the parameters' indentation, with a trailing comma when the last parameter has one; comments are not parameters and stay on their lines. A list with two parameters on a line gets it inline (a, b, c). An empty list over two lines (def f(\n):) gets the parameter on a line of its own, one level deeper (with a trailing comma in Go, and in Python, JS and TS as the file's other lists have it). A name the function already has is refused (Parameter 'a' already exists in 'f'), names in destructuring patterns and Go groups included; several _ are fine in Go, Java and Ruby. A C or C++ (void) list gets the parameter in place of void (f(void) becomes f(int c); void *p is a parameter). "end" goes before the parameters that must stay last: a Python **kwargs (f(a, **kw) plus b is f(a, b, **kw); after *args or a bare * the new parameter is keyword-only), a JS/TS rest parameter (function f(a, ...rest) plus b is function f(a, b, ...rest)), a Go variadic one (func f(a int, xs ...int) plus b string is func f(a int, b string, xs ...int)), Java varargs (String... xs), the ... of C and C++, a C++ parameter pack (Ts... xs) and a C/C++ macro's GNU named variadic parameter (#define M(a, args...) plus b is #define M(a, b, args...)). On the old C++ form int a... outside a template, the new parameter goes before the ... (int g(int a, int b...)); int... and template functions keep it before the variadic parameter. A C++ int f(...) gets int f(int b, ...) at either position. In Ruby the new parameter goes before the kinds that must come after it, in Ruby's order: required, optional, *splat, required, keyword, **opts/**nil, &blk, ...; so b goes before keyword parameters, b = 1 before the splat, *r before keywords and k: 1 before **opts (def f(a, **opts, &blk) plus b is def f(a, b, **opts, &blk)). In a list written one per line the new parameter gets its own line above them. "start" goes after a TS this parameter or a Java receiver parameter, which must stay first (function f(this: Window, a) plus b is function f(this: Window, b, a)); in a list written one per line, above the first parameter and the comment lines right before it.

remove_parameter

file_path, target, parameter_name

Remove a parameter by name. One on a line of its own goes with that line and the comment at its end; comments on other lines stay (one after the parameter before it too), a last parameter with no comma after it takes the comma before it (except in Go before a line break, which needs it), and removing the only parameter leaves (). A Go name of several that share a type goes alone (func f(a, b int) minus a is func f(b int)), the other names keeping their comments; a type-only Go parameter, the receiver and named results are not parameters; a comment after the comma before a last Go name stays. A name bound by a JS/TS or Ruby destructuring parameter goes alone ({a: x, b} minus x is {b}; in an array or Ruby pattern a hole or _ keeps the positions, [a, b] minus a is [, b]), and the parameter goes when it was its only name; a key (a of {a: x}) is not a name. In a C file (.c, .h) removing the last parameter leaves (void), not () (unspecified parameters before C23), and removing the last named parameter before a ... is refused, since f(...) is invalid C before C23; C++ keeps () and allows f(...) (int f(int a, ...) minus a is int f(...)). In Python a bare * goes when only **kwargs would follow it (f(a, *, b) minus b is f(a), f(a, *, b, **kw) minus b is f(a, **kw)), and a / goes when the removed parameter was the only one before it (f(a, /, b) minus a is f(b)). Removing *args leaves a bare * when keyword-only parameters follow it (f(a, *args, b) minus args is f(a, *, b), and f(a, *args, b=1, **kw) gives f(a, *, b=1, **kw)); with nothing or only **kwargs after it, *args just goes (f(a, *args, **kw) gives f(a, **kw)).

Tool

Parameters

Description

add_import

file_path, import_text

Add an import/from/#include/require line. Skips duplicates. Goes into the group of imports it belongs with, at its sorted place when the group is sorted, else after the group's last import, and after the file's last import when no group fits; a first import goes after the preamble with a blank line around it (see Import placement above). For Go, import "foo" and a spec alone ("foo", alias "foo") both work: the spec goes inside an existing import ( ... ) block, or is written as import "foo" without one.

remove_import

file_path, import_text

Remove a matching import line, compared after stripping surrounding whitespace: pass the exact line.

add_import_name

file_path, module, name

Add one name to an existing named-import statement: from <module> import a, b (Python) or import { a, b } from "<module>" (JS/TS, import type {...} and import D, {...} too). Idempotent. When the names are sorted the new one goes at its sorted place, else at the end. Sorted means plain, case-sensitive order (a single name always is), or else isort's and ruff's order by type: CONSTANT_CASE, then CamelCase, then the rest, each without case (from typing import TYPE_CHECKING, Any, cast plus Dict gives TYPE_CHECKING, Any, Dict, cast); names that fit both use plain order (Any, Dict plus TYPE_CHECKING gives Any, Dict, TYPE_CHECKING). A name sorts by the name it imports (b as bb as b, a TS type B as B). The list keeps its layout: names written one per line in parentheses or braces get the new one on a line of its own at their indentation (aligned under the ( or { when they are), above the next name and the comment lines right above it, or at the end after the last name's line and its comment, with the trailing-comma style kept (from x import (alpha, gamma) one per line plus beta gives alpha, beta, gamma, one per line); a comment heading the list stays first, and a next-line directive (see Import placement above) stays on the name below it. Inline lists, and a Python list without parentheses, stay inline, the new name going before the next one (from x import a, c plus b gives a, b, c; import { a, c } from "m" plus b gives { a, b, c }). For a default or namespace import (import Foo from ..., import * as ns from ...) use add_import with the full line.

remove_import_name

file_path, module, name

Remove one name from a multi-name named-import statement (Python and JS/TS). If the last named import is removed and no default/namespace binding remains, the whole line is removed; removing the last name beside a default binding (import D, { a } from "m") is refused, as it would leave empty braces: use remove_import, then add_import the default binding. In parentheses or braces, a name on a line of its own goes with that line and the comment at its end, comments on other lines stay, and a last name without a comma takes the comma before it.

Tool

Parameters

Description

edit_leading_comment

file_path, target, op, comment=""

Edit the contiguous leading-comment block above a named symbol, which is above its decorators/annotations, a JS/TS export and a C++ template <...> header; a symbol that other code comes before on its line has none of its own and is refused. op="add" inserts (refused if the symbol already has a leading comment; the error quotes it, so a following op="replace" can repeat lines worth keeping, such as // eslint-disable-next-line or //go:noinline directives); op="replace" replaces (or inserts if none); op="remove" deletes. comment includes its markers, is re-indented to the symbol, and is required for add and replace (ignored for remove). Works for # / // / /* ... */ / Javadoc /** ... */ and a Ruby =begin document (alone or with # lines beside it, kept at column 0); a Ruby Sorbet sig and a TS function's overload signatures are part of the symbol, so the comment goes above them; a comment line indented deeper than the symbol ends the code above, so op="add" puts the new comment between the two; a /* ... */ that follows code on its line (int x = 1; /* n */) is not taken as a leading comment. In YAML and TOML the target is a key path (a YAML key with no value too) or a TOML [table] by its header's names (tool.uv); a key that does not start its line (inside a flow mapping or inline table) is refused, since the comment line above would belong to another key.

replace_docstring

file_path, target, new_docstring

Replace or insert a Python function/class docstring, or the module's for target="". Python-only. new_docstring must be one Python string literal with its quotes, for every target: bare text, an f-string, a bytes literal or an empty new_docstring is refused (the error says to write it with its quotes, as in '"""Summary."""') and the file is left unchanged. Inserting one into a body on its signature's line (def f(): return 1) is refused: rewrite the body with replace_function_body. A new module docstring goes before the first statement (a from __future__ import stays after it), right below a #! line and an encoding comment, and below a header comment set off by a blank line, which keeps its blank lines; a comment right above the first statement stays with it, below the docstring. One blank line follows the docstring (two before a def or class), and in a file with no statement it goes last. An f-string or bytes literal at the top of the module is no docstring and stays.

Tool

Parameters

Description

replace_value

file_path, target, content

Replace the value of an existing key. Targets as for delete_key: JSON/YAML/TOML dotted path from the top level ("editor.fontSize" for a key with dots; keys inside YAML flow mappings and TOML inline tables too, which stay inline); Python DictName.keyExpr; JS/TS VarName.key (a shorthand { key } becomes key: <content>). A YAML key with no value (a:) gets one (a: 3, or a nested block below the key for content of several lines or a block sequence or mapping; a first line that is only |, >-, an &anchor or a !tag stays after the colon). In source files it also replaces the value of a variable, constant or field (Python X = 1 and class attributes, JS/TS const X = 1;, each name of let a = 1, b = 2 alone, and class fields A.x, Go var/const, C/C++ globals, C++ fields and static members, macros, Java fields, Ruby constants and locals, a heredoc's body too): only the value (int x(1); and int y{1}; keep their delimiters), and a declaration without one gets one (let x; becomes let x = 2;, X: int becomes X: int = 2, int g; becomes int g = 2;). Refused: a function, class or type (rewrite it with replace_function), a name that shares one value with others (a = b = 1, Go var c, d = f()), and one that cannot have a value of its own (extern, TS declare, an abstract field, Go var e, g int; for C struct fields and Go constants see the language table).

add_key

file_path, parent_target, key, value

Add a key-value pair to a dict/object/mapping/table. For config, parent_target is a dotted path from the top level (use "" for root; a TOML [table] by its header's names, a."b.c" for [a.'b.c']); YAML flow mappings (nested ones too) and keys with no value and TOML inline tables work too. For JSON and YAML key is one name, dots included. For Python it is the dict variable name; for JS/TS the name of a module-level const/let/var (or export const) object literal, as const / satisfies included. Both may continue into nested literals (CONFIG."db", CONFIG.server). JSON keys are quoted for you, YAML and TOML keys only when they need it (in TOML, dots make a dotted key), JS/TS keys only when they are not valid identifiers, Python keys are key expressions ('"timeout"'). The entry follows the container's layout (one per line, inline, trailing comma), and a key that already exists is refused (use replace_value).

delete_key

file_path, target

Delete a key-value pair. Targets: JSON/YAML/TOML dotted path from the top level ("editor.fontSize" for a key with dots; keys inside YAML flow mappings and TOML inline tables too, cut like JSON entries with their comma); Python DictName.keyExpr; JS/TS VarName.keyName on const/let/var or export const object literals (handles regular pairs, { key } shorthand, methods, and quoted "complex-key"). Python and JS/TS paths may continue into nested literals (CONFIG.server.port). For JSON, Python and JS/TS, the adjacent comma is also removed (an entry on its own line goes with that whole line, including its same-line comment), and deleting the only entry leaves {}; other YAML and TOML keys go with their lines. For an entry of an inline object literal passed as a function argument (foo({ x })), use delete_in_body on the enclosing function.

append_to_array

file_path, target, value

Append a literal value to a list/array/sequence. For Python, target is the list variable name; for config, a dotted path from the top level. The array keeps its layout: inline stays inline ([1, 2, 3]), one element per line gets a new line at the elements' indentation, and a trailing comma is kept; comments are not elements, and the new element's comma goes before a comment (see Layout-aware append_to_array above).

remove_from_array

file_path, target, value_match

Remove the first matching element from a list/array/sequence. value_match is compared with each element's source text after stripping whitespace. Comments are not elements: one on its own line goes with that line and the comment at its end, comments on other lines stay (one above it, or after the element before it, too), the trailing-comma style is kept (a last element with no comma after it takes the comma before it), and removing the only element leaves [] (a YAML block sequence becomes key: [], before a comment on the key's line).

Tool

Parameters

Description

list_symbols

file_path

Formatted outline of all top-level functions, classes, methods and data with line numbers, one <kind> <name> (line N) per symbol, the name being its target (a symbol's line is that of its first decorator, export, Ruby Sorbet sig or first overload signature). JS/TS exported declarations are listed under their own names, an anonymous default export as default; generators and functions bound to a const/let/var as function, other const names as constant, let/var names as variable and class fields as field, TS abstract classes as class (with their abstract methods), and TS enums, type aliases, interfaces and namespaces as enum, type, interface and namespace. Nested classes are listed under their containers with their members (class A.B, method A.B.m), as are Python module variables and class attributes, Ruby constants and locals, C/C++ fields, macros, typedefs, globals, destructors and operators, Java fields and Go type aliases and variables (see the language table). Of a name a scope declares more than once, the target is listed, once. In C, C++, Java, JS and TS every entry is listed under the target that finds it at the listed line: overloads with their parameter types (method A.m(int) (line 2)), a C++ or Java method beside a field of its name as A.x() (in JS/TS the method is A.x and the field is not listed), a C++ definition outside its class by its qualified name (function A::f), and a tag or type that shares its name with another symbol after its keyword, so the line reads struct struct stat (line 1) or type type User (line 2); an entry no target reaches is left out. In Python and Ruby a name defined again is listed again, and the name targets the first. Names that a pattern binds (a, b = 1, 2, const {a} = o) are not listed, and a declaration of several names (int a, *b;) lists each. Go lists types with their methods, then the names of var and const declarations, then functions.

find_references

file_path, target

Syntactic search for all occurrences of an identifier (no scope awareness, so same-named unrelated identifiers show up too), matched per identifier rather than as a dotted path, returned as line N: <source line> in file order, by line and column.

read_symbol

file_path, target, depth="full"

Return source text of a single named symbol. depth controls how much: "full" returns the entire source (typically 10-20x fewer tokens than the whole file), from its first byte, so the later lines keep their file indentation: exactly what replace_function and delete_symbol take (with a Go type/var/const, a closure's key, a TS declare, the C typedef or declaration around a struct, a Ruby private, a TS abstract method's ;), ready to be edited and given back to replace_function as is; "interface" returns a class stub (header + fields + method sigs with ..., each member at its indentation relative to the class header and ending as written, with its ; or ,; a C/C++ class closes with };) or a function's signature; "signature" returns signature-only (a method with no body, such as a TS abstract or Java interface method or a C++ A() = default;, is its whole declaration, and a Go struct its header, type A struct). Both start where the full text starts, except that a function's or class's signature leaves out its decorators and a JS/TS export (handler: () =>, RunE: func() error, declare function f(a: number): void, extern "C" int f(int a), private def m(x), typedef struct N, or typedef struct without a tag), and a closure's interface is its signature. A TS overload group and a Python @overload group give the implementation's signature, a Ruby endless method its part before the =. For a Go type, "interface" is its declaration as "full" reads it plus its methods' signatures (type N int has no signature, but its interface lists its methods). Both refuse a variable, constant, field, type alias, macro or C/C++ forward declaration, saying what it is ('X' is a constant, which has no signature ...; read it with depth='full'). A declaration of several names (int a, *b;, Java int x, y;) reads whole for each of them, and a comment after the symbol on its last line is no part of it. For a config key path, "full" (the only depth config files take) returns the key's value (an empty string for a YAML key with no value).

read_imports

file_path

Return all import/include statements in the file.

Intent

Tool

New top-level function, class, constant, or type alias

add_top_level (use position="top" to prepend after preamble)

New method in an existing class

add_method

New field/attribute/member in a class

add_field

New content before or after a top-level symbol

insert_sibling(position="before" | "after") ("before" goes above the symbol's leading comment)

New lines at the top of an existing function body

insert_in_body(at="top")

New lines at the bottom of an existing function body

insert_in_body(at="bottom")

New lines at a specific spot inside a function body (anchored to existing text)

insert_in_body(after=…) or insert_in_body(before=…)

New parameter on an existing function

add_parameter

New import or #include

add_import

New name in an existing from X import … or import { a, b } from "mod"

add_import_name

New comment above a symbol

edit_leading_comment(op="add")

New Python docstring on a function/class

replace_docstring

New key in a dict/object/mapping/table (any lang)

add_key

New item in a list/array/sequence (any lang)

append_to_array

Intent

Tool

Rewrite the full function (signature + body)

replace_function

Rewrite only the body, keep the signature

replace_function_body

Change one statement/block inside a large body

replace_in_body (scoped snippet match)

Change only the signature, keep the body

replace_signature

Change only the leading comment above a symbol

edit_leading_comment(op="replace")

Change only the Python docstring

replace_docstring

Change the value of an existing key (config, Python dict, JS/TS object)

replace_value

Intent

Tool

Remove a function, method, or class

delete_symbol (consumes leading doc comment by default)

Remove one statement/line inside a function body (a route mount, a middleware call, a key of an inline object-literal argument)

delete_in_body

Remove a parameter from a function

remove_parameter

Remove an import or #include

remove_import

Remove one name from a multi-name named-import (Python or JS/TS)

remove_import_name

Remove a leading comment above a symbol

edit_leading_comment(op="remove")

Remove a key from a dict / config / JS-TS object literal

delete_key

Remove an item from a list/array

remove_from_array

Agent

Configuration File Path

Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json (macOS); %APPDATA%\Claude\claude_desktop_config.json (Windows)

Cursor

.cursor/mcp.json (Project) or ~/.cursor/mcp.json (Global)

Windsurf

Agent Panel → "..." → MCP Servers → View raw config

Antigravity

~/.gemini/config/mcp_config.json — see Antigravity IDE (uses uvx --from)

Gemini CLI

~/.gemini/settings.json (Global) or .gemini/settings.json (Project)

Agent

Instruction file

Any agent that reads AGENTS.md (Codex CLI, Windsurf, Zed, Cursor secondary)

AGENTS.md at repo root

Cursor

.cursor/rules/*.mdc (current) — legacy: .cursorrules

GitHub Copilot

.github/copilot-instructions.md

Windsurf

.windsurfrules or AGENTS.md

Antigravity

_agents/rules/

Aider / Gemini CLI / generic

Rules file or system prompt