diff --git a/README.md b/README.md index c0d8146..52262eb 100644 --- a/README.md +++ b/README.md @@ -3,9 +3,9 @@

-> **:rocket: Serena is a powerful, fully-featured coding agent that works directly on your codebase! -> :wrench: Serena integrates with existing LLMs and provides them with essential semantic code retrieval and editing tools! -> :free: Serena is free to use. No additional API keys or subscriptions required!** +> * :rocket: **Serena is a powerful, fully-featured coding agent that works directly on your codebase.** +> * :wrench: **Serena integrates with existing LLMs and provides them with essential semantic code retrieval and editing tools!** +> * :free: **Serena is free to use. No additional 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? @@ -16,9 +16,9 @@ to perform coding tasks directly on your codebase. 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](https://x.com/OpenAIDevs/status/1904957755829481737)). - * by using **Agno – the model-agnostic agent framework**. + * 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 from Google, OpenAI or DeepSeek (with a paid API key) - or completely free like Ollama, Together or Anyscale. + or completely, e.g. Ollama, Together or Anyscale. 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 @@ -31,35 +31,28 @@ than existing solutions that charge a premium. ## Is It Really Free? -Yes! Even the free tier of Anthropic's Claude has support for MCP Servers, so you can use Serena there. -Presumably, the same will be true for ChatGPT Desktop once they add support for MCP servers. -But we do recommend to buy the Claude Pro subscription for 20$ per month as this way the rate -limits are much higher. +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](https://oraios-ai.de/)'s contribution to the developer community. We use it ourselves every day. +Serena is [Oraios AI](https://oraios-ai.de/)'s contribution to the developer community. +We use it ourselves on a regular basis. We got tired of having to pay multiple -subscriptions (Cursor, Windsurf) that forced us to keep purchasing tokens on top of the subscription costs. -We also got tired of paying the huge API costs from Claude Code, Cline, Aider and other API-based tools. -This is why we built serena and cancelled most subscriptions. -See below for a more detailed comparison to existing technologies. - -## What if I Do Want to Pay? - -If you want to use your own API key, connect serena to a custom model, -or use it within a paid tool, you can do so. -We decoupled the tools offered by serena from the MCP server implementation, so they can also -be used in any agent framework and with any model. See the section [Serena as Agent](#serena-as-agent). -This way, you can run serena as a command line tool or within a UI of your choice. +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. ## Quick Start -1. Install `uv` if not done yet (instructions [here](https://docs.astral.sh/uv/getting-started/installation/)) +### MCP Server (Claude Desktop) + +1. Install `uv` (instructions [here](https://docs.astral.sh/uv/getting-started/installation/)) 2. Clone the repository to `/path/to/serena`. -3. Create a configuration file for your project, say `myproject.yml`. See `myproject.demo.yml` for the structure. - You can just copy it and edit the entries. -4. Configure the mcp server in your client. For example, for Claude Desktop, you need to go to `Settings->Developer->MCP Servers`, - which will let you open a json file. There add the following to enable serena: +3. Create a configuration file for your project, say `myproject.yml` based on the template in [myproject.demo.yml](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: ```json { @@ -72,31 +65,31 @@ This way, you can run serena as a command line tool or within a UI of your choic } ``` -That's it! Save the config, restart Claude (you will have actually terminate the process on windows, just closing the window is not enough), -and you should see the serena mcp tools in your chat interface (the small hammer icon). +When using paths containing backslashes on Windows, be sure to escape them correctly (`\\`). -Note that serena is always configured **for a single project**. To use it for another, you will have to -write a new configuration file and adjust the config in the MCP client (don't forget to restart after). +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). +You should then see the Serena MCP tools in your chat interface (notice the small hammer icon). -For more info on MCP servers with Claude Desktop see [here](https://modelcontextprotocol.io/quickstart/user). +Note that Serena is always configured *for a single project*. To use it for another, you will have to +write a new configuration file and adjust the config in the MCP client. -## Serena as Agent +For more information on MCP servers with Claude Desktop, see [the official quick start guide](https://modelcontextprotocol.io/quickstart/user). -In the agent mode, serena can be used with any model, including the currently popular (and SOTA in coding) +### Agno + +With Agno, Serena can be used with any model, including the currently popular (and SOTA in coding) Gemini-2.5-pro. ... -## Getting Started +## Developer Environment Setup -You can have a local uv or docker-interpeter based setup. The repository is also -configured to seamlessly working within a GitHub Codespace. See the instructions +You can have a local setup via `uv` or a docker interpeter-based setup. +The repository is also configured to seamlessly work within a GitHub Codespace. See the instructions for the various setup scenarios below. Independently of how the setup was done, the virtual environment can be -created with `uv venv` and -activated with -`source .venv/bin/activate` and the various tasks like formatting, testing, and documentation building +created and activated via `uv` (see below), and the various tasks like formatting, testing, and documentation building can be executed using `poe`. For example, `poe format` will format the code, including the notebooks. Just run `poe` to see the available commands. @@ -106,7 +99,7 @@ You can install a virtual environment with the required as follows 1. Create a new virtual environment: `uv venv` 2. Activate the environment: - * On Unix or MacOS: `source .venv/bin/activate` + * On Linux/Unix/macOS: `source .venv/bin/activate` * On Windows: `.venv\Scripts\activate.bat` 3. Install the required packages: `uv pip install -e ".[dev]"` @@ -127,46 +120,9 @@ docker run -it --rm -v "$(pwd)":/workspace serena You can also just run `bash docker_build_and_run.sh`, which will do both things for you. -Note: for the WSL subsystem on Windows you might need to adjust the path for the +Note: For the Windows subsystem for Linux (WSL), you may need to adjust the path for the volume. -## Model Context Protocol (MCP) Server - -Serena's functionality is intended to be used via the model context protocol (MCP), -which allows for easy integration into applications like Claude Desktop and IDEs. - -### Project Configuration File - -The first step is to create a `.yml` configuration file for the project you want -Serena to work on: - -Copy `myproject.demo.yml` to `myproject.yml` and adjust the settings to your project. - -### MCP Server Configuration - -Tools like Claude Desktop need to be informed about the MCP server. -They typically start the server themselves and only need to be informed how to start -the server. -This is typically done by providing a configuration file in JSON format as follows, - -```json -{ - "mcpServers": { - "serena": { - "command": "/path/to/uv", - "args": ["run", "--directory", "/path/to/serena", "serena", "/path/to/myproject.yml"] - } - } -} -``` - -where you must adjust `/path/to/serena` to the actual path of the Serena repository as well as the `.yml` file -for your project configuration. -On Windows, you can specify the path in the format `C:/path/to/serena`. - -**Claude Desktop**: The JSON configuration file can be found via File / Settings / Developer / Edit Config. - Then edit the file named `claude_desktop_config.json`. - ## Contributing Please open new issues for bugs, feature requests and extensions. See more details about the structure and