tiennm99/serena
1
0 Fork 0
mirror of https://github.com/tiennm99/serena.git synced 2026-10-03 07:13:33 +00:00
Code Issues Packages Projects Releases Wiki Activity

Adjust documentation to use uv tool installation as the main way of running things

Browse Source 
* Add installation, update, etc.
* Remove use of `<serena>` and obsolete uvx examples.
This commit is contained in:
Dominik Jain committed 2026-04-07 17:36:44 +02:00
1 parent c3e3c57309
commit 25f5f5095f
9 files changed
+176 -151
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

README.md
+10 -2
View File
@@ -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`
docs/01-about/020_programming-languages.md
+1
View File
@@ -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
docs/02-usage/010_installation.md
+45
View File
@@ -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.
:::
docs/02-usage/010_prerequisites.md
-12
View File
@@ -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.
docs/02-usage/020_running.md
+104 -108
View File
@@ -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 `<serena>`,
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.
<serena> --help
<serena> <command> --help
serena --help
serena <command> --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 -- <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`.
(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:
<serena> 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.
<serena> 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
<serena> start-mcp-server --transport streamable-http --port <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 <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
<serena> tools list --help
serena> tools list --help
# list all available tools
<serena> tools list --all
serena> tools list --all
# get detailed description of a specific tool
<serena> tools description find_symbol
serena> tools description find_symbol
# creating a new Serena project in the current directory
<serena> project create
serena project create
# creating and immediately indexing a project
<serena> project create --index
serena project create --index
# indexing the project in the current directory (auto-creates if needed)
<serena> project index
serena project index
# run a health check on the project in the current directory
<serena> project health-check
serena project health-check
# check if a path is ignored by the project
<serena> project is_ignored_path path/to/check
serena project is_ignored_path path/to/check
# edit Serena's configuration file
<serena> config edit
serena config edit
# list available contexts
<serena> context list
serena context list
# create a new context
<serena> context create my-custom-context
serena context create my-custom-context
# edit a custom context
<serena> context edit my-custom-context
serena context edit my-custom-context
# list available modes
<serena> mode list
serena mode list
# create a new mode
<serena> mode create my-custom-mode
serena mode create my-custom-mode
# edit a custom mode
<serena> mode edit my-custom-mode
serena mode edit my-custom-mode
# list available prompt definitions
<serena> prompts list
serena prompts list
# create an override for internal prompts
<serena> prompts create-override prompt-name
serena prompts create-override prompt-name
# edit a prompt override
<serena> 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 -- <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`.
docs/02-usage/025_jetbrains_plugin.md
+2 -2
View File
@@ -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
docs/02-usage/040_workflow.md
+2 -9
View File
@@ -25,11 +25,7 @@ You can create a project either
To explicitly create a project, use the following command while in the project directory:
<serena> 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
<serena> start-project-server
serena start-project-server
where `<serena>` 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
docs/02-usage/050_configuration.md
+11 -16
View File
@@ -51,11 +51,9 @@ You can access it
* using the command
```shell
<serena> config edit
serena config edit
```
where `<serena>` 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,
<serena> context --help
<serena> context list
<serena> context create <context-name>
<serena> context edit <context-name>
<serena> context delete <context-name>
serena context --help
serena context list
serena context create <context-name>
serena context edit <context-name>
serena context delete <context-name>
where `<serena>` 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,
<serena> mode --help
<serena> mode list
<serena> mode create <mode-name>
<serena> mode edit <mode-name>
<serena> mode delete <mode-name>
where `<serena>` is [your way of running Serena](020_running).
serena mode --help
serena mode list
serena mode create <mode-name>
serena mode edit <mode-name>
serena mode delete <mode-name>
## Advanced Configuration
docs/03-special-guides/serena_on_chatgpt.md
+1 -2
View File
@@ -17,7 +17,6 @@ Run the following command to launch Serena as http server (assuming port 8000):
```bash
uvx mcpo --port 8000 --api-key <YOUR_SECRET_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
```
---