serena README

The project's README from github.com/oraios/serena. As one markdown file: README.md.

The IDE for Your Coding Agent

discord license

Serena's agent-first tool design involves robust high-level abstractions, distinguishing it from approaches that rely on low-level concepts like line numbers or primitive search patterns.

Practically, this means that your agent operates faster, more efficiently and more reliably, especially in larger and more complex codebases.

[!IMPORTANT] Do not install Serena via an MCP or plugin marketplace! They contain outdated and suboptimal installation commands. Instead, follow our Quick Start instructions.

Quick Demo

https://github.com/user-attachments/assets/8d11646e-b80e-4723-b9d7-32d6101b5f58

:tv: Longer video: Introduction to Serena in 5 Minutes (YouTube)

What Our "End Users" Say

While it is humans who download and set up Serena, our end users are essentially AI agents. As the ones actually applying Serena's tools, they are in the best position to evaluate Serena.

We crafted an unbiased evaluation prompt that leads the agent to perform ~20 routine coding tasks, representative of everyday development work, in order to estimate the value added by Serena's tools when used alongside its own built-ins.

Here's a one-sentence summary of what the agents had to say:

Opus 4.6 (high) in Claude Code on a large Python codebase:

"Serena's IDE-backed semantic tools are the single most impactful addition to my toolkit – cross-file renames, moves, and reference lookups that would cost me 8–12 careful, error-prone steps collapse into one atomic call, and I would absolutely ask any developer I work with to set them up."

GPT 5.4 (high) in Codex CLI on a Java codebase:

"As a coding AI agent, I would ask my owner to add Serena because it gives me the missing IDE-level understanding of symbols, references, and refactorings, turning fragile text surgery into calmer, faster, more confident code changes where semantics matter."

GPT 5.4 (medium) in Copilot CLI on a large, multi-language monorepo:

"As a coding agent, I’d absolutely ask my owner to add Serena because it makes me noticeably sharper and calmer on real code – especially symbol-aware navigation, cross-file refactors, and monorepo dependency jumps – while I still lean on built-ins for tiny text edits and non-code work."

Different agents in different settings independently converge on the same verdict.

Give your agent the tools it has been asking for and add Serena MCP to your client!

See our documentation for the full methodology and much more detailed evaluation results, or run your own evaluation on a project of your choice.

How Serena Works

Serena provides the necessary tools for coding workflows, but an LLM is required to do the actual work, orchestrating tool use.

Serena can extend the functionality of your existing AI client via the model context protocol (MCP). Most modern AI chat clients directly support MCP, including

:tv: See also: Introduction to Serena in 5 Minutes (YouTube)

To connect the Serena MCP server to your client, you either

See the Quick Start section below for information on how to get started.

Programming Language Support & Semantic Analysis Capabilities

Serena provides a set of versatile code querying and editing functionalities based on symbolic understanding of the code. Equipped with these capabilities, your agent discovers and edits code just like a seasoned developer making use of an IDE's capabilities would. Serena can efficiently find the right context and do the right thing even in very large and complex projects!

There are two alternative technologies powering these capabilities:

You can choose either of these backends depending on your preferences and requirements.

Language Servers

Serena incorporates a powerful abstraction layer for the integration of language servers that implement the language server protocol (LSP). The underlying language servers are typically open-source projects or at least freely available for use.

When using Serena's language server backend, we provide support for over 40 programming languages, including Ada / SPARK, AL, Angular, Ansible, Bash, BSL, C#, C/C++, Clojure, Crystal, CUE, Dart, Deno, Elixir, Elm, Erlang, Fortran, F#, GDScript, Gleam, GLSL, Go, Groovy, Haskell, Haxe, HLSL, HTML, Java, JavaScript, JSON, Julia, Kotlin, LaTeX, Lean 4, Lua, Luau, Markdown, MATLAB, mSL, Nextflow, Nix, OCaml, Pascal, Perl, PHP, PowerShell, Python, QML, R, Rego, Ruby, Rust, Scala, SCSS / Sass / CSS, Solidity, Svelte, Swift, SystemVerilog, Terraform, TOML, TypeScript, Vue, WGSL, Wolfram Language, YAML, and Zig.

