serena/CONTRIBUTING.md

Contributing to Serena

Serena is under active development. We are just discovering what it can do and where the limitations lie.

Feel free to share your learnings by opening open new issues, feature requests and extensions.

Developer Environment Setup

You can have a local setup via uv or a docker interpreter-based setup. The repository is also configured to seamlessly work within a GitHub Codespace. See the instructions for the various setup scenarios below.

Independently of how the setup was done, the virtual environment can be created and activated via uv (see below), and the various tasks like formatting, testing, and documentation building can be executed using poe. For example, poe format will format the code, including the notebooks. Just run poe to see the available commands.

Python (uv) setup

You can install a virtual environment with the required as follows

1. Create a new virtual environment: uv venv
2. Activate the environment:
   • On Linux/Unix/macOS: source .venv/bin/activate
   • On Windows: .venv\Scripts\activate.bat
3. Install the required packages with all extras: uv pip install --all-extras -r pyproject.toml -e .

Docker setup

Build the docker image with

docker build -t serena .

and run it with the repository mounted as a volume:

docker run -it --rm -v "$(pwd)":/workspace serena

You can also just run bash docker_build_and_run.sh, which will do both things for you.

Note: For the Windows subsystem for Linux (WSL), you may need to adjust the path for the volume.

Running Tools Locally

The Serena tools (and in fact all Serena code) can be executed without an LLM, and also without any MCP specifics (though you can use the mcp inspector, if you want).

An example script for running tools is provided in scripts/demo_run_tools.py.

Adding a New Supported Language

Serena interacts with code through language servers which are included in the multilspy package. It is rather easy to include a new supported language if an LSP implementation for it exists. You just need to:

1. create a new subclass of LanguageServer
2. add a new value to the Language enum
3. make a new elif case in the LanguageServer.create method
4. write minor tests

The subclasses are typically easy to write, have a look at the PyrightLanguageServer for an example, or at any other implementation to see how non-python dependencies for language servers are handled there. There are also some tips from the multilspy admin here.

⚠️ Important: The LSP allows for lot of optional fields and symbols, so the language servers may differ in some details, even if they follow the LSP. Therefore you should include some code of the new language in test/resources and add tests for symbolic read operations on that code. Have a look at test/multilspy/test_symbol_retrieval.py for an example of such tests for the python LS.