Refactoring and Editing Tools
Relevant source files
The following files were used as context for generating this wiki page:
Serena provides a comprehensive suite of semantic code retrieval, editing, and refactoring tools designed to operate at the symbol level rather than through primitive text surgery. These tools allow AI agents to understand the relational structure of a codebase, enabling faster and more reliable modifications in complex environments. By utilizing high-level abstractions like symbol names and name paths, Serena avoids the fragility of line-number-based editing.
The system distinguishes between two primary editing approaches: Symbolic Editing, which targets high-level constructs like classes and methods, and File-based Editing, which handles granular or regex-based modifications within a specific file. Refactoring operations such as renaming, moving, and inlining are treated as atomic calls that collapse multiple error-prone steps into single operations.
Sources: README.md:9-16, src/serena/resources/config/modes/editing.yml:13-17
Symbolic Editing and Refactoring Architecture
Serena's symbolic tools are built to leverage either the Language Server Protocol (LSP) or a dedicated JetBrains IDE backend. The symbolic approach is preferred when adjusting entire symbols (e.g., methods or classes) or when performing cross-file operations that require semantic awareness.
Core Symbolic Workflow
The recommended workflow for an agent involves first acquiring a structural overview of a file before attempting edits. This ensures that modifications maintain backward compatibility or that all referencing symbols are updated simultaneously.
Refactoring Capabilities
Serena provides specific tools for structural changes that go beyond simple text replacement. These are prioritized over naive approaches to ensure project integrity.
| Tool Name | Description | Backend Support |
|---|---|---|
rename | Renames symbols, files, or directories across the project. | LSP (Symbols only) / JetBrains (All) |
move | Moves symbols, files, or directories to new locations. | JetBrains Plugin |
inline | Inlines a symbol definition at all call sites. | JetBrains Plugin |
safe_delete | Deletes a symbol only if it is unused or safe to remove. | LSP / JetBrains Plugin |
| Sources: README.md:183-195, src/serena/resources/config/modes/editing.yml:5-10 |
File-Based Editing Tools
When modifications are localized to specific lines or require pattern matching within a file, Serena utilizes file-based tools. The primary tool for this is replace_content, which supports both literal and regex-based replacements.
Pattern Matching Logic
The replace_content tool is optimized for efficiency by allowing the use of wildcards (.*?) to match large sections of text without requiring the agent to provide the full original content. This reduces token consumption and complexity.
Specialized File Operations
The file_tools.py module defines several classes for managing file content:
CreateTextFileTool: Writes a new file or overwrites an existing one, ensuring parent directories are created automatically. Sources: src/serena/tools/file_tools.py:44-68ReadFileTool: Retrieves specific chunks of a file usingstart_lineandend_lineparameters. Sources: src/serena/tools/file_tools.py:18-41SearchForPatternTool: A flexible regex search that returns matched lines with optional context, supporting multiline matching. Sources: src/serena/tools/file_tools.py:257-293
Configuration and Tool Mapping
The behavior of editing tools is governed by the Serena configuration system. This includes global defaults for answer lengths and project-specific settings for line endings and encoding.
Configuration Parameters
The SerenaConfig and ProjectConfig classes define critical parameters for editing operations:
| Parameter | Type | Default | Description |
|---|---|---|---|
line_ending | LineEnding | NATIVE | Sets line endings to lf, crlf, or native. |
encoding | str | utf-8 | Default encoding for file reads and writes. |
tool_timeout | float | 240.0 | Maximum time allowed for a tool execution. |
default_max_tool_answer_chars | int | 150,000 | Limits the size of tool responses to prevent token overflow. |
| Sources: src/serena/config/serena_config.py:171-186, src/serena/config/serena_config.py:535-555 |
Implementation Overrides
For clients with specific constraints, such as ChatGPT, tool descriptions are overridden to emphasize efficient regex usage and symbol-level navigation.
Sources: src/serena/resources/config/contexts/chatgpt.yml:19-33
# Example of configuration propagation to tools
# Source: src/serena/config/serena_config.py:734-738
def propagate_settings(self) -> None:
from serena.tools import JetBrainsPluginClient
JetBrainsPluginClient.set_server_address(self.jetbrains_plugin_server_address)
Summary
The Refactoring and Editing Tools in Serena provide a semantic layer over standard file operations. By prioritizing symbolic awareness via replace_symbol_body and structural changes via rename or move, the system ensures that AI agents can perform complex code maintenance with minimal errors. File-based editing via replace_content remains the primary fallback for granular text adjustments, leveraging regex wildcards to maintain efficiency.