Introduction to Serena
Relevant source files
The following files were used as context for generating this wiki page:
Serena is a high-level toolset designed to function as an "IDE for your coding agent." It provides semantic code retrieval, editing, refactoring, and debugging capabilities by exploiting the relational structure of code at the symbol level. Unlike traditional agents that rely on low-level line-based edits, Serena uses robust abstractions to make agents faster and more efficient, particularly in large and complex codebases.
The system integrates with various LLM clients via the Model Context Protocol (MCP). It supports over 40 programming languages through two primary backends: an open-source Language Server Protocol (LSP) implementation and a dedicated JetBrains Plugin for deep IDE-level analysis.
Sources: README.md:1-25, src/serena/config/serena_config.py:126-140
System Architecture
Serena's architecture centers around an MCP server that bridges the gap between an AI client (like Claude Code or Cursor) and symbolic code analysis backends.
High-Level Component Flow
The following diagram illustrates how Serena orchestrates tool requests between the LLM client and the underlying code analysis backends.
The system allows the agent to discover code structure through a symbol overview before performing targeted reads or edits.
Sources: README.md:95-105, src/serena/config/serena_config.py:133-156
Core Components
| Component | Description |
|---|---|
| MCP Server | The communication hub that exposes tools to AI clients via the Model Context Protocol. |
| LSP Backend | Uses the solidlsp library to spawn and manage open-source language servers. |
| JetBrains Backend | A paid plugin that leverages a running JetBrains IDE for superior refactoring and debugging. |
| Memory Manager | A system for persisting project-wide invariants and developer notes across agent sessions. |
| Web Dashboard | A browser-based interface for monitoring logs, tool stats, and managing configuration. |
Sources: README.md:110-140, src/serena/config/serena_config.py:133-156, src/serena/resources/dashboard/dashboard.js:1-50
Key Features and Tooling
Serena provides specialized tools categorized into retrieval, symbolic editing, and refactoring.
Retrieval and Navigation
Agents use these tools to build a mental map of the codebase without reading full files.
get_symbols_overview: Provides a file outline.find_symbol: Searches for symbols by name across the repository.find_referencing_symbols: Locates callers and usages of a specific symbol.find_declaration/find_implementations: Navigates symbol hierarchies.
Sources: src/serena/resources/config/prompt_templates/system_prompt.yml:65-75, src/serena/config/serena_config.py:159-173
Symbolic Editing and Refactoring
Instead of error-prone search-and-replace, Serena performs semantic transformations.
replace_symbol_body: Replaces a function or class definition safely.insert_before_symbol/insert_after_symbol: Context-aware code insertion.rename: Cross-file symbol renames.safe_delete: Deletes symbols after checking for usages.
Sources: src/serena/resources/config/prompt_templates/system_prompt.yml:78-85, README.md:155-170
Diagnostic Capabilities
The system supports fetching linter and compiler diagnostics to help agents debug.
# Available diagnostic tools (LSP & JetBrains)
# - get_diagnostics_for_file
# - get_diagnostics_for_symbol
# - jet_brains_run_inspections
Sources: src/serena/resources/config/prompt_templates/system_prompt.yml:40-50, README.md:148-150
Configuration System
Serena uses a multi-layered configuration strategy (Global, Project, and Local) defined primarily in YAML.
SerenaConfig Structure
The global configuration (serena_config.yml) manages the server environment, active projects, and backend settings.
Configuration Options
| Option | Type | Default | Description |
|---|---|---|---|
language_backend | Enum | LSP | LSP or JetBrains. |
web_dashboard | Boolean | True | Enables the browser-based monitoring dashboard. |
tool_timeout | Float | 240 | Timeout in seconds for tool executions. |
symbol_info_budget | Float | 10.0 | Time budget for fetching additional symbol metadata. |
line_ending | Enum | native | Line ending convention (lf, crlf, or native). |
Sources: src/serena/config/serena_config.py:535-600, src/serena/resources/serena_config.template.yml:1-150
Memory Management
A critical part of the Serena workflow is the memory system, which stores non-obvious project information that persists across sessions.
Memory Discovery Model
Agents follow a graph-based discovery process starting from a root memory.
The mem:core file acts as the primary source map for the project. Agents are instructed to consult the memory_maintenance.md guidelines before creating new memories to ensure they store durable, terse bullets rather than narrative prose.
Sources: src/serena/resources/memory_maintenance.md:1-25, src/serena/resources/config/prompt_templates/simple_tool_outputs.yml:5-25
Dashboard and Monitoring
The Serena Dashboard provides a real-time interface for observing agent behavior and system health. It is typically served on port 24282.
Dashboard Features
- Executions Queue: Displays currently running tasks and allows users to cancel stuck executions.
- Log Viewer: A real-time stream of tool calls, inputs, and results with syntax highlighting for tool names.
- Token Statistics: Visualizes input and output token usage per tool using Chart.js.
- Project Management: Allows adding/removing projects and languages dynamically.
Sources: src/serena/resources/dashboard/dashboard.js:400-550, src/serena/resources/dashboard/index.html:50-120
Conclusion
Serena transforms raw AI agents into sophisticated software engineers by providing them with the same symbolic and relational tools used by human developers in modern IDEs. By abstracting away line numbers in favor of symbols and providing a structured memory system, Serena ensures that agent workflows are more reliable, token-efficient, and maintainable.
Sources: README.md:15-30, src/serena/resources/config/prompt_templates/system_prompt.yml:5-20