From 25f5f5095ff6f83aed9a1e94aeda6b74567d6b7d Mon Sep 17 00:00:00 2001 From: Dominik Jain Date: Tue, 7 Apr 2026 17:36:44 +0200 Subject: [PATCH] Adjust documentation to use uv tool installation as the main way of running things * Add installation, update, etc. * Remove use of `` and obsolete uvx examples. --- README.md | 12 +- docs/01-about/020_programming-languages.md | 1 + docs/02-usage/010_installation.md | 45 +++++ docs/02-usage/010_prerequisites.md | 12 -- docs/02-usage/020_running.md | 212 ++++++++++---------- docs/02-usage/025_jetbrains_plugin.md | 4 +- docs/02-usage/040_workflow.md | 11 +- docs/02-usage/050_configuration.md | 27 +-- docs/03-special-guides/serena_on_chatgpt.md | 3 +- 9 files changed, 176 insertions(+), 151 deletions(-) create mode 100644 docs/02-usage/010_installation.md delete mode 100644 docs/02-usage/010_prerequisites.md diff --git a/README.md b/README.md index 8fdd463d..bea385e7 100644 --- a/README.md +++ b/README.md @@ -176,16 +176,24 @@ https://github.com/user-attachments/assets/6eaa9aa1-610d-4723-a2d6-bf1e487ba753 ## Quick Start -**Prerequisites**. Serena is managed by *uv*, and [installing uv](https://docs.astral.sh/uv/getting-started/installation/) is the only required prerequisite for running Serena. +**Prerequisites**. Serena is managed by *uv*, and [installing uv](https://docs.astral.sh/uv/getting-started/installation/) is the only required prerequisite. > [!NOTE] > When using the language server backend, some additional dependencies may need to be installed to support certain languages; > see the [Language Support](https://oraios.github.io/serena/01-about/020_programming-languages.html) page for details. +**Install Serena**. Serena is installed via uv as follows: + +```bash +uv tool install -p 3.13 serena-agent@latest --prerelease=allow +``` + +After successful installation, the command `serena` should be available in your shell. + **Initialise Serena**. To initialise Serena and verify that your setup works correctly, simply run: ```bash -uvx -p 3.13 --from git+https://github.com/oraios/serena serena init +serena init ``` By default, this will set up Serena to use the language server backend. To use the JetBrains backend instead, add the parameters `-b JetBrains` diff --git a/docs/01-about/020_programming-languages.md b/docs/01-about/020_programming-languages.md index bc556a43..5e74e71d 100644 --- a/docs/01-about/020_programming-languages.md +++ b/docs/01-about/020_programming-languages.md @@ -15,6 +15,7 @@ There are two alternative technologies powering these capabilities: See the [Features](025_features) section for a detailed comparison of the capabilities provided by the JetBrains Plugin vs. language servers. +(language-servers)= ## Language Servers Serena incorporates a powerful abstraction layer for the integration of language servers diff --git a/docs/02-usage/010_installation.md b/docs/02-usage/010_installation.md new file mode 100644 index 00000000..8a3dd922 --- /dev/null +++ b/docs/02-usage/010_installation.md @@ -0,0 +1,45 @@ +# Installation + +## Prerequisites + +**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** + +When using the language server backend, some additional dependencies may need to be installed +to support certain languages. +See the [Language Support](language-servers) page for the list of supported languages. +Many dependencies are installed by Serena on the fly, but if a language requires dependencies +to be provided manually, this is mentioned in the notes below the respective language. + +(install-serena)= +## Installing and Initialising Serena + +With `uv` installed and on your PATH, install Serena with this command: + + uv tool install -p 3.13 serena-agent@latest --prerelease=allow + +Upon completion, the command `serena` should be available in your terminal. + +To test the installation and initialise Serena, run one of the following commands: + + * `serena init` + if you intend to use the default language intelligence backend (language servers) + * `serena init -b JetBrains` + if you intend to use the JetBrains backend (which uses the [JetBrains plugin](025_jetbrains_plugin)) + +Note that you can switch backends at any time via Serena's [configuration](050_configuration). + +## Updating Serena + +To update Serena to the latest version, run: + + uv tool upgrade serena-agent --prerelease=allow + +:::{tip} +To keep informed about updates, make sure you regularly open [Serena's Dashboard](060_dashboard), +where we will announce releases along with the new features and improvements they bring. +::: diff --git a/docs/02-usage/010_prerequisites.md b/docs/02-usage/010_prerequisites.md deleted file mode 100644 index b408664e..00000000 --- a/docs/02-usage/010_prerequisites.md +++ /dev/null @@ -1,12 +0,0 @@ -# Prerequisites - -## 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 - -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. -See the [language support documentation](../01-about/020_programming-languages) for details. diff --git a/docs/02-usage/020_running.md b/docs/02-usage/020_running.md index 4e2ca372..d6b0b81c 100644 --- a/docs/02-usage/020_running.md +++ b/docs/02-usage/020_running.md @@ -2,98 +2,25 @@ Serena is a command-line tool with a variety of sub-commands. This section describes - * various ways of running Serena + * how to run Serena in general * how to run and configure the most important command, i.e. starting the MCP server * other useful commands. -## 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, -as detailed below. +The main way to run Serena is to use the [installed version](install-serena), +which should be available in your system PATH as `serena.` In general, to get help, append `--help` to the command, i.e. - --help - --help + serena --help + serena --help -### 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. - - uvx -p 3.13 --from git+https://github.com/oraios/serena serena - -Explore the CLI to see some of the customization options that serena provides (more info on them below). - -### Local Installation - -1. Clone the repository and change into it. - - ```shell - git clone https://github.com/oraios/serena - cd serena - ``` - -2. Run Serena via - - ```shell - uv run serena - ``` - - when within the serena installation directory. - From other directories, run it with the `--directory` option, i.e. - - ```shell - uv run --directory /abs/path/to/serena serena - ``` - -:::{note} -Adding the `--directory` option results in the working directory being set to the Serena directory. -As a consequence, you will need to specify paths when using CLI commands that would otherwise operate on the current directory. -::: - -(docker)= -### Using Docker - -The Docker approach offers several advantages: - -* better security isolation for shell command execution -* no need to install language servers and dependencies locally -* consistent environment across different systems - -You can run the Serena MCP server directly via Docker as follows, -assuming that the projects you want to work on are all located in `/path/to/your/projects`: - -```shell -docker run --rm -i --network host -v /path/to/your/projects:/workspaces/projects ghcr.io/oraios/serena:latest serena -``` - -This command mounts your projects into the container under `/workspaces/projects`, so when working with projects, -you need to refer to them using the respective path (e.g. `/workspaces/projects/my-project`). - -Alternatively, you may use Docker compose with the `compose.yml` file provided in the repository. -See our [advanced Docker usage](https://github.com/oraios/serena/blob/main/DOCKER.md) documentation for more detailed instructions, configuration options, and limitations. - -:::{note} -Docker usage is subject to limitations; see the [advanced Docker usage](https://github.com/oraios/serena/blob/main/DOCKER.md) documentation for details. -::: - -### 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: - -```bash -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`. (start-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: - start-mcp-server [options] + serena start-mcp-server [options] 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. @@ -120,12 +47,8 @@ therefore needs to be configured with a launch command. Communication over stdio is the default for the Serena MCP server, so in the simplest case, you can simply run the `start-mcp-server` command without any additional options. - start-mcp-server + serena start-mcp-server -For example, to run the server in stdio mode via `uvx`, you would run: - - uvx -p 3.13 --from git+https://github.com/oraios/serena serena start-mcp-server - See the section ["Configuring Your MCP Client"](030_clients) for specific information on how to configure your MCP client (e.g. Claude Code, Codex, Cursor, etc.) to use such a launch command. @@ -137,13 +60,9 @@ i.e. you start the server and provide the client with the URL to connect to it. Simply provide `start-mcp-server` with the `--transport streamable-http` option and optionally provide the desired port via the `--port` option. +For example, to start the server on port 9121, run - start-mcp-server --transport streamable-http --port - -For example, to run the Serena MCP server in streamable HTTP mode on port 9121 using uvx, -you would run - - uvx -p 3.13 --from git+https://github.com/oraios/serena serena start-mcp-server --transport streamable-http --port 9121 + serena start-mcp-server --transport streamable-http --port and then configure your client to connect to `http://localhost:9121/mcp`. @@ -200,58 +119,135 @@ Here are some examples of commands you might find useful: ```bash # get help about a sub-command - tools list --help +serena> tools list --help # list all available tools - tools list --all +serena> tools list --all # get detailed description of a specific tool - tools description find_symbol +serena> tools description find_symbol # creating a new Serena project in the current directory - project create +serena project create # creating and immediately indexing a project - project create --index +serena project create --index # indexing the project in the current directory (auto-creates if needed) - project index +serena project index # run a health check on the project in the current directory - project health-check +serena project health-check # check if a path is ignored by the project - project is_ignored_path path/to/check +serena project is_ignored_path path/to/check # edit Serena's configuration file - config edit +serena config edit # list available contexts - context list +serena context list # create a new context - context create my-custom-context +serena context create my-custom-context # edit a custom context - context edit my-custom-context +serena context edit my-custom-context # list available modes - mode list +serena mode list # create a new mode - mode create my-custom-mode +serena mode create my-custom-mode # edit a custom mode - mode edit my-custom-mode +serena mode edit my-custom-mode # list available prompt definitions - prompts list +serena prompts list # create an override for internal prompts - prompts create-override prompt-name +serena prompts create-override prompt-name # edit a prompt override - prompts edit-override prompt-name +serena prompts edit-override prompt-name ``` Explore the full set of commands and options using the CLI itself! + + +## Alternative Ways of Running Serena + +Depending on your requirements, you may want to run Serena in different ways. +When applying one of these approaches, replace `serena` in commands mentioned throughout the documentation +with the respective command and options. + +### Using uvx to Run the Latest Source Version + +`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. + + uvx -p 3.13 --from git+https://github.com/oraios/serena serena + + +### Running from Cloned Source + +1. Clone the repository and change into it. + + ```shell + git clone https://github.com/oraios/serena + cd serena + ``` + +2. Run Serena via + + ```shell + uv run serena + ``` + + when within the serena installation directory. + From other directories, run it with the `--directory` option, i.e. + + ```shell + uv run --directory /abs/path/to/serena serena + ``` + +:::{note} +Adding the `--directory` option results in the working directory being set to the Serena directory. +As a consequence, you will need to specify paths when using CLI commands that would otherwise operate on the current directory. +::: + +(docker)= +### Using Docker + +The Docker approach offers several advantages: + +* better security isolation for shell command execution +* no need to install language servers and dependencies locally +* consistent environment across different systems + +You can run the Serena MCP server directly via Docker as follows, +assuming that the projects you want to work on are all located in `/path/to/your/projects`: + +```shell +docker run --rm -i --network host -v /path/to/your/projects:/workspaces/projects ghcr.io/oraios/serena:latest serena +``` + +This command mounts your projects into the container under `/workspaces/projects`, so when working with projects, +you need to refer to them using the respective path (e.g. `/workspaces/projects/my-project`). + +Alternatively, you may use Docker compose with the `compose.yml` file provided in the repository. +See our [advanced Docker usage](https://github.com/oraios/serena/blob/main/DOCKER.md) documentation for more detailed instructions, configuration options, and limitations. + +:::{note} +Docker usage is subject to limitations; see the [advanced Docker usage](https://github.com/oraios/serena/blob/main/DOCKER.md) documentation for details. +::: + +### Using Nix to Run the Latest Source Version + +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: + +```bash +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`. diff --git a/docs/02-usage/025_jetbrains_plugin.md b/docs/02-usage/025_jetbrains_plugin.md index e7f425a6..5a0a16f2 100644 --- a/docs/02-usage/025_jetbrains_plugin.md +++ b/docs/02-usage/025_jetbrains_plugin.md @@ -68,12 +68,12 @@ After installing the plugin, you need to configure Serena to use it. You can run ```shell -uvx -p 3.13 --from git+https://github.com/oraios/serena serena init -b JetBrains +serena init -b JetBrains ``` to set the default code intelligence backend to JetBrains in the global Serena configuration file. -Alternatively, you can also manually edit the configuration file `~/.serena/serena_config.yml` +Alternatively, manually edit the configuration file `~/.serena/serena_config.yml` (`%USERPROFILE%\.serena\serena_config.yml` on Windows) and set ```yaml diff --git a/docs/02-usage/040_workflow.md b/docs/02-usage/040_workflow.md index 380009c5..ce8fbb77 100644 --- a/docs/02-usage/040_workflow.md +++ b/docs/02-usage/040_workflow.md @@ -25,11 +25,7 @@ You can create a project either To explicitly create a project, use the following command while in the project directory: - project create [options] - -For instance, when using `uvx`, run - - uvx -p 3.13 --from git+https://github.com/oraios/serena serena project create [options] + serena project create [options] * For an empty project, you will need to specify the programming language (e.g., `--language python`). @@ -197,11 +193,8 @@ Depending on the language backend being used, the management of resources for th To start the server, run - start-project-server + serena start-project-server - where `` is your way of running Serena. For example, when using `uvx`, run - - uvx -p 3.13 --from git+https://github.com/oraios/serena serena start-project-server ### Multiple Agents Accessing a Single Serena Instance diff --git a/docs/02-usage/050_configuration.md b/docs/02-usage/050_configuration.md index 1c8fbfaa..5f5f3ad3 100644 --- a/docs/02-usage/050_configuration.md +++ b/docs/02-usage/050_configuration.md @@ -51,11 +51,9 @@ You can access it * using the command ```shell - config edit + serena config edit ``` - where `` is [your way of running Serena](020_running). - ## Modes and Contexts Serena's behaviour and toolset can be adjusted using contexts and modes. @@ -95,13 +93,12 @@ If you are using a local server (such as Llama.cpp) which requires you to use Op You can manage contexts using the `context` command, - context --help - context list - context create - context edit - context delete + serena context --help + serena context list + serena context create + serena context edit + serena context delete -where `` is [your way of running Serena](020_running). (modes)= ### Modes @@ -159,13 +156,11 @@ Serena currently does not prevent incompatible combinations; it is up to the use You can manage modes using the `mode` command, - mode --help - mode list - mode create - mode edit - mode delete - -where `` is [your way of running Serena](020_running). + serena mode --help + serena mode list + serena mode create + serena mode edit + serena mode delete ## Advanced Configuration diff --git a/docs/03-special-guides/serena_on_chatgpt.md b/docs/03-special-guides/serena_on_chatgpt.md index d5b640ba..c8de60eb 100644 --- a/docs/03-special-guides/serena_on_chatgpt.md +++ b/docs/03-special-guides/serena_on_chatgpt.md @@ -17,7 +17,6 @@ Run the following command to launch Serena as http server (assuming port 8000): ```bash uvx mcpo --port 8000 --api-key -- \ - uvx -p 3.13 --from git+https://github.com/oraios/serena \ serena start-mcp-server --context chatgpt --project $(pwd) ``` @@ -28,7 +27,7 @@ You can also use other options, and you don't have to pass `--project` if you wa or want to activate it later. See ```shell -uvx -p 3.13 --from git+https://github.com/oraios/serena serena start-mcp-server --help +serena start-mcp-server --help ``` ---