serena

• 🚀 Serena is a powerful, fully-featured coding agent that works directly on your codebase.
• 🔧 Serena integrates with existing LLMs, providing them with essential semantic code retrieval and editing tools!
• 🆓 Serena is free to use. No API keys or subscriptions required!

Q: Can I have a state-of-the-art coding agent without paying (enormous) API costs or constantly purchasing tokens?
A: Yes, you can! By integrating Serena with your favourite (even free) LLM and thereby enabling it to perform coding tasks directly on your codebase.

Here you see Serena implementing a small feature for itself (a better log GUI) with Claude Desktop. Note the smart usage in finding and editing the right symbols.

https://github.com/user-attachments/assets/6eaa9aa1-610d-4723-a2d6-bf1e487ba753

Serena can be integrated with an LLM in several ways:

• by using the model context protocol (MCP).
  Serena provides an MCP server which integrates with Claude (and soon also ChatGPT).
• by using Agno – the model-agnostic agent framework.
  Serena's Agno-based agent allows you to turn virtually any LLM into a coding agent, whether it's provided by Google, OpenAI or DeepSeek (with a paid API key) or a free model provided by Ollama, Together or Anyscale.
• by incorporating Serena's tools into an agent framework of your choice.
  Serena's tool implementation is decoupled from the framework-specific code and can thus easily be adapted to any agent framework.

Serena's semantic code analysis capabilities build on language servers using the widely implemented language server protocol (LSP). The LSP 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! So not only is it free and open-source, it frequently achieves better results than existing solutions that charge a premium.

Language servers provide support for a wide range of programming languages. With Serena, we provide

• direct, out-of-the-box support for:
  • Python
  • Java (Note: startup is slow, initial startup especially so)
  • TypeScript
• indirect support (may require some code changes/manual installation) for:
  • Ruby (untested)
  • Go (untested)
  • C# (untested)

Further languages can easily be supported by providing a shallow adapter for a new language server implementation.

• Is It Really Free to Use?
• What Can I Use Serena For?
• Quick Start
  • MCP Server (Claude Desktop)
  • Agno
• Serena's Tools and Configuration
• Comparison with Other Coding Agents
  • Subscription-Based Coding Agents
  • API-Based Coding Agents
  • Other MCP-Based Coding Agents
• Limitations of MCP Servers
  • Serena Logging
• Onboarding and Memories
• Recommendations on Using Serena
  • Which Model to Choose?
  • Onboarding
  • Before Editing Code
  • Potential Issues in Code Editing
  • Running Out of Context
  • Controlling Tool Execution
  • Structuring Your Codebase
  • Logging, Linting, and Testing
  • General Advice
• Acknowledgements
• Customizing Serena
• Full List of Tools

Yes! Even the free tier of Anthropic's Claude has support for MCP Servers, so you can use Serena with Claude for free. Presumably, the same will soon be possible with ChatGPT Desktop once support for MCP servers is added.
Through Agno, you furthermore have the option to use Serena with a free/open-weights model.

Serena is Oraios AI's contribution to the developer community.
We use it ourselves on a regular basis.

We got tired of having to pay multiple IDE-based subscriptions (such as Windsurf or Cursor) that forced us to keep purchasing tokens on top of the chat subscription costs we already had. The substantial API costs incurred by tools like Claude Code, Cline, Aider and other API-based tools are similarly unattractive. We thus built Serena with the prospect of being able to cancel most other subscriptions.

You can use Serena for any coding tasks – analyzing, planning, editing and so on. Serena can read, write and execute code, read logs and the terminal output. "Vibe coding" is possible, and if you want to almost feel like "the code no longer exists", you may find Serena even more adequate for vibing than an agent inside an IDE (since you will have a separate GUI that really lets you forget).

1. Install uv (instructions here)

2. Clone the repository to /path/to/serena.

3. Create a configuration file for your project, say myproject.yml based on the template in myproject.demo.yml.

4. Configure the MCP server in your client.
   For Claude Desktop, go to File / Settings / Developer / MCP Servers / Edit Config, which will let you open the json file claude_desktop_config.json. Add the following (with adjusted paths) to enable Serena:

   {
       "mcpServers": {
           "serena": {
               "command": "/abs/path/to/uv",
               "args": ["run", "--directory", "/abs/path/to/serena", "serena-mcp-server", "/abs/path/to/myproject.yml"]
           }
       }
   }

   When using paths containing backslashes on Windows, be sure to escape them correctly (\\).

