serena.tools.jetbrains_tools

Source code: serena/tools/jetbrains_tools.py

---

class JetBrainsFindSymbolTool(agent)

Bases: Tool, ToolMarkerSymbolicRead, ToolMarkerOptional

Performs a global (or local) search for symbols using the JetBrains backend

Parameters:

agent (SerenaAgent)

apply(

name_path_pattern,

depth=0,

relative_path=None,

include_body=False,

include_info=False,

search_deps=False,

max_matches=-1,

max_answer_chars=-1,

)

Finds symbols and 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 retrieve children (e.g., methods of a class). Important: through search_deps=True dependencies can be searched, which should be preferred to web search or other less sophisticated approaches to analyzing dependencies. You will always receive at least quick info for returned symbols (even if include_info=False).

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]”. In any path component, using * will match any sequence of characters (excluding /), e.g. "Class/*substring*" matches a member substring. A pattern must not contain only wildcards (e.g. "*" or "/*").

Parameters:

• name_path_pattern (str) – the name path matching pattern (see above)

• depth (int) – depth up to which descendants shall be retrieved (e.g. use 1 to also retrieve immediate children; for the case where the symbol is a class, this will return its methods). Ignored if include_body=True. Default 0.

• relative_path (str | None) – Optional. Restrict search to this file or directory. If not specified, searches entire codebase. Note: for external dependencies, this must be an identifier starting with <ext that you have received earlier (don’t try to guess!).

• include_body (bool) – If True, include the symbol’s full source code.

• include_info (bool) – whether to include additional info (hover-like, typically including docstring and signature), about the symbol. Default False; info is never included for child symbols or if include_body is True.

• search_deps (bool) – If True, also search in project dependencies (e.g., libraries).

• max_matches (int) – Maximum number of permitted matches. If exceeded, a shortened result is returned which allows refining the search. -1 (default) means no limit. Set to 1 if you search for a single symbol.

• max_answer_chars (int) – max characters for the result (-1 for default). If exceeded, no content/a shortened result is returned.

Returns:

symbols matching the name.

Return type:

str

classmethod get_param_aliases()

Returns:

a mapping of parameter aliases for the apply method, where the key is the alias and the value is the actual parameter name. This can be used to define alternative parameter names for the same parameter.

Return type:

dict[str, str]

class JetBrainsMoveTool(agent)

Bases: Tool, ToolMarkerSymbolicEdit, ToolMarkerOptional, ToolMarkerBeta

Moves a symbol, file or directory to a new location using the JetBrains backend, updating all references

Parameters:

agent (SerenaAgent)

apply(

relative_path,

name_path=None,

target_relative_path=None,

target_parent_name_path=None,

)

Moves a symbol, file or directory to a different location and automatically update all references to affected symbols. Important: this tool should always be preferred to naive moving (e.g. via file system operations or edits) as it is much more reliable and efficient. It is always safe to use this tool. For some symbols, moving may not be applicable, and will result in no edits and a suitable error message. The target location is the new parent of the symbol, i.e. the moved entity is never renamed by the operation, only moved.

Valid moves:

• Symbol:

  • (relative_path, name_path) -> new parent symbol (target_relative_path, target_parent_name_path)

  • (relative_path, name_path) -> top level of target file or directory (target_relative_path). Always consider the concrete language-specific semantics!

    • target is a file: valid for languages like Python, where files are modules

    • target is a directory: valid for languages like Java, where directories are packages and can contain classes

• File or directory:

  • relative_path -> new parent directory (target_relative_path)

Parameters:

• relative_path (str) – the relative path to the file containing the symbol to move.

• name_path (str | None) – the name path of the symbol to move (empty for moving file or dir).

• target_relative_path (str | None) – the relative path of the target directory or file.

• target_parent_name_path (str | None) – the name path of the target parent symbol.

Return type:

str

class JetBrainsSafeDeleteTool(agent)

Bases: Tool, ToolMarkerSymbolicEdit, ToolMarkerOptional, ToolMarkerBeta

Safely deletes a symbol using the JetBrains backend, checking for remaining usages first

Parameters:

agent (SerenaAgent)

apply(

relative_path,

name_path=None,

delete_even_if_used=False,

propagate=False,

)

Safely deletes a symbol, file, or directory, checking for usages first and propagating deletion, if desired. Propagation means it is possible to request deleting of usages and cleaning up of unused code. Propagation is powerful for cleaning up code but should be used with care, and only when you are sure that Important: this tool should always be preferred to naive deleting (e.g. via file system operations or edits). When using it, you don’t have to search for usages first, as the tool will do it for you.

Parameters:

• relative_path (str) – the relative path to the file containing the symbol to delete.

• name_path (str | None) – the name path of the symbol to delete. A name path identifies a symbol within a source file, e.g. “MyClass/my_method”. Omit for deleting a file or directory.

