Serena

Reads the given file or a chunk of it. Generally, symbolic operations like find_symbol or find_referencing_symbols should be preferred if you know which symbols you are looking for. Returns the full text of the file at the given relative path.

Write a new file or overwrite an existing file. Returns a message indicating success or failure.

Lists files and directories in the given directory (optionally with recursion). Returns a JSON object with the names of directories and files within the given directory.

Finds non-gitignored files matching the given file mask within the given relative path. Returns a JSON object with the list of matching files.

Replaces one or more occurrences of a given pattern in a file with new content.

This is the preferred way to replace content in a file whenever the symbol-level tools are not appropriate.

VERY IMPORTANT: The "regex" mode allows very large sections of code to be replaced without fully quoting them! Use a regex of the form "beginning.*?end-of-text-to-be-replaced" to be faster and more economical! ALWAYS try to use wildcards to avoid specifying the exact content to be replaced, especially if it spans several lines. Note that you cannot make mistakes, because if the regex should match multiple occurrences while you disabled allow_multiple_occurrences, an error will be returned, and you can retry with a revised regex. Therefore, using regex mode with suitable wildcards is usually the best choice!.

Offers a flexible search for arbitrary patterns in the codebase, including the possibility to search in non-code files. Generally, symbolic operations like find_symbol or find_referencing_symbols should be preferred if you know which symbols you are looking for.

Pattern Matching Logic: For each match, the returned result will contain the full lines where the substring pattern is found, as well as optionally some lines before and after it. The pattern will be compiled with DOTALL, meaning that the dot will match all characters including newlines. This also means that it never makes sense to have .* at the beginning or end of the pattern, but it may make sense to have it in the middle for complex patterns. If a pattern matches multiple lines, all those lines will be part of the match. Be careful to not use greedy quantifiers unnecessarily, it is usually better to use non-greedy quantifiers like .*? to avoid matching too much content.

File Selection Logic: The files in which the search is performed can be restricted very flexibly. Using restrict_search_to_code_files is useful if you are only interested in code symbols (i.e., those symbols that can be manipulated with symbolic tools like find_symbol). You can also restrict the search to a specific file or directory, and provide glob patterns to include or exclude certain files on top of that. The globs are matched against relative file paths from the project root (not to the relative_path parameter that is used to further restrict the search). Smartly combining the various restrictions allows you to perform very targeted searches. Returns A mapping of file paths to lists of matched consecutive lines.

Use this tool to get a high-level understanding of the code symbols in a file. This should be the first tool to call when you want to understand a new file, unless you already know what you are looking for. Returns a JSON object containing info about top-level symbols in the file.

Retrieves information on all symbols/code entities (classes, methods, etc.) based on the given name path pattern. The returned symbol information can be used for edits or further queries. Specify depth > 0 to also retrieve children/descendants (e.g., methods of a class).

A name path is a path in the symbol tree within a source file. For example, the method my_method defined in class MyClass would have the name path MyClass/my_method. If a symbol is overloaded (e.g., in Java), a 0-based index is appended (e.g. "MyClass/my_method[0]") to uniquely identify it.

To search for a symbol, you provide a name path pattern that is used to match against name paths. It can be

• a simple name (e.g. "method"), which will match any symbol with that name

• a relative path like "class/method", which will match any symbol with that name path suffix

• an absolute name path "/class/method" (absolute name path), which requires an exact match of the full name path within the source file. Append an index [i] to match a specific overload only, e.g. "MyClass/my_method[1]". Returns a list of symbols (with locations) matching the name.

Finds references to the symbol at the given name_path. The result will contain metadata about the referencing symbols as well as a short code snippet around the reference. Returns a list of JSON objects with the symbols referencing the requested symbol.

Replaces the body of the symbol with the given name_path.

The tool shall be used to replace symbol bodies that have been previously retrieved (e.g. via find_symbol). IMPORTANT: Do not use this tool if you do not know what exactly constitutes the body of the symbol.

Inserts the given body/content after the end of the definition of the given symbol (via the symbol's location). A typical use case is to insert a new class, function, method, field or variable assignment.

Inserts the given content before the beginning of the definition of the given symbol (via the symbol's location). A typical use case is to insert a new class, function, method, field or variable assignment; or a new import statement before the first symbol in the file.

Renames the symbol with the given name_path to new_name throughout the entire codebase. Note: for languages with method overloading, like Java, name_path may have to include a method's signature to uniquely identify a method. Returns result summary indicating success or failure.

Write some information (utf-8-encoded) about this project that can be useful for future tasks to a memory in md format. The memory name should be meaningful.

Read the content of a memory file. This tool should only be used if the information is relevant to the current task. You can infer whether the information is relevant from the memory file name. You should not read the same memory file multiple times in the same conversation.

List available memories. Any memory can be read using the read_memory tool.

Delete a memory file. Should only happen if a user asks for it explicitly, for example by saying that the information retrieved from a memory file is no longer correct or no longer relevant for the project.

Replaces content matching a regular expression in a memory.

Execute a shell command and return its output. If there is a memory about suggested commands, read that first. Never execute unsafe shell commands! IMPORTANT: Do not use this tool to start

• long-running processes (e.g. servers) that are not intended to terminate quickly,

• processes that require user interaction. Returns a JSON object containing the command's stdout and optionally stderr output.

Activates the project with the given name or path.

Activates the desired modes, like ["editing", "interactive"] or ["planning", "one-shot"].

Print the current configuration of the agent, including the active and available projects, tools, contexts, and modes.

Checks whether project onboarding was already performed. You should always call this tool before beginning to actually work on the project/after activating a project.

Call this tool if onboarding was not performed yet. You will call this tool at most once per conversation. Returns instructions on how to create the onboarding information.

Think about the collected information and whether it is sufficient and relevant. This tool should ALWAYS be called after you have completed a non-trivial sequence of searching steps like find_symbol, find_referencing_symbols, search_files_for_pattern, read_file, etc.

Think about the task at hand and whether you are still on track. Especially important if the conversation has been going on for a while and there has been a lot of back and forth.

This tool should ALWAYS be called before you insert, replace, or delete code.

Whenever you feel that you are done with what the user has asked for, it is important to call this tool.

Instructions for preparing for a new conversation. This tool should only be called on explicit user request.

Provides the 'Serena Instructions Manual', which contains essential information on how to use the Serena toolbox. IMPORTANT: If you have not yet read the manual, call this tool immediately after you are given your task by the user, as it will critically inform you!.