Contexts and Modes

Serena employs a flexible configuration system based on Contexts and Modes to define how an AI agent interacts with the user and the codebase. These components determine the set of available tools, provide specific system prompt instructions, and tailor the agent's behavior to the environment in which it is running (e.g., a terminal-based chat versus an IDE plugin).

Modes allow for dynamic adjustments to the agent's capabilities—such as switching between "planning" and "editing" tasks—while Contexts define the immutable operational environment established at startup. Both systems rely on YAML-based definitions that can be overridden or extended by users.

Sources: src/serena/config/context_mode.py:18-22, src/serena/resources/config/prompt_templates/system_prompt.yml:58-61, src/serena/config/serena_config.py:112-132

Core Architecture

The system is built around the ToolInclusionDefinition base class, which allows both Contexts and Modes to specify which tools are included or excluded from the agent's toolkit.

Class Hierarchy and Relationships

The following diagram illustrates the relationship between the configuration classes and how they manage tool availability.

Agent Modes

A Mode represents a specific state or operational strategy. An agent can operate in multiple modes simultaneously. Modes provide Jinja2-templated prompts that are injected into the final system prompt to guide the LLM's logic and tool selection for specific tasks like refactoring or symbolic editing.

Mode Definition and Types

Modes are typically loaded from YAML files found in internal resource directories or user-defined paths.

Sources: src/serena/config/context_mode.py:27-52, src/serena/config/context_mode.py:65-80

Operational Logic of Modes

When multiple modes are active, their tool inclusion/exclusion lists are merged. The final set of modes is derived from a combination of "base modes" (guaranteed to be included), "default modes" (configurable globally or per-project), and "added modes."

Agent Contexts

A Context defines the environmental constraints under which the agent is operating. Unlike Modes, an agent belongs to exactly one Context throughout its lifecycle.

Context Characteristics

Contexts are used to customize tool descriptions for specific LLM clients (like Claude Code) and to enforce project-handling rules.

• Single Project Mode: If single_project is true, the agent is restricted to one project, and project-switching tools (e.g., activate_project) are disabled.
• Tool Description Overrides: Contexts can provide custom descriptions for tools to improve the LLM's understanding of how to use them in that specific interface.
• Prompt Templating: Similar to modes, contexts provide a prompt template that describes the interaction style expected in that context.

Sources: src/serena/config/context_mode.py:127-160, src/serena/resources/config/prompt_templates/system_prompt.yml:103-120

Configuration and Selection

Contexts and Modes are selected during the startup of the Serena MCP server or via the CLI.

CLI Selection

The serena start-mcp-server command allows users to specify the context and modes:

• --context: Specifies the environment (defaults to claude-code).
• --mode: Overrides the default modes defined in the configuration.
• --add-mode: Appends additional modes to the existing selection.

Sources: src/serena/cli.py:237-255

Default Hierarchy

The project template illustrates how these are prioritized:

1. Base Modes: Hardcoded defaults (e.g., interactive, editing).
2. Default Modes: Set in serena_config.yml or project.yml.
3. Added Modes: Specific to the project or CLI.

Sources: src/serena/resources/project.template.yml:109-122, src/serena/config/serena_config.py:141-150

Implementation Example: Editing Mode

The editing.yml mode provides a concrete example of how modes influence agent behavior by guiding the choice between symbolic editing and file-based editing.

description: All tools, with detailed instructions for code editing
prompt: |  
  Use symbolic editing tools whenever possible for precise code modifications.
  ...
  **Symbolic editing**
  If you need to replace the definition of a symbol, use the `replace_symbol_body` tool.
  ...
  **File-based editing**
  The `replace_content` tool allows you to perform regex-based replacements...
excluded_tools:
 - replace_lines
 - insert_at_line
 - delete_lines

Sources: src/serena/resources/config/modes/editing.yml:1-35

Conclusion

Contexts and Modes provide a decoupled architecture for defining agent behavior. By separating environmental constraints (Contexts) from task-specific capabilities (Modes), Serena allows for a highly granular configuration that adapts the same core symbolic tools to diverse development workflows and AI clients.