Merge pull request #810 from oraios/revise-prompts

Revise prompts

DOCKER.md

@@ -98,7 +98,7 @@ services:
       - /path/to/another/project:/workspace/another-project
     # Add the context for the IDE assistant option:
     command:
-      - "uv run --directory . serena-mcp-server --transport sse --port 9121 --host 0.0.0.0 --context ide-assistant"
+      - "uv run --directory . serena-mcp-server --transport sse --port 9121 --host 0.0.0.0 --context claude-code"
 ```
 
 See the [Docker Merge Compose files documentation](https://docs.docker.com/compose/how-tos/multiple-compose-files/merge/) for more details on using merge files.

docs/02-usage/030_clients.md

@@ -13,14 +13,14 @@ Serena is a great way to make Claude Code both cheaper and more powerful!
 From your project directory, add serena with a command like this,
 
 ```shell
-claude mcp add serena -- <serena> start-mcp-server --context ide-assistant --project "$(pwd)"
+claude mcp add serena -- <serena> start-mcp-server --context claude-code --project "$(pwd)"
 ```
 
 where `<serena>` is [your way of running Serena](020_running).  
 For example, when using `uvx`, the above command becomes
 
 ```shell
-claude mcp add serena -- uvx --from git+https://github.com/oraios/serena serena start-mcp-server --context ide-assistant --project "$(pwd)"
+claude mcp add serena -- uvx --from git+https://github.com/oraios/serena serena start-mcp-server --context claude-code --project "$(pwd)"
 ```
 
 Note:

docs/02-usage/050_configuration.md

@@ -44,9 +44,14 @@ A context is set at startup when launching Serena (e.g., via CLI options for an
 Serena comes with pre-defined contexts:
 
 * `desktop-app`: Tailored for use with desktop applications like Claude Desktop. This is the default.
+  The full set of Serena's tools is provided, as the application is assumed to have no prior coding-specific capabilities.
+* `claude-code`: Optimized for use with Claude Code, it disables tools that would duplicate Claude Code's built-in capabilities.
+* `codex`: Optimized for use with OpenAI Codex.
+* `ide`: Generic context for IDE assistants/coding agents, e.g. VSCode, Cursor, or Cline, focusing on augmenting existing capabilities.
+  Basic file operations and shell execution are assumed to be handled by the assistant's own capabilities.
 * `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.
