Multi-language Prompts (Interprompt)

Relevant source files

The following files were used as context for generating this wiki page:

• src/serena/resources/config/prompt_templates/system_prompt.yml
• src/serena/resources/config/prompt_templates/simple_tool_outputs.yml
• src/serena/resources/config/modes/editing.yml
• src/serena/resources/config/modes/onboarding.yml
• src/serena/resources/config/modes/interactive.yml
• src/serena/cli.py
• src/serena/config/serena_config.py

The Multi-language Prompt (Interprompt) system in Serena provides a modular architecture for constructing complex instructions for AI agents. This system leverages YAML-based templates and dynamic "modes" to tailor the agent's behavior based on the specific programming language, project context, and operational requirements. By centralizing instructions in the src/serena/resources/config/prompt_templates/ and modes/ directories, the project ensures consistent tool usage and reasoning patterns across different LLM clients.

Architecture and Components

The Interprompt system is built upon three primary pillars: the base system prompt, context-specific prompts, and operational modes. These components are combined dynamically using Jinja2-style templating to generate a final system instruction set.

Prompt Composition Flow

The construction of the final prompt involves gathering the base template, injecting information about available tools, and appending mode-specific instructions.

Core Components

Component	File Reference	Purpose
System Prompt Template	system_prompt.yml	Defines core logic for resource-efficient code reading and symbolic tool navigation.
Operational Modes	modes/*.yml	Contextual overrides (e.g., editing, onboarding) that restrict tools and add behavior instructions.
Simple Tool Outputs	simple_tool_outputs.yml	Fixed text blocks used to guide agent thinking or project onboarding.
CLI Prompt Factory	cli.py	Command-line interface for printing or overriding prompts for specific clients like Claude Code.

Sources: src/serena/resources/config/prompt_templates/system_prompt.yml:1-10, src/serena/resources/config/modes/editing.yml:1-5, src/serena/cli.py:925-933

Symbolic Reasoning Instructions

A critical aspect of the Interprompt system is the instruction set that guides the agent to use symbolic tools rather than primitive text searches. The system_prompt.yml contains detailed logic on when to use specific tools based on the project's features.

Symbolic Tool Selection Logic

The prompt instructs the agent to avoid reading full files unless necessary. It promotes a workflow of:

1. Overview: Using get_symbols_overview to understand file structure.
2. Specific Retrieval: Using find_symbol with include_body=True for targeted reading.
3. Relationship Analysis: Using find_referencing_symbols to understand dependencies.

Sources: src/serena/resources/config/prompt_templates/system_prompt.yml:25-39

Claude Code Override

The system includes a specific override template (cc_system_prompt_override) designed for the Claude Code CLI. This prompt forces the agent to map standard built-in commands (like grep or read) to Serena's semantic equivalents.

Operational Modes

Modes are dynamic configuration fragments that modify the agent's prompt and available toolset. These are defined in individual YAML files.

Mode Descriptions

• Editing Mode: Focuses on precise modifications. It instructs the agent to use replace_symbol_body for full symbols and replace_content (regex) for granular changes.
• Onboarding Mode: Restricts the agent to read-only tools. The goal is to collect project information and populate memories without modifying source code.
• Interactive Mode: Encourages the agent to ask clarification questions and break down complex tasks into smaller, user-approved steps.

Sources: src/serena/resources/config/modes/editing.yml:10-33, src/serena/resources/config/modes/onboarding.yml:1-10, src/serena/resources/config/modes/interactive.yml:1-10

Implementation of Mode Exclusions

Modes can explicitly disable tools to ensure the agent follows specific constraints (e.g., read-only during onboarding).

# Example from onboarding.yml
excluded_tools:
  - create_text_file
  - replace_symbol_body
  - insert_after_symbol
  - delete_lines

Sources: src/serena/resources/config/modes/onboarding.yml:12-20

Memory Management Prompts

The Interprompt system facilitates a durable memory layout for long-lived workflows. The onboarding_prompt in simple_tool_outputs.yml defines a strict schema for memory storage.

Memory Name	Description
mem:core	Top-level source map and project-wide invariants.
mem:tech_stack	Frameworks, languages, and version pins.
mem:conventions	Code style, naming, and design patterns.
mem:task_completion	Commands to run for validation (linting, tests).

Sources: src/serena/resources/config/prompt_templates/simple_tool_outputs.yml:12-28

Conclusion

The Multi-language Prompt (Interprompt) system is the instructional core of Serena. It transforms a standard LLM into a specialized software engineering agent by providing deep integration instructions for symbolic tools, enforcing project-specific operational modes, and establishing a standardized memory architecture. This modular approach allows Serena to adapt to various clients and complex coding environments while maintaining resource efficiency.