serena

Serena abstracts 40+ language servers through a unified SolidLSP framework, enabling semantic symbol discovery (classes, functions, methods, variables) across codebases without regex or text-based matching. The system maintains a file buffer and symbol cache, translating LSP protocol responses into a unified symbol abstraction layer that agents can query for precise code locations, signatures, and relationships. This enables agents to navigate code at the semantic level rather than line-based text search.

Serena exposes ReplaceSymbolBodyTool and RenameSymbolTool that operate on the symbol abstraction layer rather than raw text. When an agent requests a symbol replacement, Serena uses the language server to locate the exact symbol boundaries, validate the replacement is syntactically sound, and apply the edit while preserving surrounding code structure. The system maintains a file buffer that tracks pending edits and can compose multiple symbol-level operations into a coherent transaction.

Serena exposes a command-line interface (serena CLI) for project initialization, configuration management, and server lifecycle control. Key commands include 'serena init' (initialize project with language servers or JetBrains backend), 'serena-mcp-server' (start MCP server with optional transport mode and context), and configuration commands for managing project and global settings. The CLI supports flags for context selection (--context), transport mode (--transport), port (--port), and other options. The architecture uses a hierarchical command structure with subcommands for different operations.

Serena includes a SerenaAgent core that manages task execution, memory, and state for LLM agents. The system maintains conversation history, tool call history, and project state across multiple interactions. The agent can decompose complex tasks into subtasks, track progress, and maintain context across tool invocations. The architecture supports different execution modes (synchronous, asynchronous) and integrates with the tool registry for seamless tool invocation. The system also provides hooks for custom logic (e.g., pre/post-tool execution).

Serena maintains language-specific server implementations for 40+ languages, with intelligent fallback and auto-download strategies. For each language, the system defines a preferred server (e.g., rust-analyzer for Rust, gopls for Go) and fallback options. Servers that can be auto-downloaded (e.g., via npm, pip, or direct download) are handled automatically; others require manual PATH configuration. The LanguageServerManager handles server lifecycle, including startup, shutdown, and restart. The system also provides configuration for server-specific options (e.g., LSP initialization parameters).

Serena implements an LSP protocol handler that normalizes responses from different language servers into a unified format. Language servers vary in their LSP implementation (some are strict, others have extensions or quirks), and the handler abstracts these differences. The system translates LSP protocol messages (textDocument/definition, textDocument/references, etc.) into Serena's internal symbol model, handling edge cases and server-specific behaviors. This enables agents to work with any LSP-compliant server without knowledge of server-specific quirks.

Serena implements a native Model Context Protocol (MCP) server that exposes all semantic code tools (FindSymbolTool, FindReferencingSymbolsTool, ReplaceSymbolBodyTool, RenameSymbolTool) as MCP resources and tools. The server supports multiple transport modes (stdio for Claude Desktop, streamable-http for shared access) and context-aware configuration via the --context flag, which selects predefined tool sets and system prompts optimized for different client types (claude-code, ide, codex, agent, etc.). This allows the same Serena backend to adapt its interface to different LLM clients.

Serena can use a JetBrains IDE (IntelliJ, PyCharm, etc.) as its semantic analysis backend instead of language servers. The system communicates with the IDE via LSP protocol handler and JetBrains plugin, leveraging the IDE's built-in symbol resolution, type inference, and refactoring capabilities. This approach provides superior semantic understanding for JVM languages (Java, Kotlin, Scala) and Python, at the cost of requiring a running IDE instance. The architecture abstracts this backend choice behind the same symbol and tool interfaces, allowing agents to work with either LSP or JetBrains transparently.

Serena implements FindSymbolTool and FindReferencingSymbolsTool that use language server symbol tables to perform semantic search across the entire codebase. Unlike text-based grep, these tools understand code structure and return only true semantic references (excluding comments, strings, and unrelated identifiers with the same name). The system maintains a symbol cache and file buffer to optimize repeated queries and provide fast turnaround for large codebases. Results include precise location information (file, line, column) and symbol metadata (kind, signature).

Serena automatically detects project languages based on file extensions and project configuration, then selects and initializes the appropriate language servers (or JetBrains backend). The system maintains a LanguageServerManager that handles server lifecycle (startup, shutdown, restart), caching, and fallback strategies. Agents can work with polyglot projects (e.g., Python + JavaScript + SQL) without explicit language configuration; Serena routes each file to the correct language server transparently. The architecture supports 40+ languages including Python, JavaScript, TypeScript, Java, Go, Rust, C++, C#, Ruby, PHP, and more.

Serena implements a project system that maintains awareness of project structure, file organization, and ignore patterns (similar to .gitignore). The system uses a configuration hierarchy (global config, project config, context-specific config) to determine which files are indexed, which tools are available, and how the system prompt is composed. File operations respect ignore patterns, preventing agents from accidentally modifying build artifacts, dependencies, or other non-source files. The architecture supports multiple project contexts (desktop-app, claude-code, ide, codex, agent) that customize tool availability and prompts for different use cases.

Serena maintains an in-memory file buffer that tracks open files, pending edits, and file state. The buffer supports atomic transactions (multiple edits composed into a single operation) and provides methods to read, write, and query file content without hitting disk on every operation. The system integrates with language servers to keep symbol information synchronized with buffer state, enabling agents to make multiple edits and see updated symbol information without explicit file saves. The buffer also tracks file metadata (modification time, encoding) and supports rollback of uncommitted changes.

Serena implements a tool architecture with a central tool registry that defines all available tools (FindSymbolTool, FindReferencingSymbolsTool, ReplaceSymbolBodyTool, RenameSymbolTool, file operations, etc.) with JSON schemas for input validation and output typing. The execution pipeline validates tool inputs against schemas, executes the tool, and returns typed outputs. The system supports tool composition (chaining tools together) and error handling with detailed error messages. Tools are context-aware; the active context determines which tools are exposed to the agent.

Serena implements a caching layer that stores language server responses (symbol definitions, references, type information) and symbol metadata to avoid redundant queries. The cache is keyed by file path, symbol name, and query type, and is invalidated when files change. The system uses file modification time tracking to detect external changes and refresh cache entries as needed. For large codebases, the cache can reduce symbol lookup latency from 500ms to <50ms on cache hits.