Development Setup and Contributing
Relevant source files
The following files were used as context for generating this wiki page:
Serena is an MCP-based IDE toolset designed to provide AI agents with semantic code retrieval, editing, and refactoring capabilities. Contributing to the project involves extending its support for language servers, fixing bugs, or improving documentation. The development environment relies on Python 3.13, the uv package manager, and poe for task execution.
The project emphasizes a symbol-aware approach to code manipulation, distinguishing it from traditional line-based editing. Developers are encouraged to maintain this semantic integrity when adding new features or backends.
Development Environment Setup
The Serena development environment is standardized around uv to ensure consistent dependency management and fast execution.
Python Environment
To set up the local environment, follow these steps:
- Create Virtual Environment: Use
uv venv -p 3.13to initialize the environment with Python 3.13. - Activation:
- Linux/macOS/Git Bash:
source .venv/bin/activate - Windows (CMD/PS):
.venv\Scripts\activate.bator.venv\Scripts\activate.ps1
- Linux/macOS/Git Bash:
- Install Dependencies: Execute
uv sync --extra devto install the project along with development tools.
Sources: CONTRIBUTING.md:21-27, README-dev.md:3-5
Local Installation
For testing Serena as a CLI tool during development, it can be installed locally:
uv tool install --reinstall -p 3.13 .
Sources: CONTRIBUTING.md:29-33
Development Tasks
The project uses poethepoet (poe) to wrap common development workflows:
| Task | Description |
|---|---|
poe format | Runs code auto-formatters to maintain style consistency. |
poe type-check | Executes type checkers (e.g., mypy) to ensure type safety. |
Sources: CONTRIBUTING.md:35-39
Contributing Workflow
Contributors should follow specific guidelines based on the scope of their changes. Isolated additions like new language server support or documentation improvements can be submitted via direct PRs, while significant behavioral changes require prior discussion through issues.
Pull Request Requirements
- Scope: Every PR must cover a single logical change or a set of closely related changes.
- Testing: Tools can be tested without an LLM or MCP harness using the example script at
scripts/demo_run_tools.py.
Sources: CONTRIBUTING.md:5-19, CONTRIBUTING.md:41-46
Release Process
The release workflow is managed through version bumping scripts and GitHub Actions:
The diagram shows the transition from local version bumping to automated PyPI deployment via GitHub workflows.
Sources: README-dev.md:7-22
Docker for Development (Experimental)
Serena provides an experimental Docker setup to isolate the shell tool environment and standardize dependencies across platforms.
Configuration for Containers
When running in Docker, several global settings must be adjusted in serena_config.yml:
gui_log_window: False: Disables the GUI window unsupported in containers.web_dashboard_listen_address: 0.0.0.0: Allows external access to the dashboard.web_dashboard_open_on_launch: False: Prevents the container from attempting to open a browser.
Docker Compose Services
serena: Production-like mode for use as an MCP server.serena-dev: Development mode with source code volumes mounted.
Sources: DOCKER.md:1-40, DOCKER.md:72-85
System Architecture and Configuration
The architecture is governed by a multi-layered configuration system defined primarily in src/serena/config/serena_config.py.
Configuration Hierarchy
Serena resolves configuration through several levels:
- Global Config:
~/.serena/serena_config.yml(Global defaults). - Project Config:
.serena/project.yml(Per-project settings). - Local Project Config:
.serena/project.local.yml(Developer-specific overrides, typically git-ignored). - CLI/MCP Overrides: Arguments passed during server launch.
Sources: src/serena/config/serena_config.py:348-360, src/serena/config/serena_config.py:646-665
Path Management
The SerenaPaths class manages the directory structure for user data:
This diagram represents the singleton responsible for locating user-defined templates, modes, and global memories.
Sources: src/serena/config/serena_config.py:65-128
Memory Maintenance Standards
For developers contributing to the memory system or adding "onboarding" logic, specific maintenance principles apply to ensure memories remain useful for AI agents.
Discovery and Structure
- Root Entry: Agents should start with
mem:core, which serves as the graph root for project information. - Progressive Discovery: Memories must reference others using the
mem:prefix (e.g.,mem:frontend/core). - Style: Use dense agent notes rather than prose. Prioritize invariants and terse bullets over context or examples.
Sources: src/serena/resources/memory_maintenance.md:3-23
Add/Update Thresholds
Developers should only update memories with stable, non-obvious project conventions. Avoid adding:
- Quick-read facts or generic framework knowledge.
- Volatile line-level details.
- One-off task notes.
Sources: src/serena/resources/memory_maintenance.md:25-30
Conclusion
Contributing to Serena requires a firm understanding of its symbolic approach to code analysis. By following the standardized setup using uv and adhering to the tiered configuration and memory maintenance guidelines, developers can ensure their contributions maintain the project's reliability and efficiency for AI-driven development workflows.