Skip to content
Back to search

serena

A powerful MCP toolkit for coding, providing semantic retrieval and editing capabilities - the IDE for your agent

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/oraios/serena with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/oraios/serena'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/oraios--serena/badge.svg)](/listings/oraios--serena)

HTML

<a href="/listings/oraios--serena"><img src="/api/listings/oraios--serena/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

**Prerequisites**. Serena is managed by *uv*, and [installing uv](https://docs.astral.sh/uv/getting-started/installation/) 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](https://oraios.github.io/serena/01-about/020_programming-languages.html) 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](https://oraios.github.io/serena/02-usage/025_jetbrains_plugin.html) 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](https://oraios.github.io/serena/02-usage/030_clients.html). 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](https://oraios.github.io/serena/02-usage/000_intro.html) to get the most out of Serena. > > Specifically, we recommend to read about ... > * [Serena's project-based workflow](https://oraios.github.io/serena/02-usage/040_workflow.html) and > * [configuring Serena](https://oraios.github.io/serena/02-usage/050_configuration.html).

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 277 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. <p align="center" style="text-align:center;">
  2. <img src="resources/serena-logo.svg#gh-light-mode-only" style="width:500px">
  3. <img src="resources/serena-logo-dark-mode.svg#gh-dark-mode-only" style="width:500px">
  4. </p>
  5. <h3 align="center">
  6. The IDE for Your Coding Agent
  7. </h3>
  8. <div align="center">
  9. <a href="https://discord.com/invite/cVUNQmnV4r"><img src="https://img.shields.io/badge/discord-join-5865F2?style=flat-square&labelColor=0a0e14&logo=discord&logoColor=5865F2" alt="discord"></a>
  10. <a href="https://github.com/oraios/serena/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-GPL--3.0--or--later-b0e8ff?style=flat-square&labelColor=0a0e14" alt="license: GPL-3.0-or-later"></a>
  11. </div>
  12. <br>
  13. * Serena provides essential **semantic code retrieval, editing, refactoring and debugging tools** that are akin to an IDE's capabilities,
  14. operating at the symbol level and exploiting relational structure.
  15. * It integrates with any client/LLM via the model context protocol (**MCP**).
  16. Serena's **agent-first tool design** involves robust high-level abstractions, distinguishing it from
  17. approaches that rely on low-level concepts like line numbers or primitive search patterns.
  18. Practically, this means that your agent operates **faster, more efficiently and more reliably**, especially in larger and
  19. more complex codebases.
  20. > [!TIP]
  21. > Serena v2 with the new **REPL-based agent interface** has been released.
  22. > [Learn more](https://oraios.github.io/serena/01-about/035_tools.html#serena-s-repl-code-execution-based-interface)
  23. > about the new interface and how to [configure it](https://oraios.github.io/serena/02-usage/050_configuration.html#agent-interfaces).
  24. ## Video
  25. <a href="https://www.youtube.com/watch?v=5QN7gN1KYLA"><img src="resources/serena-video-placeholder.png" style="width:500px"></a>
  26. ## What Our "End Users" Say
  27. While it is humans who download and set up Serena, our end users are essentially AI agents.
  28. As the ones actually applying Serena's tools, they are in the best position to evaluate Serena.
  29. We crafted an unbiased evaluation prompt that leads the agent to perform ~20 routine coding tasks,
  30. representative of everyday development work,
  31. in order to estimate the value added by Serena's tools when used alongside its own built-ins.
  32. Here's a one-sentence summary of what the agents had to say:
  33. **Opus 4.6 (high) in Claude Code on a large Python codebase:**
  34. > "Serena's IDE-backed semantic tools are the single most impactful addition to my toolkit – cross-file renames, moves, and reference lookups that
  35. 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."
  36. **GPT 5.4 (high) in Codex CLI on a Java codebase:**
  37. > "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
  38. refactorings, turning fragile text surgery into calmer, faster, more confident code changes where semantics matter."
  39. **GPT 5.4 (medium) in Copilot CLI on a large, multi-language monorepo:**
  40. > "As a coding agent, I’d absolutely ask my owner to add Serena because it makes me noticeably sharper and calmer on
  41. real code – especially symbol-aware navigation, cross-file refactors, and monorepo dependency jumps – while I still lean
  42. on built-ins for tiny text edits and non-code work."
  43. Different agents in different settings independently converge on the same verdict.
  44. _Give your agent the tools it has been asking for and add Serena MCP to your client!_
  45. See our [documentation](https://oraios.github.io/serena/04-evaluation/000_evaluation-intro.html) for the full methodology and much more detailed evaluation results, or run your own evaluation on a project of your choice.
  46. ## How Serena Works
  47. Serena provides the necessary [tools](https://oraios.github.io/serena/01-about/035_tools.html) for coding workflows,
  48. but an LLM is required to do the actual work, orchestrating tool use.
  49. Serena can extend the functionality of your existing AI client via the **model context protocol (MCP)**.
  50. Most modern AI chat clients directly support MCP, including
  51. * terminal-based clients like Claude Code, Codex, OpenCode, or Gemini-CLI,
  52. * IDEs and IDE assistant plugins for VSCode, Cursor and JetBrains IDEs (Copilot, Junie, JetBrains AI Assistant, etc.),
  53. * desktop and web clients like Claude Desktop, Codex App, or OpenWebUI.
  54. <img src="resources/serena-block-diagram.svg">
  55. :tv: See also: [Introduction to Serena in 5 Minutes (YouTube)](https://www.youtube.com/watch?v=5QN7gN1KYLA)
  56. To connect the Serena MCP server to your client, you either
  57. * provide the client with a launch command that allows it to start the MCP server, or
  58. * start the Serena MCP server yourself in HTTP mode and provide the client with the URL.
  59. See the [Quick Start](#quick-start) section below for information on how to get started.
  60. ## Programming Language Support & Semantic Analysis Capabilities
  61. Serena provides a set of versatile code querying and editing functionalities
  62. based on symbolic understanding of the code.
  63. Equipped with these capabilities, your agent discovers and edits code just like a seasoned developer
  64. making use of an IDE's capabilities would.
  65. Serena can efficiently find the right context and do the right thing even in very large and
  66. complex projects!
  67. There are two alternative technologies powering these capabilities:
  68. * **Language servers** implementing the language server protocol (LSP) — the free/open-source alternative
  69. which is used by default.
  70. * **The Serena JetBrains Plugin**, which leverages the powerful code analysis and editing
  71. capabilities of your JetBrains IDE (paid plugin; free trial available).
  72. You can choose either of these backends depending on your preferences and requirements.
  73. ### Language Servers
  74. Serena incorporates a powerful abstraction layer for the integration of language servers that implement the language server protocol (LSP).
  75. The underlying language servers are typically open-source projects or at least freely available for use.
  76. When using Serena's language server backend, we provide **support for over 40 programming languages**, including
  77. Ada / SPARK, AL, Angular, Ansible, Astro, Bash, BSL, C#, C/C++, Clojure, Crystal, CUE, Dart, Deno, Elixir, Elm, Erlang, Fortran, F#, GDScript, Gleam, GLSL, Go, GraphQL, 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, VB.NET, Vue, WGSL, Wolfram Language, YAML, and Zig.
  78. ### The Serena JetBrains Plugin
  79. The paid Serena JetBrains Plugin (free trial available)
  80. leverages the powerful code analysis capabilities of your JetBrains IDE.
  81. The plugin naturally supports all programming languages and frameworks that are supported by JetBrains IDEs,
  82. including IntelliJ IDEA, PyCharm, Android Studio, WebStorm, PhpStorm, RubyMine, GoLand, and potentially others (Rider and CLion are unsupported though).
  83. <a href="https://plugins.jetbrains.com/plugin/28946-serena/"><img src="docs/_static/images/jetbrains-marketplace-button.png"></a>
  84. 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.
  85. ## Features
  86. Serena provides a wide range of tools for efficient code retrieval, editing and refactoring, as well as
  87. a memory system for long-lived agent workflows.
  88. Given its large scope, Serena adapts to your needs by offering a multi-layered configuration system.
  89. <details>
  90. <summary>Details</summary>
  91. ### Retrieval
  92. Serena's retrieval tools allow agents to explore codebases at the symbol level, understanding structure and relationships
  93. without reading entire files.
  94. | Capability | Language Servers | JetBrains Plugin |
  95. |----------------------------------|------------------|------------------|
  96. | find symbol | yes | yes |
  97. | symbol overview (file outline) | yes | yes |
  98. | find referencing symbols | yes | yes |
  99. | search in project dependencies | -- | yes |
  100. | type hierarchy | -- | yes |
  101. | find declaration | yes* | yes |
  102. | find implementations | yes** | yes |
  103. | query external projects | yes | yes |
  104. | diagnostics/inspections | yes | yes |
  105. *: Will generally not work for declarations in external dependencies. <br>
  106. **: Only available for some languages, limited by the language server functionality.
  107. ### Refactoring
  108. Without precise refactoring tools, agents are forced to resort to unreliable and expensive search and replace operations.
  109. | Capability | Language Servers | JetBrains Plugin |
  110. |-------------------------------------------|--------------------|-----------------------------------|
  111. | rename | yes (only symbols) | yes (symbols, files, directories) |
  112. | move (symbol, file, directory) | -- | yes |
  113. | inline | -- | yes |
  114. | propagate deletions (remove unused code) | -- | yes |
  115. ### Symbolic Editing
  116. Serena's symbolic editing tools are less error-prone and much more token-efficient than typical alternatives.
  117. | Capability | Language Servers | JetBrains Plugin |
  118. |------------------------|-------------------|------------------|
  119. | replace symbol body | yes | yes |
  120. | insert after symbol | yes | yes |
  121. | insert before symbol | yes | yes |
  122. | safe delete | yes | yes |
  123. ### Interactive Debugging
  124. Exclusive to the JetBrains plugin, Serena supports a highly general debugging tool,
  125. which allows an agent to set breakpoints, inspect variables, evaluate expressions and control execution flow
  126. via a persistent REPL-style interface.
  127. ### Basic Features
  128. Beyond its semantic capabilities, Serena includes a set of basic utilities for completeness.
  129. When Serena is used inside an agentic harness such as Claude Code or Codex, these tools are typically disabled by default,
  130. since the surrounding harness already provides overlapping file, search, and shell capabilities.
  131. - **`search_for_pattern`** – flexible regex search across the codebase
  132. - **`replace_content`** – agent-optimised regex-based and literal text replacement
  133. - **`list_dir` / `find_file`** – directory listing and file search
  134. - **`read_file`** – read files or file chunks
  135. - **`execute_shell_command`** – run shell commands (e.g. builds, tests, linters)
  136. ### Memory Management
  137. A memory system is elemental to long-lived agent workflows, especially when knowledge is to be shared across
  138. sessions, users and projects.
  139. Despite its simplicity, we received positive feedback from many users who tend to combine Serena's memory management system with their
  140. agent's internal system (e.g., `AGENTS.md` files).
  141. It can easily be disabled if you prefer to use something else.
  142. ### Configurability
  143. Active tools, tool descriptions, prompts, language backend details and many other aspects of Serena
  144. can be flexibly configured on a per-case basis by simply adjusting a few lines of YAML.
  145. To achieve this, Serena offers multiple levels of (composable) configuration:
  146. * global configuration
  147. * MCP launch command (CLI) configuration
  148. * per-project configuration (with local overrides)
  149. * execution context-specific configuration (e.g. for particular clients)
  150. * dynamically composable configuration fragments (modes)
  151. </details>
  152. ## Quick Start
  153. > [!IMPORTANT]
  154. > Do not install Serena via an MCP or plugin marketplace! They contain outdated and suboptimal installation commands.
  155. **Prerequisites**. Serena is managed by *uv*, and [installing uv](https://docs.astral.sh/uv/getting-started/installation/) is the only required prerequisite.
  156. **Install Serena**. Serena is installed via uv as follows:
  157. ```bash
  158. uv tool install -p 3.13 serena-agent
  159. ```
  160. After successful installation, the command `serena` should be available in your shell.
  161. > [!NOTE]
  162. > When using the language server backend, some additional dependencies may need to be installed to support certain languages;
  163. > see the [Language Support](https://oraios.github.io/serena/01-about/020_programming-languages.html) page for details.
  164. **Initialise Serena**. To initialise Serena and verify that your setup works correctly, simply run:
  165. ```bash
  166. serena init
  167. ```
  168. By default, this will set up Serena to use the language server backend. To use the JetBrains backend instead, add the parameters `-b JetBrains`
  169. (see the [JetBrains Plugin documentation page](https://oraios.github.io/serena/02-usage/025_jetbrains_plugin.html) for additional usage details).
  170. Either way, you should receive a success message indicating that Serena has been initialised successfully.
  171. **Configuring Your Client**. To connect Serena to your preferred MCP client, you typically need to [configure a launch command in your client](https://oraios.github.io/serena/02-usage/030_clients.html).
  172. 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).
  173. > [!TIP]
  174. > While getting started quickly is easy, Serena is a powerful toolkit with many configuration options.
  175. > We highly recommend reading through the [user guide](https://oraios.github.io/serena/02-usage/000_intro.html) to get the most out of Serena.
  176. >
  177. > Specifically, we recommend to read about ...
  178. > * [Serena's project-based workflow](https://oraios.github.io/serena/02-usage/040_workflow.html) and
  179. > * [configuring Serena](https://oraios.github.io/serena/02-usage/050_configuration.html).
  180. ## User Guide
  181. 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.
  182. ## Acknowledgements
  183. A significant part of Serena, especially support for various languages, was contributed by the open source community.
  184. We are very grateful for the many contributors who made this possible and who played an important role in making Serena
  185. what it is today.
  186. ## License
  187. Serena is licensed per component: **SolidLSP** (`src/solidlsp`) under the [MIT License](LICENSES/MIT.txt),
  188. the **Serena application** (everything else) under [GPL-3.0-or-later](LICENSES/GPL-3.0-or-later.txt).
  189. Distributions combining both are as a whole subject to the GPL.
  190. See [LICENSE](LICENSE) for the authoritative overview and the
  191. [license documentation](https://oraios.github.io/serena/01-about/060_license.html) for the background.
  192. Contributions require acceptance of our [CLA](CLA.md); see [CONTRIBUTING.md](CONTRIBUTING.md).
  193. <!-- mcp-name: io.github.oraios/serena -->

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.