serena

<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>

* 🚀 Serena is a powerful **coding agent toolkit** that transforms an LLM into a fully-featured agent capable of working **directly on your codebase**.
* :wrench: Serena provides essential **semantic code retrieval and editing tools**, similar to an IDE's capabilities. It extracts code entities at the symbol level and leverages relational structure for precise code manipulation.
* :free: Serena is **free & open-source**, enhancing the capabilities of LLMs you already have access to, without additional charges.

### Demonstration

Here's a demonstration of Serena implementing a small feature for itself (a better log GUI) with Claude Desktop. Notice how Serena's tools enable Claude to find and edit the correct symbols.

[Demonstration Video](https://github.com/user-attachments/assets/6eaa9aa1-610d-4723-a2d6-bf1e487ba753)

<p align="center">
  <em>Serena is under active development! Stay up-to-date with the latest updates, upcoming features, and lessons learned.</em>
</p>

<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="roadmap.md">
    <img src="https://img.shields.io/badge/Roadmap-14532d?style=flat&logo=target&logoColor=white&labelColor=14532d" alt="Roadmap" />
  </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>

---

### LLM Integration: Powering Your Coding Agent

Serena provides the necessary [tools](#full-list-of-tools) for coding workflows. However, an LLM is required to orchestrate tool usage and perform the actual work.

For example, **supercharge the performance of Claude Code** with a [one-line shell command](#claude-code).

Serena can be integrated with an LLM in several ways:

*   **Model Context Protocol (MCP):** Serena provides an MCP server that integrates with:
    *   Claude Code and Claude Desktop
    *   IDEs like VSCode, Cursor, or IntelliJ
    *   Extensions like Cline or Roo Code
    *   Many others, including [the ChatGPT app soon](https://x.com/OpenAIDevs/status/1904957755829481737)
*   **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 Anthropic (with a paid API key) or a free model provided by Ollama, Together, or Anyscale.
*   **Custom Agent Frameworks:** Incorporate Serena's tools into an agent framework of your choice. Serena's tool implementation is decoupled from framework-specific code, making it easily adaptable.

### Programming Language Support & Semantic Analysis

Serena's semantic code analysis capabilities are built on **language servers** using the widely implemented Language Server Protocol (LSP). The LSP provides versatile code querying and editing functionalities based on a symbolic understanding of the code.

Equipped with these capabilities, Serena discovers and edits code just like a seasoned developer using an IDE. Serena can efficiently find the right context and do the right thing, even in very large and complex projects! It's free and open-source, and often achieves better results than existing premium solutions.

Language servers provide support for a wide range of programming languages. Serena provides:

*   **Direct, Out-of-the-Box Support:**
    *   Python
    *   TypeScript/Javascript (currently has some instability issues; we are working on it)
    *   PHP
    *   Go (requires `go` and `gopls` to be installed)
    *   Rust
    *   C# (requires .NET to be installed. We switched the underlying language server recently; please report any issues you encounter)
    *   Java (*Note*: Startup is slow, especially the initial startup. There may be issues with Java on macOS and Linux; we are working on it.)
    *   Elixir (Requires NextLS and Elixir install; **Windows not supported** - Next LS does not provide Windows binaries)
    *   Clojure
    *   C/C++ (You may experience issues with finding references; we are working on it)
*   **Indirect Support (May Require Code Changes/Manual Installation):**
    *   Ruby (untested)
    *   Kotlin (untested)
    *   Dart (untested)

    These languages are supported by the language server library, but we haven't explicitly tested whether the support works flawlessly.

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

---

## Table of Contents

<!-- Created with markdown-toc -i README.md -->
<!-- Install it with npm install -g markdown-toc -->

<!-- toc -->

- [What Can I Use Serena For?](#what-can-i-use-serena-for)
- [Free Coding Agents with Serena](#free-coding-agents-with-serena)
- [Quick Start](#quick-start)
  * [Running the Serena MCP Server](#running-the-serena-mcp-server)
    + [Usage](#usage)
        * [Local Installation](#local-installation)
      - [Using uvx](#using-uvx)
      - [Using Docker (Experimental)](#using-docker-experimental)
    + [SSE Mode](#sse-mode)
    + [Command-Line Arguments](#command-line-arguments)
  * [Configuration](#configuration)
  * [Project Activation & Indexing](#project-activation--indexing)
  * [Claude Code](#claude-code)
  * [Claude Desktop](#claude-desktop)
  * [Other MCP Clients (Cline, Roo-Code, Cursor, Windsurf, etc.)](#other-mcp-clients-cline-roo-code-cursor-windsurf-etc)
  * [Agno Agent](#agno-agent)
  * [Other Agent Frameworks](#other-agent-frameworks)
- [Detailed Usage and Recommendations](#detailed-usage-and-recommendations)
  * [Tool Execution](#tool-execution)
    + [Shell Execution and Editing Tools](#shell-execution-and-editing-tools)
  * [Modes and Contexts](#modes-and-contexts)
    + [Contexts](#contexts)
    + [Modes](#modes)
    + [Customization](#customization)
  * [Onboarding and Memories](#onboarding-and-memories)
  * [Prepare Your Project](#prepare-your-project)
    + [Structure Your Codebase](#structure-your-codebase)
    + [Start from a Clean State](#start-from-a-clean-state)
    + [Logging, Linting, and Automated Tests](#logging-linting-and-automated-tests)
  * [Prompting Strategies](#prompting-strategies)
  * [Potential Issues in Code Editing](#potential-issues-in-code-editing)
  * [Running Out of Context](#running-out-of-context)
  * [Combining Serena with Other MCP Servers](#combining-serena-with-other-mcp-servers)
  * [Serena's Logs: The Dashboard and GUI Tool](#serenas-logs-the-dashboard-and-gui-tool)
  * [Troubleshooting](#troubleshooting)
- [Comparison with Other Coding Agents](#comparison-with-other-coding-agents)
  * [Subscription-Based Coding Agents](#subscription-based-coding-agents)
  * [API-Based Coding Agents](#api-based-coding-agents)
  * [Other MCP-Based Coding Agents](#other-mcp-based-coding-agents)
- [Acknowledgements](#acknowledgements)
- [Customizing and Extending Serena](#customizing-and-extending-serena)
- [Full List of Tools](#full-list-of-tools)

<!-- tocstop -->

---

## What Can I Use Serena For?

You can use Serena for any coding tasks – whether it is focused on analysis, planning, designing new components, or refactoring existing ones.

Serena's tools allow an LLM to