From 0e229586dc1795fd962cc3f2b3c4b2018d87aab8 Mon Sep 17 00:00:00 2001 From: Michael Panchenko Date: Sat, 4 Apr 2026 15:18:33 +0200 Subject: [PATCH] Readme, docs: clarified config file creation and JB plugin role Also added a sentence on using with the Codex app --- README.md | 14 ++++++++++---- docs/02-usage/025_jetbrains_plugin.md | 19 ++++++++++++++++--- docs/02-usage/030_clients.md | 8 +++++++- 3 files changed, 33 insertions(+), 8 deletions(-) diff --git a/README.md b/README.md index 3102dc65..be17cde6 100644 --- a/README.md +++ b/README.md @@ -47,7 +47,8 @@ complex projects! There are two alternative technologies powering these capabilities: -* **Language servers** implementing the language server Protocol (LSP) — the free/open-source alternative. +* **Language servers** implementing the language server Protocol (LSP) — the free/open-source alternative + which is used by default. * The **Serena JetBrains Plugin**, which leverages the powerful code analysis and editing capabilities of your JetBrains IDE (paid plugin; free trial available). @@ -180,16 +181,21 @@ https://github.com/user-attachments/assets/6eaa9aa1-610d-4723-a2d6-bf1e487ba753 > [!NOTE] > When using the language server backend, some additional dependencies to be installed for certain languages; see the [Language Support](https://oraios.github.io/serena/01-about/020_programming-languages.html) page for details. -**Starting the MCP Server**. The easiest way to start the Serena MCP server is by running the latest version from GitHub using uvx. -Issue this command to see available options: +**Starting the MCP Server**. The easiest way to start the Serena MCP server is by running the latest version from GitHub using uvx: ```bash -uvx -p 3.13 --from git+https://github.com/oraios/serena serena start-mcp-server --help +uvx -p 3.13 --from git+https://github.com/oraios/serena serena start-mcp-server ``` +If this is the first time you are starting Serena, the necessary configuration files will be created, and +you should see the Serena dashboard appear. You can terminate the server by pressing Ctrl+C (multiple times, if necessary). + **Configuring Your Client**. To connect Serena to your preferred MCP client, you typically need to [configure a launch command in your client](https://oraios.github.io/serena/02-usage/030_clients.html). Follow the link for specific instructions on how to set up Serena for Claude Code, Codex, Claude Desktop, MCP-enabled IDEs and other clients (such as local and web-based GUIs). +**Switching to the JetBrains Backend**. The default code intelligence backend for Serena is the free LSP backend. +For using the more powerful JetBrains backend, follow the instructions on the [JetBrains Plugin page](https://oraios.github.io/serena/02-usage/025_jetbrains_plugin.html). + > [!TIP] > While getting started quickly is easy, Serena is a powerful toolkit with many configuration options. > We highly recommend reading through the [user guide](https://oraios.github.io/serena/02-usage/000_intro.html) to get the most out of Serena. diff --git a/docs/02-usage/025_jetbrains_plugin.md b/docs/02-usage/025_jetbrains_plugin.md index 13fb7697..89007a6a 100644 --- a/docs/02-usage/025_jetbrains_plugin.md +++ b/docs/02-usage/025_jetbrains_plugin.md @@ -1,7 +1,11 @@ # The Serena JetBrains Plugin -The [JetBrains Plugin](https://plugins.jetbrains.com/plugin/28946-serena/) allows Serena to +The [JetBrains Plugin](https://plugins.jetbrains.com/plugin/28946-serena/) allows the Serena MCP server to leverage the powerful code analysis and editing capabilities of your JetBrains IDE. +This page explains how to install the plugin and how to configure Serena for using it. +You will still need to set up the Serena MCP server +itself, so make sure to follow the [installation instructions](020_running.md) and connect the MCP server to your +LLM-based client as described in [client setup](030_clients.md) in addition to following the instructions below. ```{raw} html

@@ -61,9 +65,18 @@ After installing the plugin, you need to configure Serena to use it. **Central Configuration**. -Edit the global Serena configuration file located at `~/.serena/serena_config.yml` +If you ever executed Serena before, you will have the global Serena configuration file located at `~/.serena/serena_config.yml` (`%USERPROFILE%\.serena\serena_config.yml` on Windows). -Change the `language_backend` setting as follows: + +If the configuration file does not exist, run + +```shell +uvx -p 3.13 --from git+https://github.com/oraios/serena serena start-mcp-server +``` + +(see [running Serena](020_running.md) for alternative options) to install all dependencies and create configuration files. Terminate the server with `Ctrl+C` after it has started. + +In your configuration, change the `language_backend` setting as follows: ```yaml language_backend: JetBrains diff --git a/docs/02-usage/030_clients.md b/docs/02-usage/030_clients.md index e0c13e73..117a77ce 100644 --- a/docs/02-usage/030_clients.md +++ b/docs/02-usage/030_clients.md @@ -147,7 +147,7 @@ While serena can be directly installed from the GitHub MCP server registry, we r ## 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.). +Serena works with OpenAI's Codex CLI and app 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.). Add a [run command](020_running) to `~/.codex/config.toml` to configure Serena for all Codex sessions; create the file if it does not exist. @@ -162,6 +162,12 @@ args = ["-p", "3.13", "--from", "git+https://github.com/oraios/serena", "serena" The larger startup timeout is to permit uvx to download the necessary dependencies. Once downloaded, the startup time is much faster. +:::{note} +The codex app does not start a session in the project's directory, so when using the app, you will have to +ask Codex to "Activate the current dir as project using serena" at the start of each session. +This is not necessary when using the codex CLI. +::: + :::{attention} Codex currently ignores the [instructions](https://blog.modelcontextprotocol.io/posts/2025-11-03-using-server-instructions/) property of MCP servers, so it is recommended to prompt the agent to