• delete_even_if_used (bool) – whether to force deletion even if the symbol still has usages. Default is False (safe mode: will report usages instead of deleting).

• propagate (bool) – whether to propagate the deletion to usages of the symbol and also remove symbols that become unused after the deletion. Default is False.

Return type:

str

class JetBrainsInlineSymbol(agent)

Bases: Tool, ToolMarkerSymbolicEdit, ToolMarkerOptional, ToolMarkerBeta

Inlines a symbol using the JetBrains backend, replacing all call sites with the symbol’s body

Parameters:

agent (SerenaAgent)

apply(name_path, relative_path, keep_definition=False)

Inlines a symbol (usually a method/function, but also classes may be amenable to inlining, which turns invocation into anonymous class creation), replacing all call sites with the symbol’s body. Important: this tool should always be preferred to naive inlining (e.g. via searching for references and editing them).

Parameters:

• name_path (str) – the name path of the symbol to inline.

• relative_path (str) – the relative path to the file containing the symbol to inline.

• keep_definition (bool) – whether to keep the original method definition after inlining all call sites. May be ignored in some cases (e.g. when inlining a class).

Return type:

str

class JetBrainsFindReferencingSymbolsTool(agent)

Bases: Tool, ToolMarkerSymbolicRead, ToolMarkerOptional

Finds symbols that reference the given symbol using the JetBrains backend

Parameters:

agent (SerenaAgent)

apply(name_path, relative_path, max_answer_chars=-1)

Finds all symbols that reference the given symbol — its callers / usages / dependents, i.e. the symbols whose own definition (e.g. a method body) contains a reference to it. For each, returns its name path, file, and the surrounding line of code.

Parameters:

• name_path (str) – name path of the symbol for which to find references

• relative_path (str) – the relative path to the file containing the symbol (must be a file, not a directory) Note: for external dependencies, this must be an identifier starting with <ext that you have received earlier (don’t try to guess!).

• max_answer_chars (int) – max characters for the result (-1 for default). If exceeded, no content/a shortened result is returned.

Return type:

str

class JetBrainsGetSymbolsOverviewTool(agent)

Bases: Tool, ToolMarkerSymbolicRead, ToolMarkerOptional

Retrieves an overview of the top-level symbols within a specified file using the JetBrains backend

Parameters:

agent (SerenaAgent)

apply(

relative_path,

depth=-1,

max_answer_chars=-1,

include_file_documentation=False,

)

Gets an overview of the top-level symbols defined in the given file (classes, methods, fields) — its STRUCTURE, without their bodies. This is the cheap, structure-first way to learn what a file contains: it costs far less context than reading the whole file.

Parameters:

• relative_path (str) – the relative path to the file to get the overview of

• depth (int) – depth up to which descendants shall be retrieved. Default (-1) results in a language specific choice: 1 for java and kotlin and 0 for other languages

• max_answer_chars (int) – max characters for the result (-1 for default). If exceeded, no content/a shortened result is returned.

• include_file_documentation (bool) – whether to include the file’s docstring. Default False.

Return type:

str

class JetBrainsTypeHierarchyTool(agent)

Bases: Tool, ToolMarkerSymbolicRead, ToolMarkerOptional

Retrieves the type hierarchy (supertypes and/or subtypes) of a symbol using the JetBrains backend

Parameters:

agent (SerenaAgent)

apply(

name_path,

relative_path,

hierarchy_type='both',

depth=1,

max_answer_chars=-1,

)

Gets the type hierarchy of a symbol (supertypes, subtypes, or both).

Parameters:

• name_path (str) – name path of the symbol for which to get the type hierarchy.

• relative_path (str) – the relative path to the file containing the symbol.

• hierarchy_type (Literal['super', 'sub', 'both']) – which hierarchy to retrieve: “super” for parent classes/interfaces, “sub” for subclasses/implementations, or “both” for both directions. Default is “sub”.

• depth (int | None) – depth limit for hierarchy traversal (None or 0 for unlimited). Default is 1.

• max_answer_chars (int) – max characters for the JSON result. If exceeded, no content is returned. -1 means the default value from the config will be used.

Returns:

Compact JSON with file-grouped hierarchy. Error string if not applicable.

Return type:

str

class JetBrainsFindDeclarationTool(agent)

Bases: Tool, ToolMarkerSymbolicRead, ToolMarkerOptional

Finds the declaration of a symbol using the JetBrains backend

Parameters:

agent (SerenaAgent)

apply(relative_path, regex, include_body=False)

Finds the declaration of a symbol.

Parameters:

• relative_path (str) – the relative path to the source file containing the symbol for which to find the declaration.

• regex (str) – a regular expression with one group, where the group matches the symbol for which to perform the lookup. For example, to find the declaration of the process method in a call like obj.process(), pass an expression like “obj.(process)(process_input_arg=37)”. Prefer regexes with sufficiently large context around the group to render the match unambiguous. Uses Python syntax with MULTILINE and DOTALL flags enabled.

