Quick Start Guide
Relevant source files
The following files were used as context for generating this wiki page:
Serena is a semantic code retrieval and refactoring toolkit designed to act as an "IDE for your coding agent." It exposes high-level symbolic tools via the Model Context Protocol (MCP), allowing AI agents to navigate and modify complex codebases with the precision of a human developer using a modern IDE.
This guide details the initialization, configuration, and integration workflows required to connect Serena to various AI clients and manage projects effectively. Sources: README.md:14-25, src/serena/config/serena_config.py:1022-1033
Installation and Initial Setup
Serena is primarily managed using the uv tool. The installation process sets up the serena-agent package and makes the serena command available in the shell.
uv tool install -p 3.13 serena-agent
serena init
The serena init command configures the fundamental settings, defaulting to the Language Server Protocol (LSP) backend. Users can alternatively specify the JetBrains backend using -b JetBrains. Sources: README.md:167-184, src/serena/config/serena_config.py:1022-1033
Backend Options
Serena supports two primary technologies for code analysis:
- Language Servers (LSP): Uses open-source language servers to provide symbolic support for over 40 languages. Sources: README.md:86-103
- JetBrains Plugin: Leverages the JetBrains IDE's deep code analysis for all JetBrains-supported languages. Sources: README.md:105-112
Project Lifecycle and Configuration
Serena operates on a project-based workflow. Every project requires a .serena/project.yml file to define its scope, languages, and specific behaviors.
Automatic Project Registration
When a project is added, Serena can automatically detect the programming language composition and generate the necessary configuration.
The system determines the language composition by scanning source files and sorting them by density to suggest the primary language. Sources: src/serena/config/serena_config.py:356-420
Key Configuration Elements
| Element | Description | Default / Source |
|---|---|---|
language_backend | Defines whether to use LSP or JetBrains. | LSP |
symbol_info_budget | Time budget (seconds) for symbolic info requests. | 10.0 |
projects | List of registered project root paths. | [] |
line_ending | Preferred line ending convention (LF/CRLF/Native). | Native |
Sources: src/serena/config/serena_config.py:730-810, src/serena/config/serena_config.py:112-115
Connecting to AI Clients
Serena acts as an MCP server. To connect it to a client, you must provide a launch command or an SSE URL. Supported clients include Claude Code, Codex, Cursor, and VSCode. Sources: README.md:143-162
Workflow for AI Agents
Once connected, the AI agent follows a specific "Instruction Manual" workflow to ensure efficient resource usage.
Agents are encouraged to read only necessary symbol bodies rather than entire files to remain token-efficient. Sources: src/serena/resources/config/prompt_templates/system_prompt.yml:4-40, src/serena/tools/workflow_tools.py:39-50
Docker Deployment (Experimental)
Serena can be run in isolated containers to provide a safer environment for shell tools and consistent dependencies.
Docker Configuration
Special settings are required in serena_config.yml when running inside Docker:
gui_log_window: Falseweb_dashboard_listen_address: 0.0.0.0web_dashboard_open_on_launch: False
Sources: DOCKER.md:18-30
Volume Mounting
Projects must be mounted as volumes to /workspaces/projects/ to be accessible within the container.
docker run -it -v "$(pwd)":/workspace -p 9121:9121 serena
Sources: DOCKER.md:73-82
Monitoring and Dashboard
Serena provides a web-based dashboard (defaulting to port 24282) for monitoring tool usage, logs, and project status.
Dashboard Components
- Overview: Displays current configuration, active modes, and project list.
- Logs: Real-time stream of agent-tool interactions.
- Advanced Stats: Visualizes tool calls and token consumption (Input vs Output).
- Memory Management: Allows manual editing or deletion of project-specific and global memories.
Sources: src/serena/resources/dashboard/index.html:60-140, src/serena/resources/dashboard/dashboard.js:296-335
Conclusion
Setting up Serena involves installing the serena-agent via uv, initializing the server with a chosen backend, and registering projects to enable symbolic analysis. By leveraging MCP, Serena allows AI agents to perform complex refactorings and code explorations with high precision and resource efficiency. Sources: README.md:167-195, src/serena/resources/config/prompt_templates/system_prompt.yml:45-70