Retrieval is more even: finding a symbol, outlining a file, finding references, locating declarations and implementations, querying external projects and pulling diagnostics all work on both. But searching project dependencies and type hierarchy belong to the plugin alone.

Interactive debugging is a plugin exclusive too. The agent can set breakpoints, inspect variables, evaluate expressions and control execution through a persistent REPL-style interface.

The conclusion is simple: if you already live in a JetBrains IDE, the paid backend gives noticeably more. If you do not, the free language servers cover the essentials.

Installing

The only hard requirement is uv. Serena brings the rest itself.

After installation the serena command appears in your shell. Then comes initialisation, which doubles as a check that the environment assembled correctly:

By default that sets up the language server backend. With the JetBrains plugin you initialise differently:

The PyPI package is called serena-agent and requires Python from 3.11 up to and including 3.14. Three commands land in your system: serena, serena-agent and serena-hooks - the last one matters later, in the hooks section.

Connecting a Client

For Claude Code there is a command that does the whole setup:

Configuring by hand, the MCP server is added as an ordinary process. For every project at once - at user scope, with the project auto-detected from the working directory:

For the current project only:

You verify the connection with /mcp inside the client. If the server does not come up fast enough, the documentation suggests raising the timeout with an environment variable:

There is also a warning worth reading before you decide Serena "does not work". The documentation admits that recent Claude Code releases and the Opus line became markedly worse at following instructions about third-party tools. It names the reason outright: the built-in tool descriptions take almost sixteen thousand tokens, cannot be adjusted by the user, and create a strong pull towards internal tools. The workaround is to start the client with a system prompt that counteracts that pull:

Two Transports and One Important Limit

By default the server talks over standard streams: the client starts the process itself and speaks to it through stdin and stdout. Nothing needs launching by hand - the client only needs the launch command.

The second mode is streamable HTTP, where you own the server's lifecycle:

The client then connects to http://localhost:9121/mcp. Only local connections are accepted by default; --host opens it up, and the documentation immediately reminds you of the security consequences.

And here is the limit that makes the second mode a poor fit for some: Serena is a stateful server, and only one project can be active at a time. A single instance serving several clients makes sense only when all of them work on the same project. If your agents need different projects, let each start its own server over standard streams.

The older SSE transport is still supported, but the documentation discourages using it.

Contexts and Modes

Serena adapts to a client through two mechanisms, and they should not be conflated.

A context describes the environment the server runs in. It is set at startup and cannot change during a session. Several come predefined:

Three of them - ide, claude-code and grok - are declared single-project. When a project is supplied at startup, the tool set shrinks to what that project needs, and the project-switching tool is disabled as pointless.

Modes refine behaviour per kind of task, and several can be active at once: planning, editing, interactive, one-shot, onboarding, no-onboarding, no-memories, query-projects. They compose from three layers - base_modes in the global configuration, default_modes which can be overridden, and added_modes from the project configuration or the command line.

Here the project is honest about a hole of its own: some modes are semantically incompatible - interactive and one-shot, for instance - and Serena does not block such combinations. Verbatim: "Serena currently does not prevent incompatible combinations; it is up to the user to choose sensible mode configurations."

Both are managed the same way:

The Project: Create, Index, Check

Serena works from a project. The minimal cycle looks like this:

Indexing is not always necessary, but on large projects it saves waiting: it pre-caches symbol information so the first tool call does not stall on a cold language server. It is done once - afterwards the index updates itself as files change. With the JetBrains plugin indexing is unnecessary altogether: the IDE handles it.

Data lands in two places. Global data goes to ~/.serena, and the path is overridden by SERENA_HOME. Project data goes to a .serena folder inside the project itself.

The second location is configurable if you would rather not keep service folders inside repositories:

The lookup order on project load is thought through: first the configured path, then the familiar .serena in the project root, and only if neither exists is a new folder created at the configured path. Existing projects keep working after the setting changes.

The Tools

Tools are grouped by purpose, and knowing the groups helps more than memorising the whole list.

Symbol search and navigation. find_symbol locates a symbol, get_symbols_overview shows a file's structure without reading it whole, find_referencing_symbols finds every reference, find_declaration and find_implementations do what their names say.

Symbolic editing. replace_symbol_body swaps a symbol's body, insert_after_symbol and insert_before_symbol place code next to it, rename_symbol renames properly rather than by find-and-replace.

Diagnostics. get_diagnostics_for_file and get_diagnostics_for_symbol return what your editor underlines.

Memory. write_memory, read_memory, list_memories, edit_memory, rename_memory, delete_memory.

Basic utilities. search_for_pattern, replace_content, list_dir, find_file, read_file, execute_shell_command. The README notes separately that inside an agentic harness such as Claude Code or Codex these are usually disabled by default: the harness already has its own.

Working with projects. activate_project, query_project for reading from neighbouring projects, list_queryable_projects, restart_language_server, get_current_config.

An exact tool count cannot be given, and that is not an evasion. The set depends on the context, the enabled modes and the chosen backend: single-project contexts trim it to what the project needs, no-memories switches off memory work, and the JetBrains plugin carries tools the language servers do not have. User reports show both nineteen loaded tools and forty-three - both are true for their conditions.

Seeing what is available to you is easiest through Serena itself:

Memory and Onboarding

