Replace a whole symbol (decorators, signature and body) with new content. The replaced span is what read_symbol returns: decorators, a JS/TS export, a C++ template <...> header and code that only wraps the symbol are part of it, so keep them in content. read_symbol's text, edited or not, goes in as it is, and may become several members; content written from column 0 is re-indented to the symbol's level. A symbol that shares a line with other code has only its own text replaced. For one name of int a, b; the content must keep the others. Refused in JSON, YAML and TOML files (use replace_value).

Use this when: rewriting a symbol top to bottom (name, parameters and body). Don't use this when: only the body changes (replace_function_body), only the signature (replace_signature), or a few lines (replace_in_body).

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, keeping its signature and decorators. A body on its signature's line is rebuilt over lines of its own, and an empty body gets content one level deeper than the function. A Ruby method's rescue, else and ensure clauses stay and only the code before them is replaced, unless content has clauses of its own. Refused for a function without a block body: a Ruby endless method, or an arrow function whose body is an expression (use replace_function).

Use this when: changing the implementation but not the interface. Don't use this when: the parameters or return type change too (replace_function), or only a few lines change (replace_in_body).

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

Replace a snippet inside a function's body; the match is scoped to that body, so text elsewhere in the file never matches. A snippet found nowhere is refused; one found in several places is refused with their line numbers: add context.

Use this when: changing one statement or block in a long body. Don't use this when: replacing the whole body (replace_function_body), or editing a sub-expression no unique snippet can locate (your normal edit tool).

Example (a block written without its indentation): target="handle" old_snippet="if retry:\n wait()" new_snippet="if retry:\n backoff()\n wait()"

Delete a snippet inside a function's body, matched as replace_in_body matches one. A deletion that empties its lines removes them whole; a comment after the snippet on its last line stays. One that would leave a Python body without a statement is refused (replace the snippet with pass).

Use this when: removing a statement, block or line in a body, or an entry of an object literal passed as an argument. Don't use this when: deleting a whole function or class (delete_symbol).

Example: target="RegisterRoutes" snippet='r.Mount("/kb", kbHandler)'

Insert new_snippet inside a function's body. Set exactly one of at, after or before. at="top" goes after a Python docstring, at="bottom" at body level after the last statement, and in an empty body one level deeper than the function; at is refused for a body on its signature's line (use replace_function_body).

