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 all non-gitignored 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 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 WHEN APPROPRIATE! I WILL BE VERY UNHAPPY IF YOU WRITE LONG REGEXES WITHOUT USING WILDCARDS INSTEAD!.

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, 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 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.

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.

Write some information 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.

Execute a shell command and return its output. If there is a memory about suggested commands, read that first. Never execute unsafe shell commands like rm -rf / or similar!. Returns a JSON object containing the command's stdout and optionally stderr output.

Activates the project with the given name.

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

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.

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.