Serena has its own memory mechanism: the agent records knowledge about the project and retrieves it in later sessions. It is stored as markdown files inside the project folder.

On the first onboarding Serena seeds a memory_maintenance memory describing the conventions the others should follow, and instructs the agent to read it before writing any of its own. Entries can reference each other through mem:NAME, references survive renames, and the state can be checked with serena memories check.

The README notes that many users combine Serena's memory with their agent's own facilities - the same AGENTS.md files - and that the mechanism is easy to disable if you already have one.

Hooks: Reminding the Agent That Tools Exist

This is the most interesting part of the project, because it treats a behavioural problem rather than a technical one.

Agents drift. At the start of a session they remember the symbolic tools; half an hour later they slide back to grep and reading files whole, simply because that is what their built-in half is used to. Serena answers with a separate executable, serena-hooks, and four commands:

They are wired in through client settings. For Claude Code that is .claude/settings.json in the project or ~/.claude/settings.json globally:

The documentation recommends hooks insistently - and marks them honestly in the same breath: "While recommended, hooks are an alpha feature." Alpha means what it says: it will not always behave the way you want. Users have already hit cases where the reminder fired on reading a README or a log file, where symbolic tools do not apply, and where it blocked an ordinary read with a message about too many consecutive read calls.

Other Ways to Run It

If installing into your system is unappealing, there are options.

The latest source without an install, through uvx:

This used to be the main way, but it has a cost: every new commit in the repository triggers a re-synchronisation, sometimes a slow one. The documentation now prefers a regular install and suggests this route only if the sync is fast enough for you.

From a clone:

Docker - for isolation when shell commands run, and to avoid installing language servers locally:

Projects inside the container are addressed as /workspaces/projects/my-project. This route has limitations, documented separately.

And Nix, if you have flakes enabled:

What the Project Admits About Itself

The list is honest, and it is better known in advance.

Hooks are alpha. Recommended, but capable of surprising you.

Incompatible modes are not blocked. Checking the combination is on you.

C and C++ need preparation. A compile_commands.json at the repository root is required - without it cross-file reference finding does not work. And there sits a fundamental limitation of both supported servers: files created by external means after the language server starts are not indexed automatically. References to them will not resolve until the file is opened somehow, or until the compilation database is updated and the server restarted. None of this applies to the JetBrains plugin.

One active project. The limit is architectural, and it decides how you deploy the server for several agents.

Extra dependencies. Some languages need additional pieces installed by hand for the language server backend.

How the Project Measures Itself

Serena's approach to evaluation is unusual, and it is worth stating plainly, because it is not a benchmark in the customary sense.

The project starts from the premise that the tool's real users are agents rather than people: they are the ones actually using these tools. So the authors wrote an evaluation prompt that has an agent perform about twenty routine development tasks and compare working with Serena against working without it - on workflow effects, reliability and unique capabilities. The evaluation requires recording neutral and negative deltas as well as positive ones.

The README carries three verdicts - from Opus 4.6 in Claude Code on a large Python codebase, from GPT 5.4 in Codex CLI on Java, and from GPT 5.4 in Copilot CLI on a multi-language monorepo. The most substantial line from there: cross-file renames, moves and reference lookups that would cost "8-12 careful, error-prone steps" collapse into one atomic call.

How to treat this. It is an evaluation, not a measurement: the README publishes no run counts, no confidence intervals and no raw data, and the wording belongs to the models that were asked. What is useful is something else - the method is described and the project invites you to repeat it on your own codebase. That is more honest than percentages with no stated origin.

Mistakes of the First Encounter

Installing from an MCP or plugin marketplace. The README forbids it in a dedicated warning: the commands there are outdated. Install through uv.

Expecting plugin capabilities from language servers. Moving symbols and files, inlining, removing unused code, type hierarchy and debugging belong to the JetBrains backend alone. The free option covers retrieval, symbolic editing and symbol renaming - but not everything.

Not indexing a large project. The first symbolic call will stall on a cold language server, and the tool will look slow.

Enabling incompatible modes. interactive together with one-shot is the documentation's own example, and nobody will stop you.

Assuming the tool count is fixed. The set depends on context, modes and backend; check it with serena tools list --all rather than from someone else's screenshot.

Running one server for several projects. Only one project can be active; different projects need different instances.

Forgetting compile_commands.json in C and C++. Without it cross-file reference finding will not work, and files created later will not index themselves.

Deciding the agent "does not want" to use the tools. More likely it is drifting back to the built-ins - which is exactly what the hooks and the Claude Code system prompt exist for.

To put it in one sentence: Serena turns editing code from working with text into working with structure, and the hard part is not the install but getting the agent to actually use what it was given.

Sources

This article was checked against the oraios/serena repository (branch main) and the official documentation on 25 August 2026: the README, pyproject.toml, the guides on running, connecting clients, configuration and the project workflow, the C and C++ guide, and the tool sources under src/serena/tools/. The project moves fast and the main branch runs ahead of the last release, so check the tool list and the set of contexts with Serena's own commands rather than from this article.

• GitHub: oraios/serena
• Serena documentation
• Running and commands
• Connecting clients
• Configuration
• The project workflow
• Language support
• The JetBrains plugin
• Evaluation methodology
• The C and C++ guide
• Tool sources
• The plugin on the JetBrains marketplace