by oraios
A powerful MCP toolkit for coding, providing semantic retrieval and editing capabilities - the IDE for your agent
# Add to your Claude Code skills
git clone https://github.com/oraios/serenaSerena'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.
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
To connect the Serena MCP server to your client, you either
See the section below for information on how to get started.
No comments yet. Be the first to share your thoughts!
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.
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 AL, Ansible, Bash, C#, C/C++, Clojure, Crystal, Dart, Elixir, Elm, Erlang, Fortran, F#, GLSL, Go, Groovy, Haskell, Haxe, 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 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.
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.
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 |
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 |
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 |
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 codebasereplace_content – agent-optimised regex-based and literal text replacementlist_dir / find_file – directory listing and file searchread_file – read files or file chunksexecute_shell_command – run shell commands (e.g. builds, tests, linters)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.
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:
A demonstration of Serena efficiently retrieving and editing code within Claude Code, thereby saving tokens and time. Efficient operations are not only useful for saving costs, but also for generally improving the generated code's quality. This effect may be less pronounced in very small projects, but often becomes of crucial importance in larger ones.
https://github.com/user-attachments/assets/ab78ebe0-f77d-43cc-879a-cc399efefd87
A demonstration of Serena implementing a small feature for itself (a better log GUI) with Claude Desktop. 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
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@latest --prerelease=allow
After su