From 90e123726c790b3820f26bf398d1b24d1ca63c65 Mon Sep 17 00:00:00 2001 From: Dominik Jain Date: Sat, 8 Nov 2025 12:36:43 +0100 Subject: [PATCH] Fix heading levels in docs --- docs/01-about/010_llm-integration.md | 2 +- docs/01-about/020_programming-languages.md | 2 +- docs/01-about/030_serena-in-action.md | 6 ++--- docs/01-about/035_tools.md | 2 +- .../040_comparison-to-other-agents.md | 8 +++---- docs/01-about/050_acknowledgements.md | 8 +++---- docs/02-usage/010_prerequisites.md | 6 ++--- docs/02-usage/020_running.md | 22 +++++++++---------- docs/02-usage/030_clients.md | 16 +++++++------- docs/02-usage/040_workflow.md | 22 +++++++++---------- docs/02-usage/050_configuration.md | 8 +++---- docs/02-usage/060_dashboard.md | 2 +- docs/02-usage/070_security.md | 2 +- docs/02-usage/999_additional-usage.md | 8 +++---- 14 files changed, 57 insertions(+), 57 deletions(-) diff --git a/docs/01-about/010_llm-integration.md b/docs/01-about/010_llm-integration.md index 2fd10100..0f9c75aa 100644 --- a/docs/01-about/010_llm-integration.md +++ b/docs/01-about/010_llm-integration.md @@ -1,4 +1,4 @@ -## LLM Integration +# LLM Integration Serena provides the necessary [tools](035_tools) for coding workflows, but an LLM is required to do the actual work, orchestrating tool use. diff --git a/docs/01-about/020_programming-languages.md b/docs/01-about/020_programming-languages.md index 0e9eeb6c..601c3def 100644 --- a/docs/01-about/020_programming-languages.md +++ b/docs/01-about/020_programming-languages.md @@ -1,4 +1,4 @@ -## Language Support +# Language Support 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 diff --git a/docs/01-about/030_serena-in-action.md b/docs/01-about/030_serena-in-action.md index 31b26fba..d180c61d 100644 --- a/docs/01-about/030_serena-in-action.md +++ b/docs/01-about/030_serena-in-action.md @@ -1,12 +1,12 @@ -## Serena in Action +# Serena in Action -### Demonstration 1: Efficient Operation in Claude Code +## Demonstration 1: Efficient Operation in Claude Code A demonstration of Serena efficiently retrieving and editing code within Claude Code, thereby saving tokens and time. Efficient operations are not only useful for saving costs, but also for generally improving the generated code's quality. This effect may be less pronounced in very small projects, but often becomes of crucial importance in larger ones. https://github.com/user-attachments/assets/ab78ebe0-f77d-43cc-879a-cc399efefd87 -### Demonstration 2: Serena in Claude Desktop +## Demonstration 2: Serena in Claude Desktop 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. diff --git a/docs/01-about/035_tools.md b/docs/01-about/035_tools.md index 67078ded..17b84b53 100644 --- a/docs/01-about/035_tools.md +++ b/docs/01-about/035_tools.md @@ -1,4 +1,4 @@ -## List of Tools +# List of Tools Find the full list of Serena's tools below (output of ` tools list --all`). diff --git a/docs/01-about/040_comparison-to-other-agents.md b/docs/01-about/040_comparison-to-other-agents.md index f9baf158..df89149e 100644 --- a/docs/01-about/040_comparison-to-other-agents.md +++ b/docs/01-about/040_comparison-to-other-agents.md @@ -1,11 +1,11 @@ -## Comparison with Other Coding Agents +# Comparison with Other Coding Agents To our knowledge, Serena is the first fully-featured coding agent where the 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 +## Subscription-Based Coding Agents Many prominent subscription-based coding agents are parts of IDEs like Windsurf, Cursor and VSCode. @@ -26,7 +26,7 @@ More technical differences are: * Serena is open-source and has a small codebase, so it can be easily extended and modified. -### API-Based Coding Agents +## API-Based Coding Agents 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 @@ -40,7 +40,7 @@ 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. -### Other MCP-Based Coding Agents +## Other MCP-Based Coding Agents There are other MCP servers designed for coding, like [DesktopCommander](https://github.com/wonderwhy-er/DesktopCommanderMCP) and [codemcp](https://github.com/ezyang/codemcp). diff --git a/docs/01-about/050_acknowledgements.md b/docs/01-about/050_acknowledgements.md index 6831e898..334a4e6e 100644 --- a/docs/01-about/050_acknowledgements.md +++ b/docs/01-about/050_acknowledgements.md @@ -1,6 +1,6 @@ -## Acknowledgements +# Acknowledgements -### Sponsors +## 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. @@ -13,13 +13,13 @@ If you find this project useful to your work, or would like to accelerate the de 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! -### Community Contributions +## Community Contributions A significant part of Serena, especially support for various languages, was contributed by the open source community. We are very grateful for the many contributors who made this possible and who played an important role in making Serena what it is today. -### Technologies +## Technologies We built Serena on top of multiple existing open-source technologies, the most important ones being: diff --git a/docs/02-usage/010_prerequisites.md b/docs/02-usage/010_prerequisites.md index 5a59feeb..b408664e 100644 --- a/docs/02-usage/010_prerequisites.md +++ b/docs/02-usage/010_prerequisites.md @@ -1,11 +1,11 @@ -## Prerequisites +# Prerequisites -### Package Manager: 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/). -### Language-Specific Requirements +## Language-Specific Requirements Depending on the programming language you intend to use with Serena, you may need to install additional tools or SDKs if you intend to use the language server backend of Serena. diff --git a/docs/02-usage/020_running.md b/docs/02-usage/020_running.md index 73a04f72..5b778c01 100644 --- a/docs/02-usage/020_running.md +++ b/docs/02-usage/020_running.md @@ -1,4 +1,4 @@ -## Running Serena +# Running Serena Serena is a command-line tool with a variety of sub-commands. This section describes @@ -6,12 +6,12 @@ This section describes * how to run and configure the most important command, i.e. starting the MCP server * other useful commands. -### Ways of Running Serena +## Ways of Running Serena In the following, we will refer to the command used to run Serena as ``, which you should replace with the appropriate command based on your chosen method. -#### Using uvx +### Using uvx `uvx` is part of `uv`. It can be used to run the latest version of Serena directly from the repository, without an explicit local installation. @@ -19,7 +19,7 @@ which you should replace with the appropriate command based on your chosen metho Explore the CLI to see some of the customization options that serena provides (more info on them below). -#### Local Installation +### Local Installation 1. Clone the repository and change into it. @@ -42,7 +42,7 @@ Explore the CLI to see some of the customization options that serena provides (m ``` (docker)= -#### Using Docker (Experimental) +### Using Docker (Experimental) ⚠️ Docker support is currently experimental with several limitations. Please read the [Docker documentation](https://github.com/oraios/serena/blob/main/DOCKER.md) for important caveats before using it. @@ -63,7 +63,7 @@ Alternatively, use docker compose with the `compose.yml` file provided in the re See the [Docker documentation](https://github.com/oraios/serena/blob/main/DOCKER.md) for detailed setup instructions, configuration options, and known limitations. -#### Using Nix +### Using Nix If you are using Nix and [have enabled the `nix-command` and `flakes` features](https://nixos.wiki/wiki/flakes), you can run Serena using the following command: @@ -73,7 +73,7 @@ nix run github:oraios/serena -- [options] You can also install Serena by referencing this repo (`github:oraios/serena`) and using it in your Nix flake. The package is exported as `serena`. -### Running the MCP Server +## Running the MCP Server Given your preferred method of running Serena, you can start the MCP server using the `start-mcp-server` command: @@ -82,7 +82,7 @@ Given your preferred method of running Serena, you can start the MCP server usin Note that no matter how you run the MCP server, Serena will, by default, start a web-based dashboard on localhost that will allow you to inspect the server's operations, logs, and configuration. -#### Standard I/O Mode +### Standard I/O Mode The typical usage involves the client (e.g. Claude Code, Codex or Cursor) running the MCP server as a subprocess and using the process' stdin/stdout streams to communicate with it. @@ -105,7 +105,7 @@ necessarily has to be started by the client in order for communication to take p In other words, you do not need to start the server yourself. The client application (e.g. Claude Desktop) takes care of this and therefore needs to be configured with a launch command. -#### Streamable HTTP Mode +### Streamable HTTP Mode When using instead the *Streamable HTTP* mode, you control the server lifecycle yourself, i.e. you start the server and provide the client with the URL to connect to it. @@ -125,7 +125,7 @@ and then configure your client to connect to `http://localhost:9121/mcp`. ℹ️ Note that while SSE transport is also supported, its use is discouraged. (mcp-args)= -#### MCP Server Command-Line Arguments +### MCP Server Command-Line Arguments The Serena MCP server supports a wide range of additional command-line options. Use the command @@ -141,7 +141,7 @@ Some useful options include: * `--mode `: specify one or more [modes](modes) to enable (can be passed several times) * `--enable-web-dashboard `: enable or disable the web dashboard (enabled by default) -### Other Commands +## Other Commands Serena provides several other commands in addition to `start-mcp-server`, most of which are related to project setup and configuration. diff --git a/docs/02-usage/030_clients.md b/docs/02-usage/030_clients.md index 9f6dcc3e..6e0eb563 100644 --- a/docs/02-usage/030_clients.md +++ b/docs/02-usage/030_clients.md @@ -1,4 +1,4 @@ -## Configuring Your MCP Client +# Configuring Your MCP Client In the following, we provide default configurations for popular MCP-enabled clients. @@ -6,7 +6,7 @@ Depending on your needs, you might want to customize Serena's behaviour by * [adding command-line arguments](mcp-args) * [adjusting configuration](050_configuration). -### Claude Code +## Claude Code Serena is a great way to make Claude Code both cheaper and more powerful! @@ -32,7 +32,7 @@ Note: Be sure to use at least `v1.0.52` of Claude Code (as earlier versions do not read MCP server system prompts upon startup). -### Codex +## Codex Serena works with OpenAI's Codex CLI out of the box, but you have to use the `codex` context for it to work properly. (The technical reason is that Codex doesn't fully support the MCP specifications, so some massaging of tools is required.). @@ -59,7 +59,7 @@ that was already taken). > Codex will often show the tools as `failed` even though they are successfully executed. This is not a problem, seems to be a bug in Codex. Despite the error message, everything works as expected. -### Claude Desktop +## Claude Desktop On Windows and macOS there are official [Claude Desktop applications by Anthropic](https://claude.ai/download), for Linux there is an [open-source community version](https://github.com/aaddrick/claude-desktop-debian). @@ -119,9 +119,9 @@ After restarting, you should see Serena's tools in your chat interface (notice t For more information on MCP servers with Claude Desktop, see [the official quick start guide](https://modelcontextprotocol.io/quickstart/user). -### Other Clients +## Other Clients -#### Terminal-Based Clients +### Terminal-Based Clients There are many terminal-based coding assistants that support MCP servers, such as @@ -134,7 +134,7 @@ There are many terminal-based coding assistants that support MCP servers, such a 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 workflow). -#### MCP-Enabled IDEs and Coding Clients (Cline, Roo-Code, Cursor, Windsurf, etc.) +### MCP-Enabled IDEs and Coding Clients (Cline, Roo-Code, Cursor, Windsurf, etc.) Being an MCP Server, Serena can be included in any MCP Client. Most of the popular existing coding assistants (e.g. IDE extensions) and AI-enabled IDEs themselves support connections @@ -143,7 +143,7 @@ to MCP Servers. Serena generally boosts performance by providing efficient tools We generally **recommend to use the `ide-assistant` context** for these integrations by adding the arguments `--context ide-assistant` in order to reduce tool duplication. -#### Local GUIs and Agent Frameworks +### Local GUIs and Agent Frameworks Over the last months, several technologies have emerged that allow you to run a local GUI client and connect it to an MCP server. The respective applications will typically work with Serena out of the box. diff --git a/docs/02-usage/040_workflow.md b/docs/02-usage/040_workflow.md index 97b2064d..aca2143a 100644 --- a/docs/02-usage/040_workflow.md +++ b/docs/02-usage/040_workflow.md @@ -1,4 +1,4 @@ -## The Project Workflow +# The Project Workflow Serena uses a project-based workflow. A **project** is simply a directory on your filesystem that contains code and other files @@ -12,13 +12,13 @@ setting up a project with Serena typically involves the following steps: 3. **Onboarding**: Getting Serena familiar with the project (creating memories) 4. **Working on coding tasks**: Using Serena to help you with actual coding tasks in the project -### Project Creation & Indexing +## Project Creation & Indexing You can create a project either * implicitly, by just activating a directory as a project while already in a conversation; this will use default settings for your project (skip to the next section). * explicitly, using the project creation command, or -#### Explicit Project Creation +### Explicit Project Creation To explicitly create a project, use the following command while in the project directory: @@ -37,7 +37,7 @@ For instance, when using `uvx`, run After creation, you can adjust the project settings in the generated `.serena/project.yml` file. (indexing)= -#### Indexing +### Indexing Especially for larger project, it is advisable to index the project after creation (in order to avoid delays during MCP server startup or the first tool application): @@ -48,7 +48,7 @@ While in the project directory, run this command: Indexing has to be called only once. During regular usage, Serena will automatically update the index whenever files change. -### Project Activation +## Project Activation Project activation makes Serena aware of the project you want to work with. You can either choose to do this @@ -63,7 +63,7 @@ You can either choose to do this (e.g. when working on a fixed project in `ide-assistant` mode): `--project ` -### Onboarding & Memories +## Onboarding & Memories By default, Serena will perform an **onboarding process** when it is started for the first time for a project. @@ -87,11 +87,11 @@ provided, and the agent can decide to read them. We found that memories can significantly improve the user experience with Serena. -### Preparing Your Project +## Preparing Your Project When using Serena to work on your project, it can be helpful to follow a few best practices. -#### Structure Your Codebase +### 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" @@ -100,14 +100,14 @@ 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 +### 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 +### 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 @@ -120,7 +120,7 @@ It is generally a good idea to globally enable this git setting on Windows: git config --global core.autocrlf true ``` -##### Logging, Linting, and Automated Tests +### 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. diff --git a/docs/02-usage/050_configuration.md b/docs/02-usage/050_configuration.md index edec95cf..bf1a85f7 100644 --- a/docs/02-usage/050_configuration.md +++ b/docs/02-usage/050_configuration.md @@ -1,4 +1,4 @@ -## Configuration +# Configuration 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 @@ -34,13 +34,13 @@ Serena is configured in four places: After the initial setup, continue with one of the sections below, depending on how you want to use Serena. -### Modes and Contexts +## Modes and Contexts 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 +### Contexts A **context** defines the general environment in which Serena is operating. It influences the initial system prompt and the set of available tools. @@ -69,7 +69,7 @@ You can manage contexts using the `context` command, where `` is [your way of running Serena](020_running). (modes)= -#### 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. diff --git a/docs/02-usage/060_dashboard.md b/docs/02-usage/060_dashboard.md index 594a6fd4..73376926 100644 --- a/docs/02-usage/060_dashboard.md +++ b/docs/02-usage/060_dashboard.md @@ -1,4 +1,4 @@ -## The Dashboard and GUI Tool +# The Dashboard and GUI Tool Serena comes with built-in tools for monitoring and managing the current session: diff --git a/docs/02-usage/070_security.md b/docs/02-usage/070_security.md index 2b5478cd..12faabdf 100644 --- a/docs/02-usage/070_security.md +++ b/docs/02-usage/070_security.md @@ -1,4 +1,4 @@ -## Security Considerations +# Security Considerations As fundamental abilities for a coding agent, Serena contains tools for executing shell commands and modifying files. Therefore, if the respective tool calls are not monitored or restricted (and execution takes place in a sensitive environment), diff --git a/docs/02-usage/999_additional-usage.md b/docs/02-usage/999_additional-usage.md index bb37f0ef..275fd190 100644 --- a/docs/02-usage/999_additional-usage.md +++ b/docs/02-usage/999_additional-usage.md @@ -1,6 +1,6 @@ -## Additional Usage Pointers +# Additional Usage Pointers -### Prompting Strategies +## 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 @@ -8,7 +8,7 @@ better results and in increasing the feeling of control and staying in the loop. 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 +## 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 @@ -23,7 +23,7 @@ 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 +## 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).