mirror of
https://github.com/tiennm99/serena.git
synced 2026-10-14 20:17:42 +00:00
Updated readme, addressed comments
This commit is contained in:
MischaPanch authored and Michael Panchenko committed
1 parent
70e0665d28
commit
684f191845
2 files changed
+119
-155
No files matched your search
@@ -8,7 +8,11 @@
|
||||
* :wrench: Serena provides essential **semantic code retrieval and editing tools** that are akin to an IDE's capabilities, extracting code entities at the symbol level and exploiting relational structure. When combined with an existing coding agent, these tools greatly enhance (token) efficiency.
|
||||
* :free: Serena is **free & open-source**, enhancing the capabilities of LLMs you already have access to free of charge.
|
||||
|
||||
### Demonstration
|
||||
### Demonstration 1 - Efficient Operation in Claude Code
|
||||
|
||||
Here is a demonstration of Serena efficiently retrieving and editing code within Claude Code, thereby saving tokens and time. Note that efficient editing and retrieval are not only useful for saving costs, but also for generally improving the quality of the code produced by the LLM.
|
||||
|
||||
### Demonstration 2 - Serena in Claude Desktop
|
||||
|
||||
Here is 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.
|
||||
@@ -43,13 +47,13 @@ For example, **supercharge the performance of Claude Code** with a [one-line she
|
||||
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 Code and Claude Desktop,
|
||||
* Claude Code and Claude Desktop,
|
||||
* Terminal-based clients like Codex, Gemini-CLI, Qwen3-Coder, rovodev, OpenHands CLI and others,
|
||||
* IDEs like VSCode, Cursor or IntelliJ,
|
||||
* Extensions like Cline or Roo Code
|
||||
* Local clients like [OpenWebUI](https://docs.openwebui.com/openapi-servers/mcp), [Jan](https://jan.ai/docs/mcp-examples/browser/browserbase#enable-mcp), Agno and others
|
||||
* Local clients like [OpenWebUI](https://docs.openwebui.com/openapi-servers/mcp), [Jan](https://jan.ai/docs/mcp-examples/browser/browserbase#enable-mcp), [Agno](https://docs.agno.com/introduction/playground) and others
|
||||
* by using [mcpo to connect it to ChatGPT](docs/serena_on_chatgpt.md) or other clients that don't support MCP but do support tool calling.
|
||||
* by using in your custom agent beyond MCP, illustrated in our [Agno tooll integration](#agno-agent).
|
||||
* by incorporating Serena's tools into an agent framework of your choice.
|
||||
* by incorporating Serena's tools into an agent framework of your choice, as illustrated [here](docs/custom_agent.md).
|
||||
Serena's tool implementation is decoupled from the framework-specific code and can thus easily be adapted to any agent framework.
|
||||
|
||||
### Programming Language Support & Semantic Analysis Capabilities
|
||||
@@ -71,13 +75,14 @@ With Serena, we provide
|
||||
* PHP
|
||||
* Go (need to install go and gopls first)
|
||||
* Rust
|
||||
* C# (requires dotnet to be installed. We switched the underlying language server recently, please report any issues you encounter)
|
||||
* C#
|
||||
* Ruby
|
||||
* Swift
|
||||
* Java (_Note_: startup is slow, initial startup especially so. 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 some code changes/manual installation) for:
|
||||
* Ruby (untested)
|
||||
* Kotlin (untested)
|
||||
* Dart (untested)
|
||||
|
||||
@@ -145,66 +150,16 @@ implementation.
|
||||
|
||||
<!-- tocstop -->
|
||||
|
||||
## What Can I Use Serena For?
|
||||
|
||||
Serena is a toolkit, which means it can be used in various ways, depending on your needs and preferences.
|
||||
It can be used as a highly configurable MCP server (application), as a toolkit for building agents (library), or
|
||||
as a framework for building custom integrations based on language servers (the solidlsp package).
|
||||
|
||||
### As MCP Server
|
||||
You can use Serena for any coding tasks – whether it is focussed on analysis, planning,
|
||||
designing new components or refactoring existing ones.
|
||||
Since Serena's tools allow an LLM to close the cognitive perception-action loop,
|
||||
agents based on Serena can autonomously carry out coding tasks from start to finish –
|
||||
from the initial analysis to the implementation, testing and, finally, the commit.
|
||||
|
||||
Serena can read, write and execute code, read logs and the terminal output.
|
||||
While we do not necessarily encourage it, "vibe coding" is certainly 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).
|
||||
|
||||
The application layer of Serena is highly configurable, so you can adapt it to your needs.
|
||||
You can select the tools you want to use, adjust the prompts and even the tool descriptions
|
||||
without writing any code. Serena comes with a CLI to facilitate this.
|
||||
|
||||
See the sections on [configuration](#configuration) and [modes and contexts](#modes-and-contexts)
|
||||
for more information on how to adapt Serena to your needs,
|
||||
and explore the cli with `uvx --from git+https://github.com/oraios/serena serena --help`.
|
||||
|
||||
### As Library
|
||||
While the lower level interfaces should not be considered as stable yet and have no extensive documentation,
|
||||
we do develop them with generality and ease of use in mind.
|
||||
As a result, you can use Serena as a library to build your own agents using the provided tools
|
||||
and language server capabilities.
|
||||
|
||||
|
||||
## Free Coding Agents with Serena
|
||||
|
||||
Even the free tier of Anthropic's Claude has support for MCP Servers, so you can use Serena with Claude for free.
|
||||
You can also connect it to ChatGPT and turn it into a coding agent with the help of mcpo, see [here](docs/serena_on_chatgpt.md).
|
||||
|
||||
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
|
||||
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.
|
||||
|
||||
### Note
|
||||
|
||||
We had built Serena before Claude Code was included in Antrhopic's pro tier. Now the cost saving aspect is less important,
|
||||
but Serena is still valuable as its tools are more powerful than those of Claude Code or other agents that we are aware of (at least for now), so many users
|
||||
find value in using Serena together with Claude Code or similar coding agents.
|
||||
|
||||
## Quick Start
|
||||
|
||||
Serena can be used in various ways, below you will find instructions for selected integrations.
|
||||
|
||||
- If you just want to turn Claude into a free-to-use coding agent, we recommend using Serena through [Claude Code](#claude-code) or [Claude Desktop](#claude-desktop).
|
||||
- If you want to use Gemini or any other model, and you want a GUI experience, you can use [Agno](#agno-agent) or one of the many other GUIs that support MCP servers.
|
||||
- For coding with Claude, we recommend using Serena through [Claude Code](#claude-code) or [Claude Desktop](#claude-desktop). You can also use Serena in most other [terminal-based clients](#other-terminal-based-clients).
|
||||
- If you want a GUI experience outside an IDE, you can use one of the many [local GUIs](#local-guis-and-frameworks) that support MCP servers.
|
||||
You can also connect Serena to many web clients (including ChatGPT) using [mcpo](docs/serena_on_chatgpt.md).
|
||||
- If you want to use Serena integrated in your IDE, see the section on [other MCP clients](#other-mcp-clients---cline-roo-code-cursor-windsurf-etc).
|
||||
- You can use Serena as a library for building your own applications. We try to keep the public API stable, but you should still
|
||||
expect breaking changes and pin Serena to a fixed version if you use it as a dependency.
|
||||
|
||||
Serena is managed by `uv`, so you will need to [install it](https://docs.astral.sh/uv/getting-started/installation/)).
|
||||
|
||||
@@ -271,6 +226,8 @@ Replace `/path/to/your/projects` with the absolute path to your projects directo
|
||||
- No need to install language servers and dependencies locally
|
||||
- Consistent environment across different systems
|
||||
|
||||
Alternatively, use the docker-compose file provided in the repository.
|
||||
|
||||
See the [Docker documentation](DOCKER.md) for detailed setup instructions, configuration options, and known limitations.
|
||||
|
||||
#### SSE Mode
|
||||
@@ -304,7 +261,11 @@ Run with parameter `--help` to get a list of available options.
|
||||
|
||||
### Configuration
|
||||
|
||||
Serena's behavior (active tools and prompts as well as logging configuration, etc.) is configured in four places:
|
||||
Serena is very flexible in terms of configuration. While for most users, the default configurations will work,
|
||||
you can fully adjust it to your needs by editing a few yaml files. You can disable tools, change Serena's instructions
|
||||
(what we denote as the `system_prompt`), adjust the output of tools that just provide a prompt, and even adjust tool descriptions.
|
||||
|
||||
Serena is configured in four places:
|
||||
|
||||
1. The `serena_config.yml` for general settings that apply to all clients and projects.
|
||||
It is located in your user directory under `.serena/serena_config.yml`.
|
||||
@@ -325,20 +286,12 @@ Serena's behavior (active tools and prompts as well as logging configuration, et
|
||||
uvx --from git+https://github.com/oraios/serena serena project generate-yml
|
||||
```
|
||||
(or use the `--directory` command version).
|
||||
4. Through the currently active set of [modes](#modes).
|
||||
4. Through the context and modes. Explore the [modes and contexts](#modes-and-contexts) section for more details.
|
||||
|
||||
|
||||
> ⚠️ **Note:** Serena is under active development. We are continuously adding features, improving stability and the UX.
|
||||
> As a result, configuration may change in a breaking manner. If you have an invalid configuration,
|
||||
> the MCP server or Serena-based Agent may fail to start (investigate the MCP logs in the former case).
|
||||
> Check the [changelog](CHANGELOG.md)
|
||||
> and the configuration templates when updating Serena, adapting your configurations accordingly.
|
||||
|
||||
After the initial setup, continue with one of the sections below, depending on how you
|
||||
want to use Serena.
|
||||
|
||||
You can just ask the LLM to show you the config of your session, Serena has a tool for it.
|
||||
|
||||
### Project Activation & Indexing
|
||||
|
||||
The recommended way is to just ask the LLM to activate a project by providing it an absolute path to, or,
|
||||
@@ -485,71 +438,6 @@ Some of the leading open source GUI technologies offering this are
|
||||
[OpenWebUI](https://docs.openwebui.com/openapi-servers/mcp) and [Agno](https://docs.agno.com/introduction/playground).
|
||||
They allow combining Serena with almost any LLM (including locally running ones) and offer various other integrations.
|
||||
|
||||
### Custom Integrations
|
||||
|
||||
Agno is a model-agnostic agent framework that allows you to turn Serena into an agent
|
||||
(independent of the MCP technology) with a large number of underlying LLMs. While Agno has recently
|
||||
added support for MCP servers out of the box, our Agno integration predates this and is a good illustration of how
|
||||
easy it is to integrate Serena into an arbitrary agent framework.
|
||||
|
||||
Here's how it works (see also [Agno's documentation](https://docs.agno.com/introduction/playground)):
|
||||
|
||||
1. Download the agent-ui code with npx
|
||||
```shell
|
||||
npx create-agent-ui@latest
|
||||
```
|
||||
or, alternatively, clone it manually:
|
||||
```shell
|
||||
git clone https://github.com/agno-agi/agent-ui.git
|
||||
cd agent-ui
|
||||
pnpm install
|
||||
pnpm dev
|
||||
```
|
||||
|
||||
2. Install serena with the optional requirements:
|
||||
```shell
|
||||
# You can also only select agno,google or agno,anthropic instead of all-extras
|
||||
uv pip install --all-extras -r pyproject.toml -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
|
||||
```shell
|
||||
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
|
||||
```shell
|
||||
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.
|
||||
|
||||
|
||||
Here is a short demo of Serena performing a small analysis task with the newest Gemini model:
|
||||
|
||||
https://github.com/user-attachments/assets/ccfcb968-277d-4ca9-af7f-b84578858c62
|
||||
|
||||
|
||||
⚠️ 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`).
|
||||
|
||||
#### Other Agent Frameworks
|
||||
|
||||
It should be straightforward to incorporate Serena into any
|
||||
agent framework (like [pydantic-ai](https://ai.pydantic.dev/), [langgraph](https://langchain-ai.github.io/langgraph/tutorials/introduction/) or others).
|
||||
Typically, you need only to write an adapter for Serena's tools to the tool representation in the framework of your choice,
|
||||
as was done by us for Agno with [SerenaAgnoToolkit](/src/serena/agno.py).
|
||||
|
||||
|
||||
## Detailed Usage and Recommendations
|
||||
|
||||
@@ -622,20 +510,18 @@ When launching Serena, specify modes using `--mode <mode-name>`; multiple modes
|
||||
|
||||
You can create your own contexts and modes to precisely tailor Serena to your needs in two ways:
|
||||
* You can use Serena's CLI to manage modes and contexts. Check out
|
||||
|
||||
```shell
|
||||
uvx --from git+https://github.com/oraios/serena serena mode --help
|
||||
```
|
||||
and
|
||||
|
||||
```shell
|
||||
uvx --from git+https://github.com/oraios/serena serena context --help
|
||||
```
|
||||
*NOTE*: Custom contexts/modes are simply YAML files in `<home>/.serena`, they are automatically registered and available for use by their name (filename without the `.yml` extension). If you don't want to use Serena's CLI, you can create and manage them in any way you see fit.
|
||||
* **Using external YAML files**: When starting Serena, you can also provide an absolute path to a custom `.yml` file for a context or mode.
|
||||
|
||||
A context or mode YAML file typically defines:
|
||||
* `name`: (Optional if filename is used) The name of the context/mode.
|
||||
* `prompt`: A string that will be incorporated into Serena's system prompt.
|
||||
* `description`: (Optional) A brief description, not passed to the LLM.
|
||||
* `excluded_tools`: A list of tool names (strings) to disable when this context/mode is active.
|
||||
* `included_optional_tools`: A list of tool names that are disabled by default and have to be explicitly enabled by the user.
|
||||
|
||||
This customization allows for deep integration and adaptation of Serena to specific project requirements or personal preferences.
|
||||
|
||||
|
||||
@@ -872,25 +758,20 @@ It is also relatively straightforward to add [support for a new programming lang
|
||||
We look forward to seeing what the community will come up with!
|
||||
For details on contributing, see [here](/CONTRIBUTING.md).
|
||||
|
||||
## Full List of Tools
|
||||
## List of Tools
|
||||
|
||||
Here is the full list of Serena's tools with a short description (output of `uv run serena tools list`):
|
||||
Here is the list of Serena's default tools with a short description (output of `uv run serena tools list`):
|
||||
|
||||
* `activate_project`: Activates a project by name.
|
||||
* `check_onboarding_performed`: Checks whether project 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_code_snippets`: Finds code snippets in which the symbol at the given location is referenced.
|
||||
* `find_file`: Finds files in the given relative paths
|
||||
* `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_active_project`: Gets the name of the currently active project (if any) and lists existing projects
|
||||
* `get_current_config`: Prints the current configuration of the agent, including the active modes, tools, and context.
|
||||
* `get_symbols_overview`: Gets an overview of the top-level symbols defined in a given file or directory.
|
||||
* `initial_instructions`: Gets the initial instructions for the current project. Disabled by default, has to be enabled explicitly by using `included_optional_tools`
|
||||
* `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.
|
||||
@@ -898,14 +779,30 @@ Here is the full list of Serena's tools with a short description (output of `uv
|
||||
* `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_lines`: Replaces a range of lines within a file with new content.
|
||||
* `replace_regex`: Replaces content in a file by using regular expressions.
|
||||
* `replace_symbol_body`: Replaces the full definition of a symbol.
|
||||
* `restart_language_server`: Restarts the language server, may be necessary when edits not through Serena happen.
|
||||
* `search_for_pattern`: Performs a search for a pattern in the project.
|
||||
* `summarize_changes`: Provides instructions for summarizing the changes made to the codebase.
|
||||
* `switch_modes`: Activates modes by providing a list of their names
|
||||
* `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.
|
||||
|
||||
There are several tools that are disabled by default, and have to be enabled explicitly, e.g., through the context or modes.
|
||||
Note that several of our default contexts do enable some of these tools. For example, the `desktop-app` context enables the `execute_shell_command` tool.
|
||||
|
||||
The full list of optional tools is (output of `uv run serena tools list --only-optional`):
|
||||
|
||||
* `delete_lines`: Deletes a range of lines within a file.
|
||||
* `get_current_config`: Prints the current configuration of the agent, including the active and available projects, tools, contexts, and modes.
|
||||
* `initial_instructions`: Gets the initial instructions for the current project.
|
||||
Should only be used in settings where the system prompt cannot be set,
|
||||
e.g. in clients you have no control over, like Claude Desktop.
|
||||
* `insert_at_line`: Inserts content at a given line in a file.
|
||||
* `jet_brains_find_referencing_symbols`: Finds symbols that reference the given symbol
|
||||
* `jet_brains_find_symbol`: Performs a global (or local) search for symbols with/containing a given name/substring (optionally filtered by type).
|
||||
* `jet_brains_get_symbols_overview`: Retrieves an overview of the top-level symbols within a specified file
|
||||
* `remove_project`: Removes a project from the Serena configuration.
|
||||
* `replace_lines`: Replaces a range of lines within a file with new content.
|
||||
* `summarize_changes`: Provides instructions for summarizing the changes made to the codebase.
|
||||
* `switch_modes`: Activates modes by providing a list of their names
|
||||
@@ -0,0 +1,67 @@
|
||||
# Custom Agents with Serena
|
||||
|
||||
As a reference implementation, we provide an integration with the [Agno](https://docs.agno.com/introduction/playground) agent framework.
|
||||
Agno is a model-agnostic agent framework that allows you to turn Serena into an agent
|
||||
(independent of the MCP technology) with a large number of underlying LLMs. While Agno has recently
|
||||
added support for MCP servers out of the box, our Agno integration predates this and is a good illustration of how
|
||||
easy it is to integrate Serena into an arbitrary agent framework.
|
||||
|
||||
Here's how it works:
|
||||
|
||||
1. Download the agent-ui code with npx
|
||||
```shell
|
||||
npx create-agent-ui@latest
|
||||
```
|
||||
or, alternatively, clone it manually:
|
||||
```shell
|
||||
git clone https://github.com/agno-agi/agent-ui.git
|
||||
cd agent-ui
|
||||
pnpm install
|
||||
pnpm dev
|
||||
```
|
||||
|
||||
2. Install serena with the optional requirements:
|
||||
```shell
|
||||
# You can also only select agno,google or agno,anthropic instead of all-extras
|
||||
uv pip install --all-extras -r pyproject.toml -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
|
||||
```shell
|
||||
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
|
||||
```shell
|
||||
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.
|
||||
|
||||
|
||||
Here is a short demo of Serena performing a small analysis task with the newest Gemini model:
|
||||
|
||||
https://github.com/user-attachments/assets/ccfcb968-277d-4ca9-af7f-b84578858c62
|
||||
|
||||
|
||||
⚠️ 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`).
|
||||
|
||||
|
||||
## Other Agent Frameworks
|
||||
|
||||
It should be straightforward to incorporate Serena into any
|
||||
agent framework (like [pydantic-ai](https://ai.pydantic.dev/), [langgraph](https://langchain-ai.github.io/langgraph/tutorials/introduction/) or others).
|
||||
Typically, you need only to write an adapter for Serena's tools to the tool representation in the framework of your choice,
|
||||
as was done by us for Agno with [SerenaAgnoToolkit](/src/serena/agno.py).
|
||||
|
||||
Reference in new issue
Block a user