Serena for Serena

The tightest loop for working on Serena is Serena itself: point your coding agent at your development checkout, and every change you make is immediately the server you are using. The first time you fix a tool, restart, and feel the fix under your own hands, the loop makes sense for good. This page covers the two skills that make that loop work — choosing which Serena you run (and how to run a specific branch when the work calls for it), and letting the diagnostics tools tell you what an edit did.

Which Serena you run

For everyday use — including while working on Serena — run current main. It is where every fix lands first, and using it daily is the cheapest way to notice a regression before a release does. From a checkout tracking main, the persistent install CONTRIBUTING.md describes keeps it fresh:

git pull && uv tool install --reinstall -p 3.13 .

Your MCP clients launch serena by name and always get an up-to-date main.

Running the server from a specific branch

Two situations call for a branch instead: testing a change you are making, and trying a branch someone else has proposed. In both, leave the main install alone.

Your own checkout

Scope the branch to a separate client entry:

{
  "mcpServers": {
    "serena-dev": {
      "command": "uv",
      "args": ["run", "--directory", "/abs/path/to/your/serena", "serena", "start-mcp-server"]
    }
  }
}

uv run rebuilds the package from the tree on launch, so what runs is exactly the code that is checked out — switch branches, restart the server, and you are testing the other branch. No install step in between.

A remote branch, without cloning

To try a pull request you are reviewing, uvx can run it straight from git:

uvx --from git+https://github.com/<owner>/serena@<branch> serena start-mcp-server

This path ignores the lockfile, which is exactly why the project pins its dependencies to exact versions — the git install resolves to the same environment anyway.

Why not uv tool install . from the branch

The persistent install holds a single slot per tool name, so installing a branch that way replaces your main-based Serena for every client that launches it by name — and it stays replaced after you have moved on. The --directory form keeps the branch scoped to the one client entry that asked for it.

Restart semantics

Configuration is read at startup, so config changes need a server restart; a language can be added to a running instance from the dashboard. The FAQ covers the details.

Letting diagnostics do the checking

Serena’s language servers already know what is wrong with a file. The diagnostics tools expose that, and for the inner loop they are much cheaper than a build or a test run.

Ask for a file’s diagnostics

get_diagnostics_for_file returns a file’s diagnostics grouped by severity and by the symbol they belong to, with a min_severity filter (error, warning, information, hint) — raise the threshold and hint-level noise disappears. Reach for it after a series of edits, before spending minutes on poe test.

The editing tools report their own damage

Every editing tool checks the diagnostics delta of its edit and reports newly introduced warning-or-higher findings in its result — not the file’s pre-existing noise, only what the edit itself caused. An agent using Serena sees the consequence of each change at the moment it makes it, which is the difference between fixing one mistake and discovering twelve at build time. The machinery is EditingToolWithDiagnostics in serena.tools.tools_base.

See both in five minutes

scripts/demo_diagnostics.py creates a temporary file in this repository, introduces a warning, shows file- and symbol-level diagnostics, then makes a second flawed edit and demonstrates that only the new warning is reported.