insert_before_symbol
Insert text before a symbol's declaration, using LSP or tree-sitter to locate it. Add functions, methods, or doc comments precisely, avoiding manual line counting. Supports dry-run and diff previews.
Instructions
Insert text immediately before a symbol's declaration.
Useful for adding a new function/method before an existing one, or prepending a doc comment. Locates the symbol via the LSP document symbol tree (no manual line counting). Provide the full text to insert in 'content' — include trailing newline if appropriate.
Set include_doc_comment=true to insert before any existing leading doc comment instead of between the comment and the symbol — useful when adding a new function (with its own doc comment) above a function that already has one.
The response includes a unified diff of the change — a preview in dry-run, the applied change otherwise — unless show_write_diff is disabled.
Works even when the language server is cold or cannot parse the file: it then locates the symbol via a fresh tree-sitter parse (line-granular range, annotated in the output).
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| uri | No | Absolute path, file:// URI, or workspace-relative path. | |
| content | No | Text to insert before the symbol. | |
| dry_run | No | If true (default), preview only; do not write. | |
| dirty_ok | No | Allow editing a file with uncommitted changes. Default false — review/commit first, or pass true to proceed. | |
| name_path | Yes | Slash-separated symbol path within the file (e.g. "ClassName/methodName", or just "funcName" for top-level). | |
| include_doc_comment | No | If true, extend the operation to cover any contiguous comment lines (//, #, /*, *) directly above the symbol declaration. Lets you replace/delete a function together with its doc comment, or insert a new block above an existing doc comment instead of between the comment and its symbol. A WRAPPED declaration (an exported ES declaration under its export statement, a decorated Python def under its @decorator) keeps its doc comment above the wrapper, so WHEN SUCH A COMMENT EXISTS insert_before_symbol and replace_symbol_body extend past the wrapper — replacement content must then reproduce the export keyword or the decorator, or it is dropped. With no doc comment above the wrapper the range starts at the declaration and the wrapper is untouched; safe_delete_symbol never extends past the declaration at all. |