tiennm99/serena
1
0 Fork 0
mirror of https://github.com/tiennm99/serena.git synced 2026-10-13 02:14:49 +00:00
Code Issues Packages Projects Releases Wiki Activity

Update README and About section with enhanced feature presentation for v1

Browse Source
This commit is contained in:
Michael Panchenko authored and Dominik Jain committed 2026-04-02 17:38:03 +02:00
1 parent bcfec97941
commit 9f63606d7b
3 files changed
+213 -151
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

README.md
+109 -137
View File
@@ -1,46 +1,121 @@
<p align="center" style="text-align:center">
<p align="center" style="text-align:center;">
<img src="resources/serena-logo.svg#gh-light-mode-only" style="width:500px">
<img src="resources/serena-logo-dark-mode.svg#gh-dark-mode-only" style="width:500px">
</p>
* :rocket: Serena is a powerful **coding agent toolkit** capable of turning an LLM into a fully-featured agent that works **directly on your codebase**.
Unlike most other tools, it is not tied to an LLM, framework or an interface, making it easy to use it in a variety of ways.
* :wrench: Serena provides essential **semantic code retrieval and editing tools** that are akin to an IDE's capabilities, extracting code entities at the symbol level and exploiting relational structure. When combined with an existing coding agent, these tools greatly enhance (token) efficiency.
* :free: Serena is **free & open-source**, enhancing the capabilities of LLMs you already have access to free of charge.
<h3 align="center">
Serena is the IDE for your coding agent.
</span>
</h3>
You can think of Serena as providing IDE-like tools to your LLM/coding agent.
With it, the agent no longer needs to read entire files, perform grep-like searches or basic string replacements to find the right parts of the code and to edit code.
Instead, it can use code-centric tools like `find_symbol`, `find_referencing_symbols` and `insert_after_symbol`.
* Serena provides essential **semantic code retrieval, editing and refactoring tools** that are akin to an IDE's capabilities,
operating at the symbol level and exploiting relational structure.
* It integrates with any client/LLM via the model context protocol (**MCP**).
<p align="center">
<em>Serena is under active development! See the latest updates, upcoming features, and lessons learned to stay up to date.</em>
</p>
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.
<p align="center">
<a href="CHANGELOG.md"><img src="https://img.shields.io/badge/Updates-1e293b?style=flat&logo=rss&logoColor=white&labelColor=1e293b" alt="Changelog" /></a>
<a href="lessons_learned.md"><img src="https://img.shields.io/badge/Lessons-Learned-7c4700?style=flat&logo=readthedocs&logoColor=white&labelColor=7c4700" alt="Lessons Learned" /></a>
</p>
Practically, this means that your agent operates **faster, more efficiently and more reliably**, especially in larger and
more complex codebases.
> [!TIP]
> The [**Serena JetBrains plugin**](#the-serena-jetbrains-plugin) has been released!
## Features
## LLM Integration
Serena supports two code intelligence backends:
Serena provides the necessary [tools](https://oraios.github.io/serena/01-about/035_tools.html) for coding workflows, but an LLM is required to do the actual work,
orchestrating tool use.
* **Language servers** implementing the language server protocol (LSP) — the free/open-source alternative.
* **The Serena JetBrains Plugin**, which leverages the capabilities of your JetBrains IDE.
In general, Serena can be integrated with an LLM in several ways:
Language Servers, while very powerful, have inherent limitations.
The JetBrains variant is the more advanced solution, as detailed below. It is also more memory-efficient, especially in
multi-agent scenarios.
* by using the **model context protocol (MCP)**.
Serena provides an MCP server which integrates with
* Claude Code and Claude Desktop,
* terminal-based clients like Codex, Gemini-CLI, Qwen3-Coder, rovodev, OpenHands CLI and others,
* IDEs like VSCode, Cursor or IntelliJ,
* Extensions like Cline or Roo Code
* Local clients like [OpenWebUI](https://docs.openwebui.com/openapi-servers/mcp), [Jan](https://jan.ai/docs/mcp-examples/browser/browserbase#enable-mcp), [Agno](https://docs.agno.com/introduction/playground) and others
* by using [mcpo to connect it to ChatGPT](docs/03-special-guides/serena_on_chatgpt.md) or other clients that don't support MCP but do support tool calling via OpenAPI.
* by incorporating Serena's tools into an agent framework of your choice, as illustrated [here](docs/03-special-guides/custom_agent.md).
Serena's tool implementation is decoupled from the framework-specific code and can thus easily be adapted to any agent framework.
### Language Support
#### Language Servers
When using Serena's language server backend, we provide **support for over 40 programming languages**, including
AL, Ansible, Bash, C#, C/C++, Clojure, Dart, Elixir, Elm, Erlang, Fortran, F# (currently with some bugs), GLSL, Go, Groovy (partial support), Haskell, HLSL, Java, Javascript, Julia, Kotlin, Lean 4, Lua, Luau, Markdown, MATLAB, Nix, OCaml, Perl, PHP, PowerShell, Python, R, Ruby, Rust, Scala, Solidity, Swift, TOML, TypeScript, WGSL, YAML, and Zig.
#### The Serena JetBrains Plugin
The [Serena JetBrains Plugin](https://plugins.jetbrains.com/plugin/28946-serena/)
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).
<a href="https://plugins.jetbrains.com/plugin/28946-serena/"><img src="docs/_static/images/jetbrains-marketplace-button.png"></a>
See our [documentation page](https://oraios.github.io/serena/02-usage/025_jetbrains_plugin.html) for further details and instructions on how to apply the plugin.
### 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 |
| find implementations | -- | yes |
| query external projects | yes | yes |
### 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 |
### 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)
## Serena in Action
@@ -57,51 +132,13 @@ Note how Serena's tools enable Claude to find and edit the right symbols.
https://github.com/user-attachments/assets/6eaa9aa1-610d-4723-a2d6-bf1e487ba753
## 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, Serena 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:
* **Language servers** implementing the language server Protocol (LSP) — the free/open-source alternative.
* **The Serena JetBrains Plugin**, which leverages the powerful code analysis and editing
capabilities of your JetBrains IDE.
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 (like Serena) or at least freely available for use.
With Serena's LSP library, we provide **support for over 40 programming languages**, including
AL, Ansible, Bash, C#, C/C++, Clojure, Dart, Elixir, Elm, Erlang, Fortran, F# (currently with some bugs), GLSL, Go, Groovy (partial support), Haskell, HLSL, Java, Javascript, Julia, Kotlin, Lean 4, Lua, Luau, Markdown, MATLAB, Nix, OCaml, Perl, PHP, PowerShell, Python, R, Ruby, Rust, Scala, Solidity, Swift, TOML, TypeScript, WGSL, YAML, and Zig.
> [!IMPORTANT]
> Some language servers require additional dependencies to be installed; see the [Language Support](https://oraios.github.io/serena/01-about/020_programming-languages.html) page for details.
### The Serena JetBrains Plugin
As an alternative to language servers, the [Serena JetBrains Plugin](https://plugins.jetbrains.com/plugin/28946-serena/)
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).
<a href="https://plugins.jetbrains.com/plugin/28946-serena/"><img src="docs/_static/images/jetbrains-marketplace-button.png"></a>
The plugin offers the most robust and most powerful Serena experience.
See our [documentation page](https://oraios.github.io/serena/02-usage/025_jetbrains_plugin.html) for further details and instructions.
## Quick Start
**Prerequisites**. Serena is managed by *uv*. If you don’t already have it, you need to [install uv](https://docs.astral.sh/uv/getting-started/installation/) before proceeding.
> [!NOTE]
> Some language servers require additional dependencies to be installed; see the [Language Support](https://oraios.github.io/serena/01-about/020_programming-languages.html) page for details.
**Starting the MCP Server**. The easiest way to start the Serena MCP server is by running the latest version from GitHub using uvx.
Issue this command to see available options:
@@ -124,74 +161,9 @@ Follow the link for specific instructions on how to set up Serena for Claude Cod
Please refer to the [user guide](https://oraios.github.io/serena/02-usage/000_intro.html) for detailed instructions on how to use Serena effectively.
## Community Feedback
Most users report that Serena has strong positive effects on the results of their coding agents, even when used within
very capable agents like Claude Code. Serena is often described to be a [game changer](https://www.reddit.com/r/ClaudeAI/comments/1lfsdll/try_out_serena_mcp_thank_me_later/), providing an enormous [productivity boost](https://www.reddit.com/r/ClaudeCode/comments/1mguoia/absolutely_insane_improvement_of_claude_code).
Serena excels at navigating and manipulating complex codebases, providing tools that support precise code retrieval and editing in the presence of large, strongly structured codebases.
However, when dealing with tasks that involve only very few/small files, you may not benefit from including Serena on top of your existing coding agent.
In particular, when writing code from scratch, Serena will not provide much value initially, as the more complex structures that Serena handles more gracefully than simplistic, file-based approaches are yet to be created.
Several videos and blog posts have talked about Serena:
* YouTube:
* [AI Labs](https://www.youtube.com/watch?v=wYWyJNs1HVk&t=1s)
* [Yo Van Eyck](https://www.youtube.com/watch?v=UqfxuQKuMo8&t=45s)
* [JeredBlu](https://www.youtube.com/watch?v=fzPnM3ySmjE&t=32s)
* Blog posts:
* [Serena's Design Principles](https://medium.com/@souradip1000/deconstructing-serenas-mcp-powered-semantic-code-understanding-architecture-75802515d116)
* [Serena with Claude Code (in Japanese)](https://blog.lai.so/serena/)
* [Turning Claude Code into a Development Powerhouse](https://robertmarshall.dev/blog/turning-claude-code-into-a-development-powerhouse/)
## Acknowledgements
### Sponsors
We are very grateful to our [sponsors](https://github.com/sponsors/oraios) who help us drive Serena's development. The core team
(the founders of [Oraios AI](https://oraios-ai.de/)) put in a lot of work in order to turn Serena into a useful open source project.
So far, there is no business model behind this project, and sponsors are our only source of income from it.
Sponsors help us dedicating more time to the project, managing contributions, and working on larger features (like better tooling based on more advanced
LSP features, VSCode integration, debugging via the DAP, and several others).
If you find this project useful to your work, or would like to accelerate the development of Serena, consider becoming a sponsor.
We are proud to announce that the Visual Studio Code team, together with Microsoft’s Open Source Programs Office and GitHub Open Source
have decided to sponsor Serena with a one-time contribution!
<p align="center">
<img src="resources/vscode_sponsor_logo.png" alt="Visual Studio Code sponsor logo" width="220">
</p>
### Community Contributions
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.
### Technologies
We built Serena on top of multiple existing open-source technologies, the most important ones being:
1. [multilspy](https://github.com/microsoft/multilspy).
A library which wraps language server implementations and adapts them for interaction via Python.
It provided the basis for our library Solid-LSP (`src/solidlsp`).
Solid-LSP provides pure synchronous LSP calls and extends the original library with the symbolic logic
that Serena required.
2. [Python MCP SDK](https://github.com/modelcontextprotocol/python-sdk)
3. All the language servers that we use through Solid-LSP.
Without these projects, Serena would not have been possible (or would have been significantly more difficult to build).
## Customizing and Extending Serena
It is straightforward to extend Serena's AI functionality with your own ideas.
Simply implement a new tool by subclassing
`serena.agent.Tool` and implement the `apply` method with a signature
that matches the tool's requirements.
Once implemented, `SerenaAgent` will automatically have access to the new tool.
It is also relatively straightforward to add [support for a new programming language](/.serena/memories/adding_new_language_support_guide.md).
We look forward to seeing what the community will come up with!
For details on contributing, see [contributing guidelines](/CONTRIBUTING.md).
docs/01-about/000_intro.md
+98 -11
View File
@@ -1,14 +1,101 @@
# About Serena
* Serena is a powerful **coding agent toolkit** capable of turning an LLM into a fully-featured agent that works
**directly on your codebase**.
Unlike most other tools, it is not tied to an LLM, framework or an interface, making it easy to use it in a variety of ways.
* Serena provides essential **semantic code retrieval and editing tools** that are akin to an IDE's capabilities,
extracting code entities at the symbol level and exploiting relational structure.
When combined with an existing coding agent, these tools greatly enhance (token) efficiency.
* Serena is **free & open-source**, enhancing the capabilities of LLMs you already have access to free of charge.
Serena is **the IDE for your coding agent**.
Therefore, you can think of Serena as providing IDE-like tools to your LLM/coding agent.
With it, the agent no longer needs to read entire files, perform grep-like searches or string replacements to find and
edit the right code.
Instead, it can use code-centred tools like `find_symbol`, `find_referencing_symbols` and `insert_after_symbol`.
* It provides essential **semantic code retrieval, editing and refactoring tools** that are akin to an IDE's capabilities,
operating at the symbol level and exploiting relational structure.
* It integrates with any client/LLM via the model context protocol (MCP).
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.
## Features
Serena supports two code intelligence backends:
* **Language servers** implementing the language server protocol (LSP) — the free/open-source alternative.
* **The Serena JetBrains Plugin**, which leverages the capabilities of your JetBrains IDE.
Language Servers, while very powerful, have inherent limitations.
The JetBrains variant is the more advanced solution, as detailed below. It is also more memory-efficient, especially in
multi-agent scenarios.
Purchasing the JetBrains plugin supports the continued development of Serena.
### Retrieval
Serena's retrieval tools allow agents to explore codebases at the symbol level, understanding structure and relationships
without reading entire files.
| Capability | Language Server | 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 |
| **find implementations** | -- | yes |
| **query external projects** | yes | yes |
### Refactoring
| Capability | Language Server | 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
Much more token-efficient than default editing tools.
| Capability | Language Server | JetBrains Plugin |
|--------------------------|-----------------|------------------|
| **replace symbol body** | yes | yes |
| **insert after symbol** | yes | yes |
| **insert before symbol** | yes | yes |
| **safe delete** | yes | yes |
### 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 with glob-based file filtering, context lines,
and the option to restrict to code files only. Useful when you don't know the exact symbol name.
- **`list_dir` / `find_file`** -- Directory listing and file search with glob support. Helps agents orient themselves
in unfamiliar projects.
- **`read_file`** -- Read files or file chunks by line range, for cases where symbolic access isn't applicable
(e.g. configuration files, HTML templates).
- **`execute_shell_command`** -- Run shell commands (builds, tests, linters) directly from the agent,
with configurable working directory and output limits.
### Memory Management
Serena provides the functionality of a fully featured agent, and a useful aspect of this is Serena's memory system.
Despite its simplicity, we received positive feedback from many users who tend to combine it with their
agent's internal memory management (e.g., `AGENTS.md` files).
Many other memory management systems for agents exist, and you can easily disable Serena's memory management if you
prefer not to use it.
## 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)
docs/02-usage/025_jetbrains_plugin.md
+6 -3
View File
@@ -23,10 +23,13 @@ The proceeds from plugin sales allow us to dedicate more resources to further de
There are multiple features that are only available when using the JetBrains plugin:
* **External library indexing**: Dependencies and libraries are fully indexed and accessible to Serena
* **No additional setup**: No need to download or configure separate language servers
* **Enhanced retrieval & refactoring capabilities**: The plugin supports additional tools (e.g. type
hierarchy retrieval, move, find declaration, inline symbol, etc.)
* **Improved multi-agent support**: A single IDE instance naturally serves arbitrarily many agent sessions
* **Enhanced performance**: Faster tool execution thanks to optimized IDE integration
* **Multi-language excellence**: First-class support for polyglot projects with multiple languages and frameworks
* **Enhanced retrieval capabilities**: The plugin supports additional retrieval tools for type hierarchy information as well as fast and reliable documentation/type signature retrieval
* **Multi-language excellence** and **framework support**: First-class support for polyglot projects with multiple languages
and frameworks (whatever is recognised by your IDE as a symbol will also be available to Serena)
* **No additional setup**: No need to download or configure separate language servers
We are also working on additional features like a `move_symbol` tool and debugging-related capabilities that
will be available exclusively through the JetBrains plugin.