+
+* Choose the context that best matches the type of integration you are using.
 
 Find the concrete definitions of these modes [here](https://github.com/oraios/serena/tree/main/src/serena/resources/config/contexts).
 

src/serena/config/context_mode.py

@@ -4,7 +4,6 @@ Context and Mode configuration loader
 
 import os
 from dataclasses import dataclass, field
-from enum import Enum
 from pathlib import Path
 from typing import TYPE_CHECKING, Self
 
@@ -182,6 +181,16 @@ class SerenaAgentContext(ToolInclusionDefinition, ToStringMixin):
     @classmethod
     def from_name(cls, name: str) -> Self:
         """Load a registered Serena context."""
+        legacy_name_mapping = {
+            "ide-assistant": "claude-code",
+        }
+        if name in legacy_name_mapping:
+            log.warning(
+                f"Context name '{name}' is deprecated and has been renamed to '{legacy_name_mapping[name]}'. "
+                f"Please update your configuration; refer to the configuration guide for more details: "
+                "https://oraios.github.io/serena/02-usage/050_configuration.html#contexts"
+            )
+            name = legacy_name_mapping[name]
         context_path = cls.get_path(name)
         return cls.from_yaml(context_path)
 
@@ -214,35 +223,3 @@ class SerenaAgentContext(ToolInclusionDefinition, ToStringMixin):
         print(f"{self.name}:\n {self.description}")
         if self.excluded_tools:
             print(" excluded tools:\n  " + ", ".join(sorted(self.excluded_tools)))
-
-
-class RegisteredContext(Enum):
-    """A registered context."""
-
-    IDE_ASSISTANT = "ide-assistant"
-    """For Serena running within an assistant that already has basic tools, like Claude Code, Cline, Cursor, etc."""
-    DESKTOP_APP = "desktop-app"
-    """For Serena running within Claude Desktop or a similar app which does not have built-in tools for code editing."""
-    AGENT = "agent"
-    """For Serena running as a standalone agent, e.g. through agno."""
-
-    def load(self) -> SerenaAgentContext:
-        """Load the context."""
-        return SerenaAgentContext.from_name(self.value)
-
-
-class RegisteredMode(Enum):
-    """A registered mode."""
-
-    INTERACTIVE = "interactive"
-    """Interactive mode, for multi-turn interactions."""
-    EDITING = "editing"
-    """Editing tools are activated."""
-    PLANNING = "planning"
-    """Editing tools are deactivated."""
-    ONE_SHOT = "one-shot"
-    """Non-interactive mode, where the goal is to finish a task autonomously."""
-
-    def load(self) -> SerenaAgentMode:
-        """Load the mode."""
-        return SerenaAgentMode.from_name(self.value)

src/serena/resources/config/contexts/agent.yml

@@ -1,7 +1,6 @@
-description: All tools except InitialInstructionsTool for agent context
+description: Agent context where the system prompt (initial instructions) are provided at startup
 prompt: |
-  You are running in agent context where the system prompt is provided externally. You should use symbolic
-  tools when possible for code understanding and modification.
+  You are running in an agent context.
 excluded_tools:
   - initial_instructions
 

src/serena/resources/config/contexts/chatgpt.yml

@@ -1,4 +1,4 @@
-description: A configuration specific for chatgpt, which has a limit of 30 tools and requires short descriptions.
+description: A configuration specific for ChatGPT, which has a limit of 30 tools and requires short descriptions.
 prompt: |
   You are running in desktop app context where the tools give you access to the code base as well as some
   access to the file system, if configured. You interact with the user through a chat interface that is separated

src/serena/resources/config/contexts/claude-code.yml

@@ -0,0 +1,26 @@
+description: Claude Code (CLI agent where file operations, basic edits, etc. are already covered; single project mode)
+prompt: |
+  You are running in a CLI coding agent context where file operations, basic (line-based) edits and reads 
+  as well as shell commands are handled by your own, internal tools.
+  
+  If Serena's tools can be used to achieve your task, you should prioritize them.
+  In particular, it is important that you avoid reading entire source code files unless it is strictly necessary!
+  Instead, for exploring and reading code in a token-efficient manner, use Serena's overview and symbolic search tools.
+  For non-code files or for reads where you don't know the symbol's name path, you can use the pattern search tool.
+
+excluded_tools:
+  - create_text_file
+  - read_file
+  - execute_shell_command
+  - prepare_for_new_conversation
+  - replace_content
+
+tool_description_overrides: {}
+
+# whether to assume that Serena shall only work on a single project in this context (provided that a project is given
+# when Serena is started).
+# If set to true and a project is provided at startup, the set of tools is limited to those required by the project's
+# concrete configuration, and other tools are excluded completely, allowing the set of tools to be minimal.
+# Tools explicitly disabled by the project will not be available at all.
+# The `activate_project` tool is always disabled in this case, as project switching cannot be allowed.
+single_project: true

src/serena/resources/config/contexts/codex.yml

@@ -1,20 +1,13 @@
-description: Non-symbolic editing tools and general shell tool are excluded
+description: Codex Non-symbolic editing tools and general shell tool are excluded
 prompt: |
-  You are running in IDE assistant context where file operations, basic (line-based) edits and reads, 
-  and shell commands are handled by your own, internal tools.
-  The initial instructions and the current config inform you on which tools are available to you,
-  and how to use them.
-  Don't attempt to use any excluded tools, instead rely on your own internal tools
-  for achieving the basic file or shell operations.
+  You are running in the Codex IDE assistant mode, where file operations, basic (line-based) edits and reads 
+  as well as shell commands are handled by your own, internal tools.
+  Don't attempt to use any excluded tools; instead, rely on your own internal tools for basic file or shell operations.
   
-  If serena's tools can be used for achieving your task, 
-  you should prioritize them. In particular, it is important that you avoid reading entire source code files,
-  unless it is strictly necessary! Instead, for exploring and reading code in a token-efficient manner, 
-  you should use serena's overview and symbolic search tools. The call of the read_file tool on an entire source code 
-  file should only happen in exceptional cases, usually you should first explore the file (by itself or as part of exploring
-  the directory containing it) using the symbol_overview tool, and then make targeted reads using find_symbol and other symbolic tools.
-  For non-code files or for reads where you don't know the symbol's name path you can use the patterns searching tool,
-  using the read_file as a last resort.
+  If Serena's tools can be used to achieve your task, you should prioritize them. 
+  In particular, it is important that you avoid reading entire source code files unless it is strictly necessary! 
+  Instead, for exploring and reading code in a token-efficient manner, use Serena's overview and symbolic search tools. 
+  For non-code files or for reads where you don't know the symbol's name path, you can use the pattern search tool.
 
 excluded_tools:
   - create_text_file

src/serena/resources/config/contexts/desktop-app.yml

@@ -1,15 +1,13 @@
-description: All tools included for desktop app context
+description: Desktop application context (chat application detached from code) where Serena's full toolset is provided
 prompt: |
-  You are running in desktop app context where the tools give you access to the code base as well as some
-  access to the file system, if configured. You interact with the user through a chat interface that is separated
-  from the code base. As a consequence, if you are in interactive mode, your communication with the user should
+  You are running in a desktop application context.
+  Serena's tools give you access to the code base as well as some access to the file system (if enabled). 
+  You interact with the user through a chat interface that is separated from the code base. 
+  As a consequence, if you are in interactive mode, your communication with the user should
   involve high-level thinking and planning as well as some summarization of any code edits that you make.
-  For viewing the code edits the user will view them in a separate code editor window, and the back-and-forth
-  between the chat and the code editor should be minimized as well as facilitated by you.
-  If complex changes have been made, advise the user on how to review them in the code editor.
-  If complex relationships that the user asked for should be visualized or explained, consider creating
-  a diagram in addition to your text-based communication. Note that in the chat interface you have various rendering
-  options for text, html, and mermaid diagrams, as has been explained to you in your initial instructions.
+  To view the code edits you make, the user will have switch to a separate application.
+  To illustrate complex relationships, consider creating diagrams in addition to your text-based communication
+  (depending on the options for text, html, mermaid diagrams, etc. that you are provided with in your initial instructions).
 excluded_tools: []
 included_optional_tools:
   - switch_modes

src/serena/resources/config/contexts/ide-assistant.yml

@@ -1,34 +0,0 @@
-description: Non-symbolic editing tools and general shell tool are excluded
-prompt: |
-  You are running in IDE assistant context where file operations, basic (line-based) edits and reads, 
-  and shell commands are handled by your own, internal tools.
-  The initial instructions and the current config inform you on which tools are available to you,
-  and how to use them.
-  Don't attempt to use any excluded tools, instead rely on your own internal tools
-  for achieving the basic file or shell operations.
-  
-  If serena's tools can be used for achieving your task, 
-  you should prioritize them. In particular, it is important that you avoid reading entire source code files,
-  unless it is strictly necessary! Instead, for exploring and reading code in a token-efficient manner, 
-  you should use serena's overview and symbolic search tools. 
-  Before reading a full file, it is usually best to first explore the file using the symbol_overview tool, 
-  and then make targeted reads using find_symbol and other symbolic tools.
-  For non-code files or for reads where you don't know the symbol's name path, you can use the pattern searching tool,
-  and read full files only as a last resort.
-
-excluded_tools:
-  - create_text_file
-  - read_file
-  - execute_shell_command
-  - prepare_for_new_conversation
-  - replace_content
-
-tool_description_overrides: {}
-
-# whether to assume that Serena shall only work on a single project in this context (provided that a project is given
-# when Serena is started).
-# If set to true and a project is provided at startup, the set of tools is limited to those required by the project's
-# concrete configuration, and other tools are excluded completely, allowing the set of tools to be minimal.
-# Tools explicitly disabled by the project will not be available at all.
-# The `activate_project` tool is always disabled in this case, as project switching cannot be allowed.
-single_project: true

src/serena/resources/config/contexts/ide.yml

@@ -0,0 +1,25 @@
+description: Generic IDE coding agent context (basic file operations and shell operations assumed to be covered; single project mode)
+prompt: |
+  You are running in an IDE assistant context where file operations, basic (line-based) edits and reads, 
+  and shell commands are handled by your own, internal tools.
+  
+  If Serena's tools can be used to achieve your task, you should prioritize them.
+  In particular, it is important that you avoid reading entire source code files unless it is strictly necessary!
+  Instead, for exploring and reading code in a token-efficient manner, use Serena's overview and symbolic search tools.
+  For non-code files or for reads where you don't know the symbol's name path, you can use the pattern search tool.
+
+excluded_tools:
+  - create_text_file
+  - read_file
+  - execute_shell_command
+  - prepare_for_new_conversation
+
+tool_description_overrides: {}
+
+# whether to assume that Serena shall only work on a single project in this context (provided that a project is given
+# when Serena is started).
+# If set to true and a project is provided at startup, the set of tools is limited to those required by the project's
+# concrete configuration, and other tools are excluded completely, allowing the set of tools to be minimal.
+# Tools explicitly disabled by the project will not be available at all.
+# The `activate_project` tool is always disabled in this case, as project switching cannot be allowed.
+single_project: true

src/serena/resources/config/modes/editing.yml

@@ -1,39 +1,31 @@
 description: All tools, with detailed instructions for code editing
 prompt: |
-  You are operating in editing mode. You can edit files with the provided tools
-  to implement the requested changes to the code base while adhering to the project's code style and patterns.
+  You are operating in editing mode. You can edit files with the provided tools.
+  You adhere to the project's code style and patterns.
+  
   Use symbolic editing tools whenever possible for precise code modifications.
-  If no editing task has yet been provided, wait for the user to provide one.
+  If no explicit editing task has yet been provided, wait for the user to provide one. Do not be overly eager.
 
   When writing new code, think about where it belongs best. Don't generate new files if you don't plan on actually
-  integrating them into the codebase, instead use the editing tools to insert the code directly into the existing files in that case.
+  properly integrating them into the codebase.
 
-  You have two main approaches for editing code - editing at the symbol level and more file-based editing.
+  You have two main approaches for editing code: (a) editing at the symbol level and (b) file-based editing.
   The symbol-based approach is appropriate if you need to adjust an entire symbol, e.g. a method, a class, a function, etc.
-  But it is not appropriate if you need to adjust just a few lines of code within a symbol.
+  It is not appropriate if you need to adjust just a few lines of code within a larger symbol.
 
-  Let us first discuss the symbol-based approach.
-  Symbols are identified by their name path and relative file path (description of the `find_symbol` tool).
-  You can get information about available symbols by using the `get_symbols_overview` tool for finding top-level symbols in a file,
-  or by using `find_symbol` if you already know the symbol's name path. You generally try to read as little code as possible
-  while still solving your task, meaning you only read the bodies when you need to, and after you have found the symbol you want to edit.
-  Before calling symbolic reading tools, you should have a basic understanding of the repository structure that you can get from memories
-  or by using the `list_dir` and `find_file` tools (or similar).
-  For example, if you are working with python code and already know that you need to read the body of the constructor of the class Foo, you can directly
-  use `find_symbol` with the name path `Foo/__init__` and `include_body=True`. If you don't know yet which methods in `Foo` you need to read or edit,
-  you can use `find_symbol` with the name path `Foo`, `include_body=False` and `depth=1` to get all (top-level) methods of `Foo` before proceeding
-  to read the desired methods with `include_body=True`.
-  In particular, keep in mind the description of the `replace_symbol_body` tool. If you want to add some new code at the end of the file, you should
-  use the `insert_after_symbol` tool with the last top-level symbol in the file. If you want to add an import, often a good strategy is to use
-  `insert_before_symbol` with the first top-level symbol in the file.
-  You can understand relationships between symbols by using the `find_referencing_symbols` tool. If not explicitly requested otherwise by a user,
-  you make sure that when you edit a symbol, it is either done in a backward-compatible way, or you find and adjust the references as needed.
-  The `find_referencing_symbols` tool will give you code snippets around the references, as well as symbolic information.
-  You will generally be able to use the info from the snippets and the regex-based approach to adjust the references as well.
-  You can assume that all symbol editing tools are reliable, so you don't need to verify the results if the tool returns without error.
+  **Symbolic editing**
+  Use symbolic retrieval tools to identify the symbols you need to edit.
+  If you need to replace the definition of a symbol, use the `replace_symbol_body` tool.
+  If you want to add some new code at the end of the file, use the `insert_after_symbol` tool with the last top-level symbol in the file. 
+  Similarly, you can use `insert_before_symbol` with the first top-level symbol in the file to insert code at the beginning of a file.
+  You can understand relationships between symbols by using the `find_referencing_symbols` tool. If not explicitly requested otherwise by the user,
+  you make sure that when you edit a symbol, the change is either backward-compatible or you find and update all references as needed.
+  The `find_referencing_symbols` tool will give you code snippets around the references as well as symbolic information.
+  You can assume that all symbol editing tools are reliable, so you never need to verify the results if the tools return without error.
 
   {% if 'replace_content' in available_tools %}
-  The `replace_content` tool allows you to perform regex-based replacements within files.
+  **File-based editing**
+  The `replace_content` tool allows you to perform regex-based replacements within files (as well as simple string replacements).
   This is your primary tool for editing code whenever replacing or deleting a whole symbol would be a more expensive operation,
   e.g. if you need to adjust just a few lines of code within a method.
   You are extremely good at regex, so you never need to check whether the replacement produced the correct result.

src/serena/resources/config/modes/interactive.yml

@@ -6,6 +6,6 @@ prompt: |
   Break down complex tasks into smaller steps and explain your thinking at each stage. When you're uncertain about
   a decision, present options to the user and ask for guidance rather than making assumptions.
   
-  Focus on providing informative results for intermediate steps so the user can follow along with your progress and
+  Focus on providing informative results for intermediate steps, such that the user can follow along with your progress and
   provide feedback as needed.
 excluded_tools: []

src/serena/resources/config/modes/mode.template.yml

@@ -1,7 +1,8 @@
 # See Serena's documentation for more details on concept of modes.
-description: Description of the mode, not used in the code.
-prompt: Prompt that will form part of the message sent to the model when activating this mode.
+description: Description of the mode (meta-information only)
+prompt: |
+  Provide a prompt that will form part of the instructions sent to the model when this mode is activated.
+# tools that are to be excluded by this mode
 excluded_tools: []
-
 # several tools are excluded by default and have to be explicitly included by the user
 included_optional_tools: []

src/serena/resources/config/modes/planning.yml

@@ -1,8 +1,7 @@
 description: Only read-only tools, focused on analysis and planning
 prompt: |
   You are operating in planning mode. Your task is to analyze code but not write any code.
-  The user may ask you to assist in creating a comprehensive plan, or to learn something about the codebase -
-  either a small aspect of it or about the whole project.
+  The user may ask you to assist in creating a comprehensive plan, or to learn something about the codebase.
 excluded_tools:
   - create_text_file
   - replace_symbol_body

test/conftest.py

@@ -1,4 +1,6 @@
 import logging
+import os
+import platform
 from pathlib import Path
 
 import pytest
@@ -144,3 +146,9 @@ def project(request: LanguageParamRequest):
 
     language = request.param
     yield create_default_project(language)
+
+
+is_ci = os.getenv("CI") == "true" or os.getenv("GITHUB_ACTIONS") == "true"
+
+# We skip Java tests in CI if not on Windows (hangs on Ubuntu for unknown reasons; testing on Windows is sufficient)
+java_tests_enabled = not is_ci or platform.system() == "Windows"

test/serena/test_serena_agent.py

@@ -11,7 +11,7 @@ from serena.config.serena_config import ProjectConfig, RegisteredProject, Serena
 from serena.project import Project
 from serena.tools import FindReferencingSymbolsTool, FindSymbolTool
 from solidlsp.ls_config import Language
-from test.conftest import get_repo_path
+from test.conftest import get_repo_path, java_tests_enabled
 
 
 @pytest.fixture
@@ -56,6 +56,9 @@ def serena_config():
 @pytest.fixture
 def serena_agent(request: pytest.FixtureRequest, serena_config):
     language = Language(request.param)
+    if language == Language.JAVA and not java_tests_enabled:
+        pytest.skip("Java tests are not enabled")
+
     project_name = f"test_repo_{language}"
 
     return SerenaAgent(project=project_name, serena_config=serena_config)

test/solidlsp/java/test_java_basic.py

@@ -1,16 +1,12 @@
 import os
-import platform
 
 import pytest
 
 from solidlsp import SolidLanguageServer
 from solidlsp.ls_config import Language
 from solidlsp.ls_utils import SymbolUtils
+from test.conftest import java_tests_enabled
 
-# These marks will be applied to all tests in this module.
-# We skip the tests if not on Windows (CI hangs on Ubuntu for unknown reasons; testing on Windows is sufficient)
-is_ci = os.getenv("CI") == "true" or os.getenv("GITHUB_ACTIONS") == "true"
-java_tests_enabled = not is_ci or platform.system() == "Windows"
 pytestmark = [pytest.mark.java, pytest.mark.skipif(not java_tests_enabled, reason="Java tests are only run on Windows in CI")]