mirror of
https://github.com/tiennm99/serena.git
synced 2026-10-11 12:29:04 +00:00
Several docs improvements (proof-reading)
This commit is contained in:
Dominik Jain authored and Dominik Jain committed
1 parent
766ecbccd4
commit
530926c836
15 files changed
+110
-147
No files matched your search
@@ -1,2 +1,3 @@
|
||||
# About Serena
|
||||
|
||||
In this section, we provide an overview of Serena, its purpose, and its key features.
|
||||
@@ -1,10 +1,8 @@
|
||||
## LLM Integration
|
||||
|
||||
Serena provides the necessary [tools](#list-of-tools) for coding workflows, but an LLM is required to do the actual work,
|
||||
Serena provides the necessary [tools](035_tools) for coding workflows, but an LLM is required to do the actual work,
|
||||
orchestrating tool use.
|
||||
|
||||
For example, **supercharge the performance of Claude Code** with a [one-line shell command](#claude-code).
|
||||
|
||||
In general, Serena can be integrated with an LLM in several ways:
|
||||
|
||||
* by using the **model context protocol (MCP)**.
|
||||
@@ -14,6 +12,6 @@ In general, Serena can be integrated with an LLM in several ways:
|
||||
* 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](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 via OpenAPI.
|
||||
* by using [mcpo to connect it to ChatGPT](../03-special-guides/serena_on_chatgpt.md) or other clients that don't support MCP but do support tool calling via OpenAPI.
|
||||
* 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.
|
||||
@@ -25,20 +25,20 @@ With Serena, we provide direct, out-of-the-box support for:
|
||||
(requires Elm compiler)
|
||||
* **Erlang**
|
||||
(requires installation of beam and [erlang_ls](https://github.com/erlang-ls/erlang_ls), experimental, might be slow or hang)
|
||||
* **Fortran**
|
||||
* **Fortran**
|
||||
(requires installation of fortls: `pip install fortls`)
|
||||
* **Go**
|
||||
* **Go**
|
||||
(requires installation of `gopls`)
|
||||
* **Haskell**
|
||||
(automatically locates HLS via ghcup, stack, or system PATH; supports Stack and Cabal projects)
|
||||
* **Java**
|
||||
(_Note_: Uses quirky symbol names for methods that include the full method signature; this causes a variety of problems!)
|
||||
* **Javascript**
|
||||
* **JavaScript**
|
||||
* **Julia**
|
||||
* **Kotlin**
|
||||
(uses the pre-alpha [official kotlin LS](https://github.com/Kotlin/kotlin-lsp), some issues may appear)
|
||||
* **Lua**
|
||||
* **Markdown**
|
||||
* **Markdown**
|
||||
(must be explicitly specified via `--language markdown` when generating project config, primarily useful for documentation-heavy projects)
|
||||
* **Nix**
|
||||
(requires nixd installation)
|
||||
@@ -47,9 +47,9 @@ With Serena, we provide direct, out-of-the-box support for:
|
||||
* **PHP**
|
||||
(uses Intelephense LSP; set `INTELEPHENSE_LICENSE_KEY` environment variable for premium features)
|
||||
* **Python**
|
||||
* **R**
|
||||
* **R**
|
||||
(requires installation of the `languageserver` R package)
|
||||
* **Ruby**
|
||||
* **Ruby**
|
||||
(by default, uses [ruby-lsp](https://github.com/Shopify/ruby-lsp), specify ruby_solargraph as your language to use the previous solargraph based implementation)
|
||||
* **Rust**
|
||||
(requires [rustup](https://rustup.rs/) - uses rust-analyzer from your toolchain)
|
||||
|
||||
@@ -1,9 +1,9 @@
|
||||
## Comparison with Other Coding Agents
|
||||
|
||||
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.
|
||||
entire functionality is made available through an MCP server,
|
||||
thus not requiring additional API keys or subscriptions if access to an LLM
|
||||
is already available through an MCP-compatible client.
|
||||
|
||||
### Subscription-Based Coding Agents
|
||||
|
||||
@@ -13,20 +13,16 @@ Serena's functionality is similar to Cursor's Agent, Windsurf's Cascade or
|
||||
VSCode's 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 or CLI.
|
||||
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
|
||||
IDE-based tools often use a text search-based or purely text file-based approach, which is often
|
||||
less powerful, especially for large codebases.
|
||||
* Serena is not bound to a specific interface (IDE or CLI).
|
||||
Serena's MCP server can be used with any MCP client (including some IDEs).
|
||||
* Serena is not bound to a specific large language model or API.
|
||||
* Serena is open-source and has a small codebase, so it can be easily extended
|
||||
and modified.
|
||||
|
||||
@@ -38,17 +34,11 @@ 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.
|
||||
Serena itself can be used as an API-based agent (see the [section on Agno](../03-special-guides/custom_agent.md)).
|
||||
|
||||
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.
|
||||
an API key and bypassing the API costs.
|
||||
|
||||
### Other MCP-Based Coding Agents
|
||||
|
||||
|
||||
@@ -2,21 +2,17 @@
|
||||
|
||||
### Sponsors
|
||||
|
||||
We are very grateful to our [sponsors](https://github.com/sponsors/oraios) who help us drive Serena's development. The core team
|
||||
(the founders of [Oraios AI](https://oraios-ai.de/)) put in a lot of work in order to turn Serena into a useful open source project.
|
||||
We are very grateful to our [sponsors](https://github.com/sponsors/oraios), who help us drive Serena's development.
|
||||
The core team (the founders of [Oraios AI](https://oraios-ai.de/)) put in a lot of work in order to turn Serena into a useful open source project.
|
||||
So far, there is no business model behind this project, and sponsors are our only source of income from it.
|
||||
|
||||
Sponsors help us dedicating more time to the project, managing contributions, and working on larger features (like better tooling based on more advanced
|
||||
Sponsors help us dedicate more time to the project, managing contributions, and working on larger features (like better tooling based on more advanced
|
||||
LSP features, VSCode integration, debugging via the DAP, and several others).
|
||||
If you find this project useful to your work, or would like to accelerate the development of Serena, consider becoming a sponsor.
|
||||
|
||||
We are proud to announce that the Visual Studio Code team, together with Microsoft’s Open Source Programs Office and GitHub Open Source
|
||||
have decided to sponsor Serena with a one-time contribution!
|
||||
|
||||
<p align="center">
|
||||
<img src="resources/vscode_sponsor_logo.png" alt="Visual Studio Code sponsor logo" width="220">
|
||||
</p>
|
||||
|
||||
### Community Contributions
|
||||
|
||||
A significant part of Serena, especially support for various languages, was contributed by the open source community.
|
||||
@@ -24,6 +20,7 @@ We are very grateful for the many contributors who made this possible and who pl
|
||||
what it is today.
|
||||
|
||||
### Technologies
|
||||
|
||||
We built Serena on top of multiple existing open-source technologies, the most important ones being:
|
||||
|
||||
1. [multilspy](https://github.com/microsoft/multilspy).
|
||||
@@ -32,23 +29,6 @@ We built Serena on top of multiple existing open-source technologies, the most i
|
||||
Solid-LSP provides pure synchronous LSP calls and extends the original library with the symbolic logic
|
||||
that Serena required.
|
||||
2. [Python MCP SDK](https://github.com/modelcontextprotocol/python-sdk)
|
||||
3. [Agno](https://github.com/agno-agi/agno) and
|
||||
the associated [agent-ui](https://github.com/agno-agi/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 Solid-LSP.
|
||||
3. All the language servers that we use through Solid-LSP.
|
||||
|
||||
Without these projects, Serena would not have been possible (or would have been significantly more difficult to build).
|
||||
|
||||
## Customizing and Extending Serena
|
||||
|
||||
It is straightforward to extend Serena's AI functionality with your own ideas.
|
||||
Simply implement a new tool by subclassing
|
||||
`serena.agent.Tool` and implement the `apply` method with a signature
|
||||
that matches the tool's requirements.
|
||||
Once implemented, `SerenaAgent` will automatically have access to the new tool.
|
||||
|
||||
It is also relatively straightforward to add [support for a new programming language](/.serena/memories/adding_new_language_support_guide.md).
|
||||
|
||||
We look forward to seeing what the community will come up with!
|
||||
For details on contributing, see [contributing guidelines](/CONTRIBUTING.md).
|
||||
@@ -1,11 +1,6 @@
|
||||
# Usage
|
||||
|
||||
Serena can be used in various ways.
|
||||
In this section, you will find general usage instructions as well as concrete instructions for selected integrations.
|
||||
Serena can be used in various ways and supports coding workflows through a project-based approach.
|
||||
Its configuration is flexible and allows tailoring it to your specific needs.
|
||||
|
||||
* 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.
|
||||
In this section, you will find general usage instructions as well as concrete instructions for selected integrations.
|
||||
@@ -1,6 +1,6 @@
|
||||
## Prerequisites
|
||||
|
||||
### uv
|
||||
### Package Manager: uv
|
||||
|
||||
Serena is managed by `uv`.
|
||||
If you do not have it yet, install it following the instructions [here](https://docs.astral.sh/uv/getting-started/installation/).
|
||||
|
||||
@@ -136,8 +136,8 @@ to get a list of all available options.
|
||||
Some useful options include:
|
||||
|
||||
* `--project <path|name>`: specify the project to work on by name or path.
|
||||
* `--context <context>`: specify the operation [context]() in which Serena shall operate
|
||||
* `--mode <mode>`: specify one or more [modes]() to enable (can be passed several times)
|
||||
* `--context <context>`: specify the operation [context](contexts) in which Serena shall operate
|
||||
* `--mode <mode>`: specify one or more [modes](modes) to enable (can be passed several times)
|
||||
* `--enable-web-dashboard <true|false>`: enable or disable the web dashboard (enabled by default)
|
||||
|
||||
### Other Commands
|
||||
|
||||
@@ -132,7 +132,7 @@ There are many terminal-based coding assistants that support MCP servers, such a
|
||||
* [opencode](https://github.com/sst/opencode).
|
||||
|
||||
They generally benefit from the symbolic tools provided by Serena. You might want to customize some aspects of Serena
|
||||
by writing your own context, modes or prompts to adjust it to the client's respective internal capabilities (and your general worflow).
|
||||
by writing your own context, modes or prompts to adjust it to the client's respective internal capabilities (and your general workflow).
|
||||
|
||||
#### MCP-Enabled IDEs and Coding Clients (Cline, Roo-Code, Cursor, Windsurf, etc.)
|
||||
|
||||
|
||||
@@ -83,4 +83,49 @@ 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.
|
||||
Whenever Serena starts working on a project, the list of memories is
|
||||
provided, and the agent can decide to read them.
|
||||
We found that memories can significantly improve the user experience with Serena.
|
||||
We found that memories can significantly improve the user experience with Serena.
|
||||
|
||||
|
||||
### Preparing Your Project
|
||||
|
||||
When using Serena to work on your project, it can be helpful to follow a few best practices.
|
||||
|
||||
#### Structure Your Codebase
|
||||
|
||||
Serena uses the code structure for finding, reading and editing code. This means that it will
|
||||
work well with well-structured code but may perform poorly on fully unstructured one (like a "God class"
|
||||
with enormous, non-modular functions).
|
||||
|
||||
Furthermore, for languages that are not statically typed, the use of type annotations (if supported)
|
||||
are highly beneficial.
|
||||
|
||||
#### Start from a Clean State
|
||||
|
||||
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.
|
||||
|
||||
##### Use Platform-Native Line Endings
|
||||
|
||||
**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
|
||||
due to line endings only.
|
||||
It is generally a good idea to globally enable this git setting on Windows:
|
||||
|
||||
```shell
|
||||
git config --global core.autocrlf true
|
||||
```
|
||||
|
||||
##### Logging, Linting, and Automated Tests
|
||||
|
||||
Serena can successfully complete tasks in an _agent loop_, where it iteratively
|
||||
acquires information, performs actions, and reflects on the results.
|
||||
However, Serena cannot use a debugger; it must rely on the results of program executions,
|
||||
linting results, and test results to assess the correctness of its actions.
|
||||
Therefore, software that is designed to meaningful interpretable outputs (e.g. log messages)
|
||||
and that has a good test coverage is much easier to work with for Serena.
|
||||
|
||||
We generally recommend to start an editing task from a state where all linting checks and tests pass.
|
||||
@@ -39,6 +39,7 @@ want to use Serena.
|
||||
Serena's behavior and toolset can be adjusted using contexts and modes.
|
||||
These allow for a high degree of customization to best suit your workflow and the environment Serena is operating in.
|
||||
|
||||
(contexts)=
|
||||
#### Contexts
|
||||
|
||||
A **context** defines the general environment in which Serena is operating.
|
||||
@@ -67,6 +68,7 @@ You can manage contexts using the `context` command,
|
||||
|
||||
where `<serena>` is [your way of running Serena](020_running).
|
||||
|
||||
(modes)=
|
||||
#### Modes
|
||||
|
||||
Modes further refine Serena's behavior for specific types of tasks or interaction styles. Multiple modes can be active simultaneously, allowing you to combine their effects. Modes influence the system prompt and can also alter the set of available tools by excluding certain ones.
|
||||
|
||||
@@ -18,5 +18,5 @@ Serena comes with built-in tools for monitoring and managing the current session
|
||||
|
||||
This is mainly supported on Windows, but it may also work on Linux; macOS is unsupported.
|
||||
|
||||
Both can be enabled, configured or disabled in Serena's [configuration](050_configuration) file (`serena_config.yml`).
|
||||
Both can be configured in Serena's [configuration](050_configuration) file (`serena_config.yml`).
|
||||
If enabled, they will automatically be opened as soon as the Serena agent/MCP server is started.
|
||||
@@ -0,0 +1,30 @@
|
||||
## Additional Usage Pointers
|
||||
|
||||
### Prompting Strategies
|
||||
|
||||
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).
|
||||
|
||||
### Running Out of Context
|
||||
|
||||
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.
|
||||
|
||||
Serena instructs the LLM to be economical in general, so the problem of running out of context
|
||||
should not occur too often, unless the task is very large or complicated.
|
||||
|
||||
### Serena and Git Worktrees
|
||||
|
||||
[git-worktree](https://git-scm.com/docs/git-worktree) can be an excellent way to parallelize your work. More on this in [Anthropic: Run parallel Claude Code sessions with Git worktrees](https://docs.claude.com/en/docs/claude-code/common-workflows#run-parallel-claude-code-sessions-with-git-worktrees).
|
||||
|
||||
When it comes to serena AND git-worktree AND larger projects (that take longer to index), the recommended way is to COPY your `$ORIG_PROJECT/.serena/cache` to `$GIT_WORKTREE/.serena/cache`. After you have performed pre-indexing of your project described in [Project Activation & Indexing](#project-activation--indexing) section. To avoid having to re-index per each git work tree that you create.
|
||||
@@ -1,78 +0,0 @@
|
||||
## Detailed Usage and Recommendations
|
||||
|
||||
### Tool Execution
|
||||
|
||||
Serena combines tools for semantic code retrieval with editing capabilities and shell execution.
|
||||
Serena's behavior can be further customized through [Modes and Contexts](#modes-and-contexts).
|
||||
Find the complete list of tools [below](#full-list-of-tools).
|
||||
|
||||
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.
|
||||
|
||||
### Prepare Your Project
|
||||
|
||||
#### Structure Your Codebase
|
||||
|
||||
Serena uses the code structure for finding, reading and editing code. This means that it will
|
||||
work well with well-structured code but may perform poorly on fully unstructured one (like a "God class"
|
||||
with enormous, non-modular functions).
|
||||
Furthermore, for languages that are not statically typed, type annotations are highly beneficial.
|
||||
|
||||
#### Start from a Clean State
|
||||
|
||||
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.
|
||||
|
||||
:warning: **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 globally enable this git setting on Windows:
|
||||
|
||||
```shell
|
||||
git config --global core.autocrlf true
|
||||
```
|
||||
|
||||
#### Logging, Linting, and Automated Tests
|
||||
|
||||
Serena can successfully complete tasks in an _agent loop_, where it iteratively
|
||||
acquires information, performs actions, and reflects on the results.
|
||||
However, Serena cannot use a debugger; it must rely on the results of program executions,
|
||||
linting results, and test results to assess the correctness of its actions.
|
||||
Therefore, software that is designed to meaningful interpretable outputs (e.g. log messages)
|
||||
and that has a good test coverage is much easier to work with for Serena.
|
||||
|
||||
We generally recommend to start an editing task from a state where all linting checks and tests pass.
|
||||
|
||||
### Prompting Strategies
|
||||
|
||||
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).
|
||||
|
||||
### Running Out of Context
|
||||
|
||||
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.
|
||||
|
||||
### Serena and GIT worktrees
|
||||
[git-worktree](https://git-scm.com/docs/git-worktree) can be an excellent way to parallelize your work. More on this in [Anthropic: Run parallel Claude Code sessions with Git worktrees](https://docs.claude.com/en/docs/claude-code/common-workflows#run-parallel-claude-code-sessions-with-git-worktrees).
|
||||
|
||||
When it comes to serena AND git-worktree AND larger projects (that take longer to index), the recommended way is to COPY your `$ORIG_PROJECT/.serena/cache` to `$GIT_WORKTREE/.serena/cache`. After you have performed pre-indexing of your project described in [Project Activation & Indexing](#project-activation--indexing) section. To avoid having to re-index per each git work tree that you create.
|
||||
@@ -33,7 +33,7 @@ class Intelephense(SolidLanguageServer):
|
||||
@override
|
||||
def is_ignored_dirname(self, dirname: str) -> bool:
|
||||
# For PHP projects, we should ignore:
|
||||
# - vendor: third-party dependencies managed by Composer
|
||||
# - vendor: third-party dependencies <managed by Composer
|
||||
# - node_modules: if the project has JavaScript components
|
||||
# - cache: commonly used for caching
|
||||
return super().is_ignored_dirname(dirname) or dirname in ["node_modules", "vendor", "cache"]
|
||||
|
||||
Reference in new issue
Block a user