Configuration Hierarchy
Relevant source files
The following files were used as context for generating this wiki page:
Serena employs a multi-layered configuration system designed to offer both global stability and per-project flexibility. The system allows for fine-grained control over language backends, tool availability, and operational modes, enabling the agent to adapt to diverse codebases ranging from single-file scripts to complex monorepos.
The hierarchy moves from global defaults to project-specific overrides, and finally to transient runtime configurations such as execution modes or CLI parameters. This structure ensures that security settings (like trusted projects) are maintained globally while development preferences (like specific language servers or memory patterns) are managed at the project level.
Sources: src/serena/config/serena_config.py:596-613, README.md:195-202
Hierarchy Architecture
The configuration logic is structured into four primary layers. Each subsequent layer can override or extend the settings defined in the layers above it.
- Global Configuration (
serena_config.yml): Defines the default behavior for all projects, including the global language backend, log levels, and trusted path patterns. - Project Configuration (
project.yml): Located within a project's.serena/directory, this file defines project-specific settings like languages, ignored paths, and required tools. - Local Project Overrides (
project.local.yml): Allows individual developers to override project settings locally without committing those changes to version control. - Operational Modes and Contexts: Dynamically composable fragments (e.g., "editing", "interactive") that adjust tool descriptions and system prompts at runtime.
Configuration Flow Diagram
The following diagram illustrates how Serena resolves configuration values by traversing the hierarchy.
The flow represents the priority of settings, where the bottom-most layer (Modes/Runtime) provides the final values used by the MCP server.
Sources: src/serena/config/serena_config.py:447-459, README.md:196-202
Global Configuration
The SerenaConfig class manages the global settings stored in the user's home directory (typically ~/.serena/serena_config.yml). It serves as the source of truth for the list of registered projects and system-wide operational parameters.
Key Global Parameters
| Parameter | Type | Description |
|---|---|---|
language_backend | Enum | The default backend (LSP or JetBrains) used for analysis. |
trusted_project_path_patterns | List[str] | Glob patterns for project roots allowed to use advanced settings. |
project_serena_folder_location | String | Template for where .serena metadata folders are stored. |
projects | List[RegisteredProject] | List of absolute paths to known project roots. |
tool_timeout | Float | Maximum time allowed for a single tool execution. |
Sources: src/serena/config/serena_config.py:616-680, src/serena/config/serena_config.py:734-738
Project-Level Configuration
Project configuration is handled by the ProjectConfig class. When a project is initialized, Serena automatically detects the programming language composition and generates a project.yml file.
Overrides and Extensions
Project-level settings can either override or extend global settings:
- Overrides: Parameters like
language_backendorline_endingreplace the global value if defined in the project. - Extensions: Parameters like
ignored_pathsorread_only_memory_patternsare merged additively with global lists.
Sources: src/serena/config/serena_config.py:343-356, src/serena/config/serena_config.py:382-390, src/serena/resources/project.template.yml:68-75
Implementation Detail: Configuration Merging
The loading process for project configuration follows a specific sequence to ensure project.local.yml takes precedence over project.yml.
Tool and Mode Selection
The configuration hierarchy also determines which tools are exposed to the LLM. This is controlled via ToolInclusionDefinition, which supports three modes:
- Incremental (Exclusion): Excluding specific tools from the default set.
- Incremental (Optional): Enabling specific optional tools.
- Fixed Mode: Specifying an exact list of allowed tools, ignoring defaults.
Mode Composition
The final set of active modes is calculated as:
base_modes (Global) + default_modes (Global/Project) + added_modes (Project/Runtime).
Sources: src/serena/config/serena_config.py:145-163, src/serena/resources/project.template.yml:109-122
Example: Editing Mode
The "editing" mode (editing.yml) demonstrates how runtime fragments modify the hierarchy by excluding primitive line-editing tools in favor of symbolic tools.
description: All tools, with detailed instructions for code editing
prompt: |
Use symbolic editing tools whenever possible for precise code modifications.
excluded_tools:
- replace_lines
- insert_at_line
- delete_lines
Sources: src/serena/resources/config/modes/editing.yml:1-32
Summary of Resolution Logic
Serena's configuration resolution ensures that the system is "project-aware." By resolving the .serena folder location using placeholders like $projectDir, the system can support both "in-project" configurations (stored in the repo) and "centralized" configurations (stored externally). This flexibility, combined with the layered override system, allows Serena to scale from individual developer preferences to project-wide standards.
Sources: src/serena/config/serena_config.py:894-910, README.md:195-202