That's it! Save the config and then restart Claude Desktop.
⚠️ Be sure to fully quit the application, as closing Claude will just minimize it to the system tray – at least on Windows.

After restarting, you should Serena's tools in your chat interface (notice the small hammer icon).

Note that Serena is always configured for a single project. To use it for another, you will have to write a new configuration file, adjust the configuration to point to it and then restart the client.

For more information on MCP servers with Claude Desktop, see the official quick start guide.

Agno is a model-agnostic agent framework that allows you to use Serena with a large number of underlying LLMs.

While Agno is not yet entirely stable, we chose it, because it comes with its own open-source UI, making it easy to directly use the agent using a chat interface.

Here's how it works (see also Agno's documentation):

1. Download the agent-ui code with npx

   npx create-agent-ui@latest

   or, alternatively, clone it manually:

   git clone https://github.com/agno-agi/agent-ui.git
   cd agent-ui 
   pnpm install 
   pnpm dev

2. Install serena with the optional requirements:

   # You can also only select agno,google or agno,anthropic instead of all-extras
   uv pip install --all-extras -e .

3. Copy .env.example to .env and fill in the API keys for the provider(s) you intend to use.

4. Start the agno agent app with

   uv run python scripts/agno_agent.py

   By default, the script uses Claude as the model, but you can choose any model supported by Agno (which is essentially any existing model).

5. In a new terminal, start the agno UI with

   cd agent-ui 
   pnpm dev

   Connect the UI to the agent you started above and start chatting. You will have the same tools as in the MCP server version.

⚠️ IMPORTANT: In contrast to the MCP server approach, tool execution in the Agno UI does not ask for the user's permission. The shell tool is particularly critical, as it can perform arbitrary code execution. While we have never encountered any issues with this in our testing with Claude, allowing this may not be entirely safe. You may choose to disable certain tools for your setup in your Serena project's configuration file (.yml).

Serena combines tools for semantic code retrieval with editing capabilities and shell execution. Find the complete list of tools below.

The use of all tools is generally recommended, as this allows Serena to provide the most value: Only by executing shell commands (in particular, tests) can Serena identify and correct mistakes autonomously.

However, it should be noted that the execute_shell_command tool allows for arbitrary code execution. When using Serena as an MCP Server, clients will typically ask the user for permission before executing a tool, so as long as the user inspects execution parameters beforehand, this should not be a problem. However, if you have concerns, you can choose to disable certain commands in your project's .yml configuration file. If you only want to use Serena purely for analyzing code and suggesting implementations without modifying the codebase, you can consider disabling the editing tools in the configuration, i.e.

• create_text_file
• insert_after_symbol
• insert_at_line
• insert_before_symbol
• replace_symbol_body
• delete_lines.

In general, be sure to back up your work and use a version control system in order to avoid losing any work.

To our knowledge, Serena is the first fully-featured coding agent where the entire functionality is available through an MCP server, thus not requiring API keys or subscriptions.

The most prominent subscription-based coding agents are parts of IDEs like Windsurf, Cursor and VSCode. Serena's functionality is similar to Cursor's Agent, Windsurf's Cascade or VSCode's upcoming agent mode.

Serena has the advantage of not requiring a subscription. A potential disadvantage is that it is not directly integrated into an IDE, so the inspection of newly written code is not as seamless.

More technical differences are:

• Serena is not bound to a specific IDE. Serena's MCP server can be used with any MCP client (including some IDEs), and the Agno-based agent provides additional ways of applying its functionality.
• Serena is not bound to a specific large language model or API.
• Serena navigates and edits code using a language server, so it has a symbolic understanding of the code. IDE-based tools often use a RAG-based or purely text-based approach, which is often less powerful, especially for large codebases.
• Serena is open-source and has a small codebase, so it can be easily extended and modified.

An alternative to subscription-based agents are API-based agents like Claude Code, Cline, Aider, Roo Code and others, where the usage costs map directly to the API costs of the underlying LLM. Some of them (like Cline) can even be included in IDEs as an extension. They are often very powerful and their main downside are the (potentially very high) API costs.

Serena itself can be used as an API-based agent (see the section on Agno above). We have not yet written a CLI tool or a dedicated IDE extension for Serena (and there is probably no need for the latter, as Serena can already be used with any IDE that supports MCP servers). If there is demand for a Serena as a CLI tool like Claude Code, we will consider writing one.