The Serena JetBrains Plugin

The paid Serena JetBrains Plugin (free trial available) leverages the powerful code analysis capabilities of your JetBrains IDE. The plugin naturally supports all programming languages and frameworks that are supported by JetBrains IDEs, including IntelliJ IDEA, PyCharm, Android Studio, WebStorm, PhpStorm, RubyMine, GoLand, and potentially others (Rider and CLion are unsupported though).

See our documentation page for further details and instructions on how to apply the plugin.

Features

Serena provides a wide range of tools for efficient code retrieval, editing and refactoring, as well as a memory system for long-lived agent workflows.

Given its large scope, Serena adapts to your needs by offering a multi-layered configuration system.

Details

Retrieval

Serena's retrieval tools allow agents to explore codebases at the symbol level, understanding structure and relationships without reading entire files.

Capability Language Servers JetBrains Plugin
find symbol yes yes
symbol overview (file outline) yes yes
find referencing symbols yes yes
search in project dependencies -- yes
type hierarchy -- yes
find declaration yes* yes
find implementations yes** yes
query external projects yes yes
diagnostics/inspections yes yes

*: Will generally not work for declarations in external dependencies.
**: Only available for some languages, limited by the language server functionality.

Refactoring

Without precise refactoring tools, agents are forced to resort to unreliable and expensive search and replace operations.

Capability Language Servers JetBrains Plugin
rename yes (only symbols) yes (symbols, files, directories)
move (symbol, file, directory) -- yes
inline -- yes
propagate deletions (remove unused code) -- yes

Symbolic Editing

Serena's symbolic editing tools are less error-prone and much more token-efficient than typical alternatives.

Capability Language Servers JetBrains Plugin
replace symbol body yes yes
insert after symbol yes yes
insert before symbol yes yes
safe delete yes yes

Interactive Debugging

Exclusive to the JetBrains plugin, Serena supports a highly general debugging tool, which allows an agent to set breakpoints, inspect variables, evaluate expressions and control execution flow via a persistent REPL-style interface.

Basic Features

Beyond its semantic capabilities, Serena includes a set of basic utilities for completeness. When Serena is used inside an agentic harness such as Claude Code or Codex, these tools are typically disabled by default, since the surrounding harness already provides overlapping file, search, and shell capabilities.

  • search_for_pattern – flexible regex search across the codebase
  • replace_content – agent-optimised regex-based and literal text replacement
  • list_dir / find_file – directory listing and file search
  • read_file – read files or file chunks
  • execute_shell_command – run shell commands (e.g. builds, tests, linters)

Memory Management

A memory system is elemental to long-lived agent workflows, especially when knowledge is to be shared across sessions, users and projects. Despite its simplicity, we received positive feedback from many users who tend to combine Serena's memory management system with their agent's internal system (e.g., AGENTS.md files). It can easily be disabled if you prefer to use something else.

Configurability

Active tools, tool descriptions, prompts, language backend details and many other aspects of Serena can be flexibly configured on a per-case basis by simply adjusting a few lines of YAML. To achieve this, Serena offers multiple levels of (composable) configuration:

  • global configuration
  • MCP launch command (CLI) configuration
  • per-project configuration (with local overrides)
  • execution context-specific configuration (e.g. for particular clients)
  • dynamically composable configuration fragments (modes)

Quick Start

Prerequisites. Serena is managed by uv, and installing uv is the only required prerequisite.

[!NOTE] When using the language server backend, some additional dependencies may need to be installed to support certain languages; see the Language Support page for details.

Install Serena. Serena is installed via uv as follows:

uv tool install -p 3.13 serena-agent

After successful installation, the command serena should be available in your shell.

Initialise Serena. To initialise Serena and verify that your setup works correctly, simply run:

serena init

By default, this will set up Serena to use the language server backend. To use the JetBrains backend instead, add the parameters -b JetBrains (see the JetBrains Plugin documentation page for additional usage details).
Either way, you should receive a success message indicating that Serena has been initialised successfully.

Configuring Your Client. To connect Serena to your preferred MCP client, you typically need to configure a launch command in your client. Follow the link for specific instructions on how to set up Serena for Claude Code, Codex, Claude Desktop, MCP-enabled IDEs and other clients (such as local and web-based GUIs).

