From 774333befc7e5ab57fd0077efef5a4a0a9eeda39 Mon Sep 17 00:00:00 2001 From: Dominik Jain Date: Fri, 7 Nov 2025 20:30:17 +0100 Subject: [PATCH] Improve docs on contexts and modes --- docs/02-usage/050_configuration.md | 28 +++++++++++++++++++++++++--- docs/02-usage/999_detailed-usage.md | 21 --------------------- 2 files changed, 25 insertions(+), 24 deletions(-) diff --git a/docs/02-usage/050_configuration.md b/docs/02-usage/050_configuration.md index ee9a2120..31de3420 100644 --- a/docs/02-usage/050_configuration.md +++ b/docs/02-usage/050_configuration.md @@ -41,7 +41,7 @@ These allow for a high degree of customization to best suit your workflow and th #### Contexts -A context defines the general environment in which Serena is operating. +A **context** defines the general environment in which Serena is operating. It influences the initial system prompt and the set of available tools. A context is set at startup when launching Serena (e.g., via CLI options for an MCP server or in the agent script) and cannot be changed during an active session. @@ -57,6 +57,16 @@ Note that for cases where parameter lists are specified (e.g. Claude Desktop), y If you are using a local server (such as Llama.cpp) which requires you to use OpenAI-compatible tool descriptions, use context `oaicompat-agent` instead of `agent`. +You can manage contexts using the `context` command, + + context --help + context list + context create + context edit + context delete + +where `` is [your way of running Serena](020_running). + #### Modes Modes further refine Serena's behavior for specific types of tasks or interaction styles. Multiple modes can be active simultaneously, allowing you to combine their effects. Modes influence the system prompt and can also alter the set of available tools by excluding certain ones. @@ -70,8 +80,20 @@ Examples of built-in modes include: * `no-onboarding`: Skips the initial onboarding process if it's not needed for a particular session. * `onboarding`: (Usually triggered automatically) Focuses on the project onboarding process. -Modes can be set at startup (similar to contexts) but can also be _switched dynamically_ during a session. You can instruct the LLM to use the `switch_modes` tool to activate a different set of modes (e.g., "switch to planning and one-shot modes"). +Modes can be set at startup (similar to contexts) but can also be _switched dynamically_ during a session. +You can instruct the LLM to use the `switch_modes` tool to activate a different set of modes (e.g., "Switch to planning and one-shot modes"). When launching Serena, specify modes using `--mode `; multiple modes can be specified, e.g. `--mode planning --mode no-onboarding`. -:warning: **Mode Compatibility**: While you can combine modes, some may be semantically incompatible (e.g., `interactive` and `one-shot`). Serena currently does not prevent incompatible combinations; it is up to the user to choose sensible mode configurations. +:warning: **Mode Compatibility**: While you can combine modes, some may be semantically incompatible (e.g., `interactive` and `one-shot`). +Serena currently does not prevent incompatible combinations; it is up to the user to choose sensible mode configurations. + +You can manage contexts using the `mode` command, + + mode --help + mode list + mode create + mode edit + mode delete + +where `` is [your way of running Serena](020_running). \ No newline at end of file diff --git a/docs/02-usage/999_detailed-usage.md b/docs/02-usage/999_detailed-usage.md index 53dc4b27..a1471134 100644 --- a/docs/02-usage/999_detailed-usage.md +++ b/docs/02-usage/999_detailed-usage.md @@ -30,27 +30,6 @@ allowing all analysis and exploration capabilities. In general, be sure to back up your work and use a version control system in order to avoid losing any work. -#### Customization - -You can create your own contexts and modes to precisely tailor Serena to your needs in two ways: - -* You can use Serena's CLI to manage modes and contexts. Check out - - ```shell - uvx --from git+https://github.com/oraios/serena serena mode --help - ``` - - and - - ```shell - uvx --from git+https://github.com/oraios/serena serena context --help - ``` - - _NOTE_: Custom contexts/modes are simply YAML files in `/.serena`, they are automatically registered and available for use by their name (filename without the `.yml` extension). If you don't want to use Serena's CLI, you can create and manage them in any way you see fit. -* **Using external YAML files**: When starting Serena, you can also provide an absolute path to a custom `.yml` file for a context or mode. - -This customization allows for deep integration and adaptation of Serena to specific project requirements or personal preferences. - ### Prepare Your Project #### Structure Your Codebase