The main difference between Serena and other API-based agents is that Serena can also be used as an MCP server, thus not requiring an API key and bypassing the API costs. This is a unique feature of Serena.

There are other MCP servers designed for coding, like DesktopCommander and codemcp. However, to the best of our knowledge, none of them provide semantic code retrieval and editing tools; they rely purely on text-based analysis. It is the integration of language servers and the MCP that makes Serena unique and so powerful for challenging coding tasks, especially in the context of larger codebases.

The support for MCP Servers in Claude Desktop and the various MCP Server SDKs are relatively new developments, and we found them to be somewhat unstable. Sometimes, Claude Desktop will crash on a tool execution (with an asyncio error or something else of this kind). On the one hand, it can display show error messages that are no of consequence, and on the other, it can fail to show error messages when things fail irrecoverably. Yet we expect these stability issues to improve over time.

The working configuration of an MCP server may vary from platform to platform and from client to client. We recommend always using absolute paths, as relative paths may be sources of errors. The language server is running in a separate sub-process and is called with asyncio – sometimes Claude Desktop lets it crash. If you have Serena's log window enabled, and it disappears, you'll know what happened.

For now, you may have to restart Claude Desktop multiple times, may have to manually cleanup lingering processes, and you may experiences freezes in conversations. Just try again in the latter case. Feel free to open issues if you encounter setup problems that you cannot solve.

To help with troubleshooting, we have written a small GUI utility for logging. We recommend that you enable it through the project configuration (myproject.yml) if you encounter problems. For Claude Desktop, there are also the MCP logs that can help identify issues.

By default, Serena will perform an onboarding process when it is started for the first time for a project. The goal of the process is for Serena to get familiar with the project and to store memories, which it can then draw upon in future interactions.

Memroies are files stored in .serena/memories/ in the project directory, which the agent can choose to read. Feel free to read and adjust them as needed; you can also add new ones manually. Every file in the .serena/memories/ directory is a memory file.

We found the memories to significantly improve the user experience with Serena. By itself, Serena is instructed to create new memories whenever appropriate.

We will continue to collect best practices as the Serena community grows. Below a short overview of things that we learned when using Serena internally.

Most of these recommendations are true for any coding agent, including all agents mentioned above.

To our surprise, Serena seemed to work best with the non-thinking version of Claude 3.7 vs its thinking version (we haven't yet made extensive comparisons to Gemini). The thinking version took longer, had more difficulties in using the tools, and often would just write code without reading enough context.

In our initial experiments, Gemini seemed to work very well. Unfortunately, Gemini does not support the MCP (yet?), so the only way to use it is through an API-key. On the bright side, Gemini is comparatively cheap and can handle huge context lengths.

In the very first interaction, Serena is instructed to perform an onboarding and write the first memory files. Sometimes (depending on the LLM), the files are not written to disk. In that case, just as Serena to write the memories.

In this phase Serena will usually read and write quite a lot of text and thereby fill up the context. We recommend that you switch to another conversation once the onboarding is performed in order to not run out of tokens. The onboarding will only be performed once, unless you explicitly trigger it.

After the onboarding, we recommend that you have a quick look at the memories and, if necessary, edit them or add additional ones.

It is best to start a code generation task from a clean git state. Not only will this make it easier for you to inspect the changes, but also the model itself will have a chance of seeing what it has changed by calling git diff and thereby correct itself or continue working in a followup conversation if needed.

⚠️ Important: since Serena will write to files using the system-native line endings and it might want to look at the git diff, it is important to set git config core.autocrlf to true on Windows. With git config core.autocrlf set to false on Windows, you may end up with huge diffs only due to line endings. It is generally a good idea to enable this git setting on Windows:

git config --global core.autocrlf true

In our experience, LLMs are really bad at counting, i.e. they have problems inserting blocks of code in the right place. Most editing operations can be performed on a symbolic level, allowing this problem is overcome. However, sometimes, line-level insertions are useful.

Serena is instructed to double-check the line numbers and any code blocks that it will edit, but you may find it useful to explicitly tell it how to edit code if you run into problems.

For long and complicated tasks, or tasks where Serena has read a lot of content, you may come close to the limits of context tokens. In that case, it is often a good idea to continue in a new conversation. Serena has a dedicated tool to create a summary of the current state of the progress and all relevant info for continuing it. You can request to create this summary and write it to a memory. Then, in a new conversation, you can just ask Serena to read the memory and continue with the task. In our experience, this worked really well. On the up-side, since in a single session there is no summarization involved, Serena does not usually get lost (unlike some other agents that summarize under the hood), and it is also instructed to occasionally check whether it's on the right track.

Moreover, Serena is instructed to be frugal with context (e.g., to not read bodies of code symbols unnecessarily), but we found that Claude is not always very good in being frugal (Gemini seemed better at it). You can explicitly instruct it to not read the bodies if you know that it's not needed.

Claude Desktop will ask you before executing a tool. For most tools you can just safely click on "Allow for this Chat", especially if all your files are under version control. One exception is the execute_shell_command tool - there you might want to inspect each call individually. We recommend reviewing each call to this command and not enabling it for the whole chat.

Serena uses the code structure for finding, reading and editing code. This means that it will work well with well-structured code but may fail with fully unstructured one (like a God-class with enormous, non-modular functions). Type annotations also help a lot here. The better your code, the better Serena will work. So we generally recommend you to write well-structured, modular and typed code - it will not only help you but also help your AI ;).

