Fix heading levels in docs

2026-10-11 03:13:51 +00:00 · 2025-11-08 12:43:17 +01:00
1 parent e436fb3f59
commit 90e123726c
@@ -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.
@@ -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
@@ -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.
@@ -1,4 +1,4 @@
-## List of Tools
+# List of Tools

 Find the full list of Serena's tools below (output of `<serena> tools list --all`).

@@ -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).
@@ -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:

@@ -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.  
@@ -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 `<serena>`,
 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 -- <command> [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 <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
+## Other Commands

 Serena provides several other commands in addition to `start-mcp-server`, 
 most of which are related to project setup and configuration.
@@ -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.
@@ -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 <path|name>`


-### 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.
@@ -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 `<serena>` 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.

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

@@ -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), 
@@ -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).