[!TIP] While getting started quickly is easy, Serena is a powerful toolkit with many configuration options. We highly recommend reading through the user guide to get the most out of Serena.

Specifically, we recommend to read about ...

User Guide

Please refer to the user guide for detailed instructions on how to use Serena effectively.

Acknowledgements

A significant part of Serena, especially support for various languages, was contributed by the open source community. We are very grateful for the many contributors who made this possible and who played an important role in making Serena what it is today.

serena (oraios/serena)

Searching Database…

30.3K ·GitHub
Serena
Что это такое?Бесплатный open-source набор инструментов для MCP, который даёт ИИ-агентам для кода семантические инструменты уровня IDE: поиск кода на уровне символов, редактирование, рефакторинг и отладку. Их девиз: IDE для вашего кодинг-агента.
Это полноценная IDE, которую я устанавливаю, или она подключается к моему существующему ИИ-клиенту?Это не отдельная IDE: это MCP-сервер, который вы подключаете к уже имеющемуся клиенту (Claude Code, Codex, Cursor, JetBrains IDE, Claude Desktop). Код пишет ваша LLM, а Serena поставляет семантические инструменты.
Как запустить её вместе со своим кодинг-агентом?Установите uv (единственная предустановка), установите Serena через uv, чтобы команда 'serena' появилась в вашей оболочке, запустите её один раз для инициализации, затем пропишите в MCP-клиенте команду запуска или HTTP-URL.
Нужно ли что-то ещё, кроме uv?Нет, uv — единственная обязательная предустановка. Но при работе через language-server отдельным языкам могут понадобиться дополнительные зависимости.
Есть ли подводные камни при установке?Ни в коем случае не ставьте Serena из маркетплейсов MCP или плагинов: там устаревшие и неоптимальные команды, пользуйтесь официальным Quick Start. Кроме того, рефакторинг с перемещением и инлайнингом и отладка есть только в платном плагине для JetBrains.
Где она работает: локально или на сервере?Она работает локально рядом с вашим клиентом на Windows, macOS или Linux; альтернативно можно запустить её самостоятельно в режиме HTTP и передать клиенту URL вместо команды запуска.
Она бесплатная, и в чём подвох с плагином для JetBrains?Базовый вариант на language-server — бесплатный и open-source. Альтернативный бэкенд в виде плагина для JetBrains — платный, с бесплатным пробным периодом; лицензию для самой Serena в README не указывают.
Какие языки программирования она поддерживает?Более 40 через language server, включая Python, TypeScript, JavaScript, Java, Go, Rust, C/C++, C#, Kotlin, Ruby и PHP. Бэкенд для JetBrains покрывает всё, что поддерживает ваша JetBrains IDE, кроме Rider и CLion.
Что платный плагин для JetBrains даёт по сравнению с бесплатным бэкендом на language server?Поиск в зависимостях проекта, иерархии типов, переименование файлов и каталогов, рефакторинг с перемещением и инлайнингом, распространение удалений, а также интерактивный отладчик, где агент расставляет точки останова и смотрит значения переменных через интерфейс в стиле REPL.
Зачем Serena система памяти?Она позволяет агентам сохранять знания и обмениваться ими между сессиями, пользователями и проектами в долгоживущих рабочих процессах. Пользователи часто совмещают её с собственной системой агента вроде AGENTS.md, а можно и полностью отключить.
Почему отзывы пользователей там — от ИИ-агентов?Авторы провели непредвзятую оценку: специальный промпт заставлял агентов выполнить около 20 рутинных задач по коду и оценить пользу Serena; модели вроде Opus 4.6 и GPT 5.4 сообщили, что многошаговые рефакторинги сжимались в один атомарный вызов.
What are similar projects?claude-context, openrig, Trail-Code, oh-my-openagent, Baize, claurst, headroom, claude-code
Which topics is it in?language-server, language-server-protocol, code-search, refactoring, jetbrains, vibe-coding, ide, ai-coding, memory, programming, mcp-server, claude
Creator
oraios
Size
13.4 MB
Stars
30.3K
Updated
CommitOct 15Releasev2.0.0Oct 13
Age
1y
Commits · 90 Days