• include_body (bool) – whether to include the symbol’s body in the result. Default False.

Return type:

str

class JetBrainsFindImplementationsTool(agent)

Bases: Tool, ToolMarkerSymbolicRead, ToolMarkerOptional

Finds the implementations of a symbol using the JetBrains backend

Parameters:

agent (SerenaAgent)

apply(relative_path, name_path)

Finds the implementations of a symbol.

Parameters:

• relative_path (str) – the relative path to the source file containing the symbol for which to find implementations.

• name_path (str) – name path of the symbol for which to find implementations

Return type:

str

class JetBrainsRenameTool(agent)

Bases: Tool, ToolMarkerSymbolicEdit, ToolMarkerOptional

Renames a symbol, file or directory throughout the codebase using the JetBrains backend.

Parameters:

agent (SerenaAgent)

apply(

relative_path,

new_name,

name_path=None,

rename_in_comments=False,

rename_in_text_occurrences=False,

)

Renames a symbol, file or directory throughout the codebase. Note: renaming in comments/text is on a best-effort basis by the IDE; if the symbol name is non-unique, further verification is recommended.

Parameters:

• relative_path (str) – if name_path is passed, the relative path of the file containing the symbol. Otherwise, the path to the directory or file to rename.

• new_name (str) – the new name

• name_path (str | None) – the name path of the symbol to rename or None if renaming a file or directory.

• rename_in_comments (bool) – whether to also rename occurrences in comments. Default True.

• rename_in_text_occurrences (bool) – whether to also rename occurrences in text. Default True.

Returns:

a status message

Return type:

str

class JetBrainsDebugTool(agent)

Bases: Tool, ToolMarkerOptional, ToolMarkerBeta

Provides debugging functionality (run configs, breakpoints, stepping, inspection, and evaluation) via a persistent debug REPL connected to the JetBrains IDE.

Parameters:

agent (SerenaAgent)

apply(expression, repl_key='default')

Debug code by evaluating Groovy/Java expressions in a persistent REPL attached to the IDE’s debugger (run configs, breakpoints, stepping, inspection of live state).

Use the serena_info tool with topic jet_brains_debug_repl for usage information.

Parameters:

• expression (str) – a Groovy/Java expression/statement to evaluate in the REPL. If empty/null, closes the REPL with the given key.

• repl_key (str) – identifier for the REPL instance. State persists across calls with the same key.

Returns:

string representation of the result

Return type:

str

class JetBrainsRunInspectionsTool(agent)

Bases: Tool, ToolMarkerSymbolicRead, ToolMarkerOptional

Runs JetBrains IDE inspections on a file and returns the results.

Parameters:

agent (SerenaAgent)

apply(

relative_path,

min_severity=None,

inspection_names=None,

start_line=None,

end_line=None,

max_answer_chars=-1,

)

Runs IDE inspections (code analysis) on the given file and returns the problems found. This leverages the full power of JetBrains’ static analysis engine, including language-specific inspections, type checking, potential bugs, code style issues, and more.

Parameters:

• relative_path (str) – the relative path to the file to inspect.

• min_severity (str | None) – minimum severity level to include in results (e.g. “ERROR”, “WARNING”, “WEAK_WARNING”, “INFO”). If not specified, all severities are returned.

• inspection_names (list[str] | None) – optional list of specific inspection names to run (e.g. [“UnusedImport”, “TypeMismatch”]). If not specified, all applicable inspections are run.

• start_line (int | None) – optional 1-based start line to restrict the inspection range.

• end_line (int | None) – optional 1-based end line to restrict the inspection range.

• max_answer_chars (int) – max characters for the JSON result. If exceeded, no content is returned. -1 means the default value from the config will be used.

Returns:

JSON string with inspection results including severity, message, and location.

Return type:

str

class JetBrainsListInspectionsTool(agent)

Bases: Tool, ToolMarkerSymbolicRead, ToolMarkerOptional

Lists available JetBrains IDE inspections, optionally filtered by language or group.

Parameters:

agent (SerenaAgent)

apply(

language=None,

group_path_contains=None,

max_answer_chars=-1,

)

Lists the available IDE inspections. Use this to discover which inspections can be passed to the run_inspections tool’s inspection_names parameter.

Parameters:

• language (str | None) – optional language to filter by (e.g. “Java”, “Python”, “Kotlin”).

• group_path_contains (str | None) – optional substring to match against the inspection group path (e.g. “probable bugs”, “code style”).

• max_answer_chars (int) – max characters for the JSON result. If exceeded, no content is returned. -1 means the default value from the config will be used.

Returns:

JSON string with the list of available inspections including name, group path, and language.

Return type:

str