mirror of
https://github.com/tiennm99/serena.git
synced 2026-10-13 22:16:23 +00:00
Improve documentation (particularly on configuration) and the issue template
This commit is contained in:
Dominik Jain committed
1 parent
7c1cc2ad0e
commit
1c17d61121
6 files changed
+116
-57
No files matched your search
@@ -1,5 +1,5 @@
|
||||
---
|
||||
name: Issue (bug, performance problem, question)
|
||||
name: Issue (bug, performance problem, etc.)
|
||||
about: General Issue
|
||||
title: ''
|
||||
labels: ''
|
||||
@@ -9,19 +9,20 @@ assignees: ''
|
||||
|
||||
I have:
|
||||
|
||||
- [ ] Read the readme and verified that the issue cannot be solved by adjusting configuration
|
||||
- [ ] Understood that Serena's dashboard can be disabled through the config
|
||||
- [ ] Understood that by default a client session will start a separate instance of a Serena server.
|
||||
- [ ] Understood that for multi-agent setups, the SSE mode should be used.
|
||||
- [ ] Verified that non-project files are ignored using either gitignore or the corresponding setting in `.serena/project.yml`
|
||||
- [ ] Have looked for similar issues and discussions, including closed ones
|
||||
- [ ] Made sure it's an actual issue and not a question - those should be opened as discussion instead.
|
||||
- [ ] read the relevant parts of the documentation and verified that the issue cannot be solved by adjusting configuration
|
||||
- [ ] understood that the Serena Dashboard can be disabled through the config
|
||||
- [ ] understood that, by default, a client session will start a separate instance of a Serena server.
|
||||
- [ ] understood that, for multi-agent setups, the Streamable HTTP/SSE mode should be used.
|
||||
- [ ] understood that non-project files are ignored using either .gitignore or the corresponding setting in `.serena/project.yml`
|
||||
- [ ] looked for similar issues and discussions, including closed ones
|
||||
- [ ] made sure it's an actual issue, not a question (use GitHub Discussions instead).
|
||||
|
||||
If you have encountered a real and new issue:
|
||||
If you have encountered an actual issue:
|
||||
|
||||
- [ ] I performed `<uv invocation> serena project health-check`
|
||||
- [ ] I indexed the project as described in the readme
|
||||
- [ ] Added sufficient explanation of my setup: the MCP client, the OS, the programming language, any config adjustments or relevant project specifics
|
||||
- [ ] Explained how the issue arose, added instructions on how to reproduce it (if possible)
|
||||
- [ ] If the issue happens on an open source project, I have added the link
|
||||
- [ ] Wrote a meaningful title and description
|
||||
- If using language servers (not the JetBrains plugin),
|
||||
- [ ] I performed `<uv invocation> serena project health-check`
|
||||
- [ ] I indexed the project as described in the documentation
|
||||
- [ ] I added sufficient explanation of my setup: the MCP client, the OS, the programming language(s), any config adjustments or relevant project specifics
|
||||
- [ ] I explained how the issue arose and, where possible, added instructions on how to reproduce it
|
||||
- [ ] If the issue happens on an open-source project, I have added the link
|
||||
- [ ] I provided a meaningful title and description
|
||||
@@ -169,7 +169,7 @@ Some useful options include:
|
||||
* `--language-backend JetBrains`: use the Serena JetBrains Plugin as the language backend (overriding the default backend configured in the central configuration)
|
||||
* `--context <context>`: specify the operation [context](contexts) in which Serena shall operate
|
||||
* `--mode <mode>`: specify one or more [modes](modes) to enable (can be passed several times)
|
||||
* `--enable-web-dashboard <true|false>`: enable or disable the web dashboard (enabled by default)
|
||||
* `--open-web-dashboard <true|false>`: whether to open the web dashboard on startup (enabled by default)
|
||||
|
||||
## Other Commands
|
||||
|
||||
|
||||
@@ -37,13 +37,34 @@ For instance, when using `uvx`, run
|
||||
* You can optionally specify a custom project name with `--name "My Project"`.
|
||||
* You can immediately index the project after creation with `--index`.
|
||||
|
||||
After creation, you can adjust the project settings in the generated `.serena/project.yml` file.
|
||||
(project-config)=
|
||||
#### Project Configuration
|
||||
|
||||
After creation, you can adjust the project settings in the generated `.serena/project.yml` file
|
||||
within the project directory.
|
||||
|
||||
The file allows you to configure ...
|
||||
* the set of programming languages for which language servers are spawned (not relevant when using the JetBrains plugin)
|
||||
Note that you can dynamically add/remove language servers while Serena is running via the [Dashboard](060_dashboard).
|
||||
* the encoding used in source files
|
||||
* ignore rules
|
||||
* write access
|
||||
* an initial prompt that shall be passed to the LLM whenever the project is activated
|
||||
* the name by which you want to refer to the project (relevant when telling the LLM to dynamically activate the project)
|
||||
|
||||
For detailed information on the parameters and possible settings, see the
|
||||
[template file](https://github.com/oraios/serena/blob/main/src/serena/resources/project.template.yml).
|
||||
|
||||
(indexing)=
|
||||
### Indexing
|
||||
|
||||
Especially for larger project, it is advisable to index the project after creation (in order to avoid
|
||||
delays during MCP server startup or the first tool application):
|
||||
:::{note}
|
||||
Indexing is not a relevant operation when using the JetBrains plugin, as indexing is handled by the IDE.
|
||||
:::
|
||||
|
||||
Especially for larger project, it can be advisable to index the project after creation, pre-caching
|
||||
symbol information provided by the language server(s). This will avoid delays during the first tool invocation
|
||||
that requires symbol information.
|
||||
|
||||
While in the project directory, run this command:
|
||||
|
||||
|
||||
@@ -1,38 +1,58 @@
|
||||
# Configuration
|
||||
|
||||
Serena is very flexible in terms of configuration. While for most users, the default configurations will work,
|
||||
you can fully adjust it to your needs by editing a few yaml files. You can disable tools, change Serena's instructions
|
||||
(what we denote as the `system_prompt`), adjust the output of tools that just provide a prompt, and even adjust tool descriptions.
|
||||
you can fully adjust it to your needs.
|
||||
|
||||
Serena is configured in four places:
|
||||
You can disable tools, change Serena's fundamental instructions
|
||||
(what we denote as the `system_prompt`), adjust the output of tools that just provide a prompt,
|
||||
and even adjust tool descriptions.
|
||||
|
||||
1. The `serena_config.yml` for general settings that apply to all clients and projects.
|
||||
It is located in your user directory under `.serena/serena_config.yml`.
|
||||
The file will be auto-generated when you first run Serena.
|
||||
You can edit it directly or use
|
||||
Serena is configured in using a multi-layered approach:
|
||||
|
||||
```shell
|
||||
<serena> config edit
|
||||
```
|
||||
* **global configuration** (`serena_config.yml`, see below)
|
||||
* **project configuration** (`project.yml`, see [Project Configuration](project-config))
|
||||
* **contexts and modes** for composable configuration, which can be enabled on a case-by-case basis (see below)
|
||||
* **command-line parameters** passed to the `start-mcp-server` server command (overriding/extending configured settings)
|
||||
See [MCP Server Command-Line Arguments](mcp-args) for further information.
|
||||
|
||||
## Global Configuration
|
||||
|
||||
where `<serena>` is [your way of running Serena](020_running).
|
||||
The configuration file can also be accessed through [Serena's dashboard](060_dashboard).
|
||||
2. In the arguments passed to the `start-mcp-server` in your client's config (see below),
|
||||
which will apply to all sessions started by the respective client. In particular, the [context](contexts) parameter
|
||||
should be set appropriately for Serena to be best adjusted to existing tools and capabilities of your client.
|
||||
See for a detailed explanation. You can override all entries from the `serena_config.yml` through command line arguments.
|
||||
3. In the `.serena/project.yml` file within your project. This will hold project-level configuration that is used whenever
|
||||
that project is activated. This file will be autogenerated when you first use Serena on that project, but you can also
|
||||
create it explicitly with `serena project create [options]` (see the [](project-creation-indexing)
|
||||
for details on available options).
|
||||
4. Through the context and modes (see below).
|
||||
The global configuration file allows you to change general settings and defaults that will apply to all projects unless overridden.
|
||||
|
||||
After the initial setup, continue with one of the sections below, depending on how you
|
||||
want to use Serena.
|
||||
### Settings
|
||||
|
||||
Some of the configurable settings include:
|
||||
* the language backend to use by default (i.e., the JetBrains plugin or language servers)
|
||||
* UI settings affecting the [Serena Dashboard and GUI tool](060_dashboard.md)
|
||||
* the set of tools to enable/disable by default
|
||||
* tool execution parameters (timeout, max. answer length)
|
||||
* global ignore rules
|
||||
* logging settings
|
||||
* advanced settings specific to individual language servers (see [below](ls-specific-settings))
|
||||
|
||||
For detailed information on the parameters and possible settings, see the
|
||||
[template file](https://github.com/oraios/serena/blob/main/src/serena/resources/serena_config.template.yml).
|
||||
|
||||
### Accessing the Configuration File
|
||||
|
||||
The configuration file is auto-created when you first run Serena. It is stored in your user directory:
|
||||
* Linux/macOS/Git-Bash: `~/.serena/serena_config.yml`
|
||||
* Windows (CMD/PowerShell): `%USERPROFILE%\.serena\serena_config.yml`
|
||||
|
||||
You can access it
|
||||
* through [Serena's dashboard](060_dashboard) while Serena is running (use the respective button)
|
||||
* directly, using your favourite text editor
|
||||
* using the command
|
||||
|
||||
```shell
|
||||
<serena> config edit
|
||||
```
|
||||
|
||||
where `<serena>` is [your way of running Serena](020_running).
|
||||
|
||||
## Modes and Contexts
|
||||
|
||||
Serena's behavior and toolset can be adjusted using contexts and modes.
|
||||
Serena's behaviour and toolset can be adjusted using contexts and modes.
|
||||
These allow for a high degree of customization to best suit your workflow and the environment Serena is operating in.
|
||||
|
||||
(contexts)=
|
||||
@@ -134,7 +154,8 @@ For advanced users, Serena's configuration can be further customized.
|
||||
The Serena user data directory (where configuration, language server files, logs, etc. are stored) defaults to `~/.serena`.
|
||||
You can change this location by setting the `SERENA_HOME` environment variable to your desired path.
|
||||
|
||||
### Language Server-Specific settings (`ls_specific_settings`)
|
||||
(ls-specific-settings)=
|
||||
### Language Server-Specific Settings
|
||||
|
||||
Under the key `ls_specific_settings` in `serena_config.yml`, you can you pass per-language,
|
||||
language server-specific configuration.
|
||||
|
||||
@@ -0,0 +1,14 @@
|
||||
"""
|
||||
Prints the list of supported languages, for use in the project.yml template
|
||||
"""
|
||||
|
||||
from solidlsp.ls_config import Language
|
||||
|
||||
if __name__ == "__main__":
|
||||
lang_strings = sorted([l.value for l in Language])
|
||||
max_len = max(len(s) for s in lang_strings)
|
||||
fmt = f"%-{max_len+2}s"
|
||||
for i, l in enumerate(lang_strings):
|
||||
if i % 5 == 0:
|
||||
print("\n# ", end="")
|
||||
print(" " + fmt % l, end="")
|
||||
@@ -1,15 +1,20 @@
|
||||
# list of languages for which language servers are started; choose from:
|
||||
# al bash clojure cpp csharp csharp_omnisharp
|
||||
# dart elixir elm erlang fortran fsharp
|
||||
# go groovy haskell java julia kotlin
|
||||
# lua markdown nix pascal perl php
|
||||
# powershell python python_jedi r rego ruby
|
||||
# ruby_solargraph rust scala swift terraform toml
|
||||
# typescript typescript_vts yaml zig
|
||||
# al bash clojure cpp csharp
|
||||
# csharp_omnisharp dart elixir elm erlang
|
||||
# fortran fsharp go groovy haskell
|
||||
# java julia kotlin lua markdown
|
||||
# matlab nix pascal perl php
|
||||
# powershell python python_jedi r rego
|
||||
# ruby ruby_solargraph rust scala swift
|
||||
# terraform toml typescript typescript_vts vue
|
||||
# yaml zig
|
||||
# (This list may be outdated. For the current list, see values of Language enum here:
|
||||
# https://github.com/oraios/serena/blob/main/src/solidlsp/ls_config.py
|
||||
# For some languages, there are alternative language servers, e.g. csharp_omnisharp, ruby_solargraph.)
|
||||
# Note:
|
||||
# - For C, use cpp
|
||||
# - For JavaScript, use typescript
|
||||
# - For Free Pascal / Lazarus, use pascal
|
||||
# - For Free Pascal/Lazarus, use pascal
|
||||
# Special requirements:
|
||||
# - csharp: Requires the presence of a .sln file in the project folder.
|
||||
# - pascal: Requires Free Pascal Compiler (fpc) and optionally Lazarus.
|
||||
@@ -22,14 +27,11 @@ languages: ["python"]
|
||||
# For a list of possible encodings, see https://docs.python.org/3.11/library/codecs.html#standard-encodings
|
||||
encoding: "utf-8"
|
||||
|
||||
# whether to use the project's gitignore file to ignore files
|
||||
# Added on 2025-04-07
|
||||
# whether to use project's .gitignore files to ignore files
|
||||
ignore_all_files_in_gitignore: true
|
||||
|
||||
# list of additional paths to ignore
|
||||
# list of additional paths to ignore in all projects
|
||||
# same syntax as gitignore, so you can use * and **
|
||||
# Was previously called `ignored_dirs`, please update your config if you are using that.
|
||||
# Added (renamed) on 2025-04-07
|
||||
ignored_paths: []
|
||||
|
||||
# whether the project is in read-only mode
|
||||
|
||||
Reference in new issue
Block a user