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 (what we denote as the system_prompt), adjust the output of tools that just provide a prompt, and even adjust tool descriptions.

Serena is configured in four places:

  1. The serena_config.yml for general settings that apply to all clients and projects. It is located in your user directory under .serena/serena_config.yml. If you do not explicitly create the file, it will be auto-generated when you first run Serena. You can edit it directly or use

    uvx --from git+https://github.com/oraios/serena serena config edit

    (or use the --directory command version).

  2. In the arguments passed to the start-mcp-server in your client’s config (see below), which will apply to all sessions started by the respective client. In particular, the context parameter should be set appropriately for Serena to be best adjusted to existing tools and capabilities of your client. See for a detailed explanation. You can override all entries from the serena_config.yml through command line arguments.

  3. In the .serena/project.yml file within your project. This will hold project-level configuration that is used whenever that project is activated. This file will be autogenerated when you first use Serena on that project, but you can also generate it explicitly with

    uvx --from git+https://github.com/oraios/serena serena project generate-yml

    (or use the --directory command version).

  4. Through the context and modes (see below).

After the initial setup, continue with one of the sections below, depending on how you want to use Serena.

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#

A context defines the general environment in which Serena is operating. It influences the initial system prompt and the set of available tools. A context is set at startup when launching Serena (e.g., via CLI options for an MCP server or in the agent script) and cannot be changed during an active session.

Serena comes with pre-defined contexts:

  • desktop-app: Tailored for use with desktop applications like Claude Desktop. This is the default.

  • agent: Designed for scenarios where Serena acts as a more autonomous agent, for example, when used with Agno.

  • ide-assistant: Optimized for integration into IDEs like VSCode, Cursor, or Cline, focusing on in-editor coding assistance. Choose the context that best matches the type of integration you are using.

When launching Serena, specify the context using --context <context-name>. Note that for cases where parameter lists are specified (e.g. Claude Desktop), you must add two parameters to the list.

If you are using a local server (such as Llama.cpp) which requires you to use OpenAI-compatible tool descriptions, use context oaicompat-agent instead of agent.

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>

where <serena> is your way of running Serena.

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.

Examples of built-in modes include:

  • planning: Focuses Serena on planning and analysis tasks.

  • editing: Optimizes Serena for direct code modification tasks.

  • interactive: Suitable for a conversational, back-and-forth interaction style.

  • one-shot: Configures Serena for tasks that should be completed in a single response, often used with planning for generating reports or initial plans.

  • no-onboarding: Skips the initial onboarding process if it’s not needed for a particular session.

  • onboarding: (Usually triggered automatically) Focuses on the project onboarding process.

Modes can be set at startup (similar to contexts) but can also be switched dynamically during a session. You can instruct the LLM to use the switch_modes tool to activate a different set of modes (e.g., “Switch to planning and one-shot modes”).

When launching Serena, specify modes using --mode <mode-name>; multiple modes can be specified, e.g. --mode planning --mode no-onboarding.

:warning: Mode Compatibility: While you can combine modes, some may be semantically incompatible (e.g., interactive and one-shot). Serena currently does not prevent incompatible combinations; it is up to the user to choose sensible mode configurations.

You can manage contexts 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.

Contents