Serena cannot debug (no coding assistant can do this at the moment, to our knowledge). This means that for improving the results within an agent loop, Serena needs to acquire information by executing tests, running scripts, performing linting and so on. It is often very helpful to include many log messages with explicit information and to have meaningful tests. Especially the latter often help the agent to self-correct.

We generally recommend to start an editing task from a state where all linting checks and tests pass.

We found that it is often a good idea to spend some time conceptualizing and planning a task before actually implementing it, especially for non-trivial task. This helps both in achieving better results and in increasing the feeling of control and staying in the loop. You can make a detailed plan in one session, where Serena may read a lot of your code to build up the context, and then continue with the implementation in another (potentially after creating suitable memories).

We built Serena on top of multiple existing open-source technologies, the most important ones being:

1. multilspy. A beautifully designed wrapper around language servers following the LSP. It was not easily extendable with the symbolic logic that Serena required, so instead of incorporating it as dependency, we copied the source code and adapted it to our needs.
2. Python MCP SDK
3. Agno and the associated agent-ui, which we use to allow Serena to work with any model, beyond the ones supporting the MCP.
4. All the language servers that we use through multilspy.

Without these projects, Serena would not have been possible (or would have been significantly more difficult to build).

It is very easy to extend Serena with your own ideas. Just implement a new Tool by subclassing from serena.agent.Tool. By default, the SerenaAgent will immediately have access to it. We look forward to seeing what the community will come up with! For details on contributing, see here.

Here the full list of Serena's default tools with a short description (the output of uv run serena-list-tools)

• check_onboarding_performed: Checks whether the onboarding was already performed.
• create_text_file: Creates/overwrites a file in the project directory.
• delete_lines: Deletes a range of lines within a file.
• delete_memory: Deletes a memory from Serena's project-specific memory store.
• execute_shell_command: Executes a shell command.
• find_referencing_symbols: Finds symbols that reference the symbol at the given location (optionally filtered by type).
• find_symbol: Performs a global (or local) search for symbols with/containing a given name/substring (optionally filtered by type).
• get_dir_overview: Gets an overview of the top-level symbols defined in all files within a given directory.
• get_document_overview: Gets an overview of the top-level symbols defined in a given file.
• insert_after_symbol: Inserts content after the end of the definition of a given symbol.
• insert_at_line: Inserts content at a given line in a file.
• insert_before_symbol: Inserts content before the beginning of the definition of a given symbol.
• list_dir: Lists files and directories in the given directory (optionally with recursion).
• list_memories: Lists memories in Serena's project-specific memory store.
• onboarding: Performs onboarding (identifying the project structure and essential tasks, e.g. for testing or building).
• prepare_for_new_conversation: Provides instructions for preparing for a new conversation (in order to continue with the necessary context).
• read_file: Reads a file within the project directory.
• read_memory: Reads the memory with the given name from Serena's project-specific memory store.
• replace_symbol_body: Replaces the full definition of a symbol.
• search_in_all_code: Performs a search for a pattern in all code files (and only in code files) in the project.
• summarize_changes: Provides instructions for summarizing the changes made to the codebase.
• think_about_collected_information: Thinking tool for pondering the completeness of collected information.
• think_about_task_adherence: Thinking tool for determining whether the agent is still on track with the current task.
• think_about_whether_you_are_done: Thinking tool for determining whether the task is truly completed.
• write_memory: Writes a named memory (for future reference) to Serena's project-specific memory store.