+
- Serena is under active development! See the latest updates, upcoming features, and lessons learned to stay up to date. -
+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. -
- 
+
+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 +131,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).
-
-
-
-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 +160,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!
-
-
- 
-
@@ -140,5 +130,3 @@ of choice.
``` - -See the [JetBrains Plugin documentation](../02-usage/025_jetbrains_plugin) for usage details. diff --git a/docs/02-usage/025_jetbrains_plugin.md b/docs/02-usage/025_jetbrains_plugin.md index 32c69591..c8af4a14 100644 --- a/docs/02-usage/025_jetbrains_plugin.md +++ b/docs/02-usage/025_jetbrains_plugin.md @@ -14,23 +14,39 @@ leverage the powerful code analysis and editing capabilities of your JetBrains I We recommend the JetBrains plugin as the preferred way of using Serena, especially for users of JetBrains IDEs. +How it works: +1. Install the plugin in your JetBrains IDE +2. Configure Serena to use the JetBrains language backend (see [below](configure-jetbrains)) +3. Open the project you want to work on in your JetBrains IDE and activate it in Serena (see [below](jetbrains-workflow)) +4. Start coding via your MCP client as usual + **Purchasing the JetBrains Plugin supports the Serena project.** The proceeds from plugin sales allow us to dedicate more resources to further developing and improving Serena. - ## Advantages of the JetBrains Plugin 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 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 +* **Enhanced retrieval & refactoring capabilities**: The plugin adds additional [tools](../01-about/035_tools) (e.g. type + hierarchy retrieval, move, find declaration, inline symbol, etc.) + and transforms the underlying mechanisms of shared tools to build upon the IDE's capabilities. +* **Improved multi-agent support**: A single IDE instance naturally serves arbitrarily many agent sessions without requiring additional resources. +* **Enhanced performance**: Faster tool execution thanks to optimized IDE integration. +* **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 +We are also working on additional features like debugging and advanced introspection capabilities, which will be available exclusively through the JetBrains plugin. +:::{note} +With Serena's JetBrains tools, we try to offer the latest features. +As a result, some of them are considered as beta features (see [tool list](../01-about/035_tools)), which may have some quirks. +Please report your experience with these tools if they do not work as expected. +::: + +(configure-jetbrains)= ## Configuring Serena to Use the JetBrains Plugin After installing the plugin, you need to configure Serena to use it. @@ -79,15 +95,16 @@ you will see `Languages: Using JetBrains backend` in the configuration overview. You will also notice that your client will use the JetBrains-specific tools like `jet_brains_find_symbol` and others like it. +(jetbrains-workflow)= ## Workflow Having installed the plugin in your IDE and having configured Serena to use the JetBrains backend, the general workflow is simple: 1. Open the project you want to work on in your JetBrains IDE -2. Open the project's root folder as a project in Serena (see [Project Creation](project-creation-indexing) and [Project Activation](project-activation)) +2. Activate the project's root folder as a project in Serena (see [Project Creation](project-creation-indexing) and [Project Activation](project-activation)) 3. Start using Serena tools as usual -Note that the folder that is open in your IDE and the project's root folder must match. +Note that the project folder that is open in your IDE and the Serena project root folder must match. :::{tip} If you need to work on multiple projects in the same agent session, create a monorepo folder diff --git a/docs/autogen_docs.py b/docs/autogen_docs.py index 5b4ca422..6dfd37f0 100644 --- a/docs/autogen_docs.py +++ b/docs/autogen_docs.py @@ -1,5 +1,6 @@ import logging import os +import re import shutil from pathlib import Path from typing import Optional, List @@ -152,9 +153,10 @@ def autogen_tool_list(target_filename = "01-about/035_tools.md"): with open(target_file, "w") as f: f.write("\n\n") f.write("# Tools\n\n") - f.write("Find the full list of Serena's tools below. \n") + f.write("Find the full list of Serena's tools below.\n\n") f.write("Note that in most configurations, only a subset of these tools will be enabled simultaneously.\n") - f.write("Tools marked as optional are disabled by default.\n\n") + f.write("Tools marked as *optional* are disabled by default.\n\n") + f.write("Tools marked as [BETA] were recently introduced and may not be fully robust yet.\n\n") tools_by_module = ToolRegistry().get_registered_tools_by_module() priority_modules = {"serena.tools.symbol_tools": 1, "serena.tools.jetbrains_tools": 2} @@ -165,16 +167,54 @@ def autogen_tool_list(target_filename = "01-about/035_tools.md"): module = module.replace("serena.tools.", "") text.with_line(f"* **{module}**") for tool in tools: - info = " *(optional)*" if tool.is_optional else "" + info = "" + if tool.is_optional: + info += " *(optional)*" + if tool.is_beta: + info += " [BETA]" text.with_line(f"* `{tool.tool_name}`{info}: {tool.class_docstring}", indent=2) f.write(text.build()) +def autogen_about_intro_features(): + readme_path = Path(__file__).parent.parent / "README.md" + with open(readme_path, "r", encoding="utf-8") as f: + readme_contents = f.read() + + match = re.search(r"April 3, 2026
++ After a full year of work since the first version of Serena, we are excited to announce the release of Serena v1.0! +
++ Since our last update, we have now added support for exciting new retrieval and refactoring tools, especially for users of the JetBrains backend. +
++ We are far from done. Many new features will be coming your way – for both the LSP and JetBrains backends. +
++ Thank you to our contributors, users and customers! +
+
'
+ '