Serena

Use this tool only on explicit user request or after confirmation. It may be necessary to restart the language server if the user performs edits not through Serena, so the language server state becomes outdated and further editing attempts lead to errors.

If such editing errors happen, you should suggest using this tool.

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. Reading the entire file is only recommended if there is no other way to get the content required for the task. Returns the full text of the file at the given relative path.

Write a new file (or overwrite an existing file). For existing files, it is strongly recommended to use symbolic operations like replace_symbol_body or insert_after_symbol/insert_before_symbol, if possible. You can also use insert_at_line to insert content at a specific line for existing files if the symbolic operations are not the right choice for what you want to do.

If ever used on an existing file, the content has to be the complete content of that file (so it may never end with something like "The remaining content of the file is left unchanged."). For operations that just replace a part of a file, use the replace_lines or the symbolic editing tools instead. 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 files matching the given file mask within the given relative path. Returns a JSON object with the list of matching files.

Gets an overview of the given file or directory. For each analyzed file, we list the top-level symbols in the file (name_path, kind). Use this tool to get a high-level understanding of the code symbols. Calling this is often a good idea before more targeted reading, searching or editing operations on the code symbols. Returns a JSON object mapping relative paths of all contained files to info about top-level symbols in the file (name_path, kind).

Retrieves information on all symbols/code entities (classes, methods, etc.) based on the given name_path, which represents a pattern for the symbol's path within the symbol tree of a single file. The returned symbol location can be used for edits or further queries. Specify depth > 0 to retrieve children (e.g., methods of a class).

The matching behavior is determined by the structure of name_path, which can either be a simple name (e.g. "method") or a name path like "class/method" (relative name path) or "/class/method" (absolute name path). Note that the name path is not a path in the file system but rather a path in the symbol tree within a single file. Thus, file or directory names should never be included in the name_path. For restricting the search to a single file or directory, the within_relative_path parameter should be used instead. The retrieved symbols' name_path attribute will always be composed of symbol names, never file or directory names.

Key aspects of the name path matching behavior:

• Trailing slashes in name_path play no role and are ignored.
• The name of the retrieved symbols will match (either exactly or as a substring) the last segment of name_path, while other segments will restrict the search to symbols that have a desired sequence of ancestors.
• If there is no starting or intermediate slash in name_path, there is no restriction on the ancestor symbols. For example, passing method will match against symbols with name paths like method, class/method, class/nested_class/method, etc.
• If name_path contains a / but doesn't start with a /, the matching is restricted to symbols with the same ancestors as the last segment of name_path. For example, passing class/method will match against class/method as well as nested_class/class/method but not method.
• If name_path starts with a /, it will be treated as an absolute name path pattern, meaning that the first segment of it must match the first segment of the symbol's name path. For example, passing /class will match only against top-level symbols like class but not against nested_class/class. Passing /class/method will match against class/method but not nested_class/class/method or method. Returns JSON string: a list of symbols (with locations) matching the name.

Finds symbols that reference 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 (unless include_body is True, then the short snippet will be omitted). Note that among other kinds of references, this function can be used to find (direct) subclasses of a class, as subclasses are referencing symbols that have the kind class. Returns a list of JSON objects with the symbols referencing the requested symbol.

Replaces the body of the symbol with the given name_path.

Important: You don't need to provide an adjusted indentation, as the tool will automatically add the indentation of the original symbol to each line. For example, for replacing a method in python, you can just write (using the standard python indentation): body="def my_method_replacement(self, ...):\n first_line\n second_line...". So each line after the first line only has an indentation of 4 (the indentation relative to the first characted), since the additional indentation will be added by the tool. Same for more deeply nested cases. You always only need to write the relative indentation to the first character of the first line, and that in turn should not have any indentation. ALWAYS REMEMBER TO USE THE CORRECT INDENTATION IN THE BODY!.

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 body/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. It also can be used to insert a new import statement before the first symbol in the file.

Replaces one or more occurrences of the given regular expression. This is the preferred way to replace content in a file whenever the symbol-level tools are not appropriate. Even large sections of code can be replaced by providing a concise regular expression of the form "beginning.*?end-of-text-to-be-replaced". Always try to use wildcards to avoid specifying the exact content of the code to be replaced, especially if it spans several lines.

IMPORTANT: REMEMBER TO USE WILDCARDS WEHEN APPROPRIATE! I WILL BE VERY UNHAPPY IF YOU WRITE LONG REGEXES WITHOUT USING WILDCARDS INSTEAD!.

Deletes the given lines in the file. Requires that the same range of lines was previously read using the read_file tool to verify correctness of the operation.

Replaces the given range of lines in the given file. Requires that the same range of lines was previously read using the read_file tool to verify correctness of the operation.

Inserts the given content at the given line in the file, pushing existing content of the line down. In general, symbolic insert operations like insert_after_symbol or insert_before_symbol should be preferred if you know which symbol you are looking for. However, this can also be useful for small targeted edits of the body of a longer symbol (without replacing the entire body).

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, but after calling the initial instructions tool.

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.

Write some information about this project that can be useful for future tasks to a memory. Use markdown formatting for the content. The information should be short and to the point. The memory name should be meaningful, such that from the name you can infer what the information is about. It is better to have multiple small memories than to have a single large one because memories will be read one by one and we only ever want to read relevant memories.

This tool is either called during the onboarding process or when you have identified something worth remembering about the project from the past conversation.

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.

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.

Summarize the changes you have made to the codebase. This tool should always be called after you have fully completed any non-trivial coding task, but only after the think_about_whether_you_are_done call.

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

Search for a pattern in the project. You can select whether all files or only code files should be searched. Generally, symbolic operations like find_symbol or find_referencing_symbols should be preferred if you know which symbols you are looking for. Returns A JSON object mapping file paths to lists of matched consecutive lines (with context, if requested).

Execute a shell command and return its output.

IMPORTANT: you should always consider the memory about suggested shell commands before using this tool. If this memory was not loaded in the current conversation, you should load it using the read_memory tool before using this tool.

You should have at least once looked at the suggested shell commands from the corresponding memory created during the onboarding process before using this tool. Never execute unsafe shell commands like rm -rf / or similar! Generally be very careful with deletions. Returns a JSON object containing the command's stdout and optionally stderr output.

Activates the project with the given name.

Removes a project from the Serena configuration.

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.

Get the initial instructions for the current coding project. You should always call this tool before starting to work (including using any other tool) on any programming task! The only exception is when a user asks you to activate a project, in which case you should call the activate_project first instead and then call this tool.