Revise context prompts/descriptions #742

* Rename 'ide-assistant' to 'claude-code' (backwards-compatible)
* Add new mode 'ide' (basically the same as 'claude-code')

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

@@ -182,6 +182,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)
 

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