Serena

# 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 ```shell 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](contexts) 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 create it explicitly with `serena project create [options]` (see the [](project-creation-indexing) for details on available options). 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)= ### 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](020_running). (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. 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](020_running).