An anchor is matched as replace_in_body matches a snippet and must be unique. One that ends its line (after) or starts it (before) gets new_snippet on lines of its own; after a line that opens a block (if x:, if (x) {), new lines go inside the block. A mid-line anchor gets new_snippet byte for byte.

Use this when: adding lines to a body. Don't use this when: replacing the whole body (replace_function_body), changing existing lines (replace_in_body), or adding a top-level symbol (add_top_level).

Example (both written without indentation): target="handle" new_snippet='auth_check(request)' before='validate(request)'

Add a method at the end of a class body, after its last member, spaced like the class's methods. In Go it goes after the type declaration. In a C++ class whose last method is followed by an access label, it goes right after that method, so it gets the same access. A one-line Python or Ruby class is refused, and so is a function target (use insert_in_body).

Use this when: adding a method to an existing class. Don't use this when: adding a field (add_field) or a top-level function (add_top_level).

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

Delete a whole function, method, class or other symbol, with its decorators, a JS/TS export and a C++ template <...> header. The blank lines that set it apart go too, so the file keeps its spacing. A symbol that shares a line with other code is cut out of the line. One name of a declaration of several (int a, b;, struct S {...} s;) is refused: give replace_function the declaration without it. Refused in JSON, YAML and TOML files (use delete_key).

Use this when: removing a symbol along with its doc comment. Don't use this when: removing a config key (delete_key), an import (remove_import) or lines inside a body (delete_in_body).

Example: target="LRUCache.old_method"

Replace the value of an existing config key, dict or object entry, or of a variable, constant, field or macro in a source file (X = 1, const X = 1;, int x = 1;, #define N 3). Only the value changes; a declaration without one gets one (let x; becomes let x = 2;, YAML a: becomes a: 2). Refused: a function, class or type (use replace_function), a name sharing one value with others (a = b = 1) and a declaration that cannot have a value (extern, TS declare). Array elements are not addressable.

Use this when: updating a value that exists. Don't use this when: the key is new (add_key), or you edit an array (append_to_array, remove_from_array).

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

Add an import line, skipping an exact duplicate. It goes into the group of imports it belongs with (same package, standard library or not, relative or not), at its sorted place when the group is sorted, else after the group's last import. A comment heading the group stays first (a next-line directive stays on its import), and so do Python from __future__ imports. With no fitting group it goes after the last import, and a first import after the preamble.

Use this when: importing something the file does not import yet. Don't use this when: adding a name to an existing import (add_import_name).

Example: import_text="from typing import Optional"

Remove an import line, matched by its text with surrounding whitespace stripped.

Use this when: removing an unused import. Don't use this when: removing one name from a multi-name import (remove_import_name).

Example: import_text="import os"

Add a key-value pair to a JSON object, YAML mapping, TOML table, Python dict literal or JS/TS object literal. The entry follows the container's layout: one key per line stays so, an inline object stays inline, and a trailing comma is kept. A YAML key with no value gets a nested mapping. A key the container already has is refused, naming the target to give replace_value.

Use this when: the key does not exist yet. Don't use this when: the key exists (replace_value), or you add a list item (append_to_array).

Example (TS, const CONFIG = { server: {...} }): parent_target="CONFIG.server" key="port" value="8080"

Delete a key-value pair from a config file, or from a Python or JS/TS module-level dict or object literal. The adjacent comma goes too where the syntax has one, and deleting the only entry leaves {}; YAML and TOML keys otherwise go with their lines.

Use this when: removing a whole entry. Don't use this when: removing a list item (remove_from_array), or an entry of an object literal passed as an argument (delete_in_body).

Example: target='CONFIG."timeout"'

Append a value to a JSON, YAML or TOML array or a Python module-level list. The value follows the array's layout: an inline array stays inline ([1, 2] becomes [1, 2, 3]), one element per line gets a new line, and a trailing comma is kept. Comments are not elements: the comma goes before them.

Use this when: adding a list item. Don't use this when: adding a key-value pair (add_key).

Example: target="project.dependencies" value='"new-package"'

Remove the first element matching value_match from a JSON, YAML or TOML array or a Python module-level list. An element on a line of its own goes with that line and its comment; other comments stay. The trailing-comma style is kept, and removing the only element leaves [].

Use this when: removing one list item. Don't use this when: removing a whole key (delete_key).

Example: target="project.dependencies" value_match='"old-package"'

Add a field or member at the top of a class body: before the first member, after a Python class docstring or a Java enum's constants (adding the ; they need), and below the access label a C++ class opens with. It is indented like the class's members, with a blank line after it when a method follows. A function target is refused.

Use this when: adding a class attribute, field or member variable. Don't use this when: adding a method (add_method).

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

Replace the signature of a function, or the header of a class, keeping its body. Existing decorators, Java annotations and a C++ template <...> header stay unless new_signature has its own. Code that read_symbol's signature starts with (a JS/TS const f =, a closure's key, a TS declare, a Ruby private) is replaced when new_signature starts with it, else kept. A method without a body keeps its ;. Refused for a symbol with no signature, such as a variable.

Use this when: changing a function's parameters, return type or name. Don't use this when: the body changes too (replace_function), or one parameter is added or removed (add_parameter, remove_parameter).

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

List the symbols of a source file, one per line as <kind> <name> (line N), class members indented under their class (method A.B.m). Each name is the target the other tools take: overloads with their parameter types (A.m(int)), a C++ definition outside its class by its qualified name (A::f), and a struct or TS type that shares its name with another symbol after its keyword (struct struct stat targets struct stat). Kinds include function, method, class, struct, enum, interface, namespace, type, macro, field, variable and constant; a Go var x = func(...) {...}, listed as a variable, also takes the body, parameter and signature tools. A name with a prototype or forward declaration is listed once, at its definition. Read-only.

Use this when: before editing a file, to get exact target names. Don't use this when: you already know the target (read_symbol reads one symbol).

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

Add a name to an existing from <module> import ... (Python) or import { ... } from "<module>" (JS/TS) statement; a name already there is left as is. It goes at its sorted place when the names are sorted (plainly or as isort and ruff sort them), else at the end, in the list's layout: names one per line give it a line of its own, an inline list stays inline. Refused when the file has no such import.

Use this when: the module is already imported with named imports. Don't use this when: there is no such import yet, or for a default or namespace import (add_import with the full line).

Example (from typing import Any, cast becomes Any, Dict, cast): module="typing" name="Dict"

Remove one name from a from <module> import ... (Python) or import { ... } from "<module>" (JS/TS) statement. A name on a line of its own goes with that line and its comment. Removing the only name removes the statement, but is refused when a default import would be left with empty braces (import D, { a } from "m"): use remove_import, then add_import.

Use this when: dropping one name from a multi-name import. Don't use this when: removing the whole import line (remove_import).

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

Add one parameter to a function's signature, keeping the body. "end" puts it after the last parameter but before those that must come after it (Python **kwargs, a JS/TS rest parameter, Go and Java variadics, C/C++ ..., Ruby **opts and &blk); "start" before the first, but after a TS this or Java receiver parameter. A list written one parameter per line gets it on a line of its own, a C (void) takes it in place of void, and a bare JS/TS arrow parameter gets parentheses. A name the function already has is refused.

Use this when: adding a parameter without retyping the signature. Don't use this when: rewriting the signature (replace_signature), or changing the body too (replace_function).

Example (def f(a, **kw) becomes def f(a, b, **kw)): target="f" parameter="b"

Remove a parameter by name from a function's signature, keeping the body. A parameter on a line of its own goes with that line and its comment. Removing the only one leaves (), or (void) in C. In Python a * or / left invalid goes too, and a *args with keyword-only parameters after it leaves a bare * (def f(a, *args, b) minus args is def f(a, *, b)). One Go name of a, b int, or one name that a destructuring parameter binds, goes alone. Refused: a name the function lacks, and in C the last named parameter before ....

Use this when: dropping one parameter without retyping the signature. Don't use this when: rewriting the signature (replace_signature).

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

Replace or add the docstring of a Python function, method or class, or of the module with target "". new_docstring must be one string literal with its quotes; anything else (bare text, an f-string, bytes, an empty value) is refused. A new docstring goes first in the body; the module's goes below a #! line and encoding or header comments. A new docstring for a body on its signature's line is refused (use replace_function_body); so is any non-Python file.

Use this when: adding or updating a Python docstring. Don't use this when: editing a # comment above the symbol (edit_leading_comment).

Example: target="LRUCache.get" new_docstring='"""Return the cached value, or None."""'

List each occurrence of an identifier in a source file as line N: <source line>, in file order. Read-only and syntactic, with no scope analysis, so unrelated identifiers of the same name show up too. C++ destructors and operators go by their list_symbols names (~A, operator==).

Use this when: surveying a name's uses in a file before a rename. Don't use this when: you need references across files or by scope (use a language server).

Example: target="LRUCache"

Add top-level code (a function, class, constant or other statement) to a source file. "bottom" appends it at the end, inside a header's include guard; "top" puts it after the preamble, before the first declaration. It is set apart by a blank line, two around a Python def or class, but one-line code added at the bottom under stacked one-line code is stacked too. In Go, or a file indented with tabs, its indentation becomes tabs.

Use this when: adding a top-level symbol or statement. Don't use this when: placing it next to a symbol (insert_sibling), in a class (add_method, add_field), in a body (insert_in_body) or in a config file (add_key).

Example: content="MAX_CONNECTIONS = 10" position="top"

Return the source of one symbol (function, class, method, variable) or the value of a config key, without reading the whole file. Read-only. "full" is the text replace_function and delete_symbol take: decorators, a JS/TS export, a C++ template <...> header and code that only wraps the symbol (a Go type, a closure's key, a C typedef) included, a C/C++ class ending with its ;. It starts at the symbol's first byte, the later lines at their file indentation. "interface" gives a class's header, fields and method signatures (bodies as ...), indented as in the class, or a function's signature; "signature" the signature or class header alone, after decorators. Both refuse a variable, constant, field, type alias or macro, saying what it is. A name with a prototype or forward declaration reads as its definition.

Use this when: reading one symbol; pick the narrowest depth. Don't use this when: you need the file's outline (list_symbols) or its imports (read_imports).

Example: target="LRUCache", depth="interface"

Return the import statements of a source file (imports, includes, Ruby requires), without reading the rest. Read-only.

Use this when: checking a file's dependencies, as before add_import. Don't use this when: changing imports (add_import, remove_import).

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

Add, replace or remove the comment block directly above a symbol, its doc comment. The block sits above the symbol's decorators, annotations, export and C++ template <...> header, and a new comment goes there, re-indented to the symbol. A comment indented deeper than the symbol ends the code above and is not part of the block. A symbol that other code comes before on its line is refused. In YAML and TOML the target is a key path or a TOML [table]; JSON has no comments and is refused.

Use this when: adding, rewriting or deleting a symbol's doc comment. Don't use this when: writing a Python docstring (replace_docstring) or a comment inside a body (insert_in_body, replace_in_body).

Example: target="LRUCache.get", op="add", comment="# Return the cached value."

Insert code next to a named symbol, at its level. "before" goes above the symbol's leading comment, decorators and export; "after" below the symbol (after the ; that ends a C/C++ class). The code is spaced like the gap it goes into: one-line code stacked without blank lines stays stacked, and next to a function or class it gets at least one blank line, two around a top-level Python def or class. A comment indented deeper than the target ends the code above, so "before" goes below it. "before" is refused when other code comes before the target on its line, "after" when code follows it. Refused in JSON, YAML and TOML files (use add_key).

Use this when: placing code relative to a symbol, such as a helper above its caller. Don't use this when: appending at the end of the file (add_top_level), or inserting into a body (insert_in_body) or a class (add_method, add_field).

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