mirror of
https://github.com/tiennm99/serena.git
synced 2026-10-14 04:16:34 +00:00
Merge branch 'main' into feature/cross-package-typescript-references
# Conflicts: # CHANGELOG.md # src/solidlsp/ls.py
This commit is contained in:
Michael Panchenko committed
commit
64e604630e
216 files changed
+7868
-1189
No files matched your search
@@ -101,8 +101,32 @@ You can do this in Tools / GitHub Copilot / Chat, where at the bottom you can cl
|
||||
|
||||
## Claude Code
|
||||
|
||||
Serena is a great way to make Claude Code both cheaper and more powerful!
|
||||
To add Serena to Claude Code, you can simply run `serena setup claude-code`. Alternatively, follow the instructions below.
|
||||
Serena is a great way to make Claude Code both more efficient and more powerful!
|
||||
To set up the Serena MCP server for Claude Code, you can simply run this command:
|
||||
|
||||
serena setup claude-code
|
||||
|
||||
Find manual setup instructions as well as workarounds for Claude Code's recent regressions pertaining to (external) tool use below.
|
||||
|
||||
:::{attention}
|
||||
Recent updates to Claude Code (CC) and to the Opus line of models resulted in drastically reduced
|
||||
adherence to instructions pertaining to Serena's tools.
|
||||
|
||||
After extensive analysis, we identified part of the reason to be very long and detailed
|
||||
tool descriptions for built-in tools and parts of the default system prompt.
|
||||
The descriptions of CC's system tools take almost 16k tokens, cannot be adjusted by the user,
|
||||
and introduce a very strong bias towards internal tools, making it almost impossible to convince Opus 4.7 to use Serena.
|
||||
|
||||
As a workaround, we crafted a system prompt that counteracts this bias.
|
||||
When using Serena, we highly recommend that you start CC as
|
||||
|
||||
```shell
|
||||
claude --system-prompt="$(serena prompts print-cc-system-prompt-override)"
|
||||
```
|
||||
|
||||
You can also consider adding the content of `serena cc-system-prompt-override` to your `CLAUDE.md` files,
|
||||
but the effect be insufficient for counteracting Claude Code's bias towards internal tools.
|
||||
:::
|
||||
|
||||
**Global Configuration**. To add the Serena MCP server for all your projects, use the user-level configuration of claude code and the `--project-from-cwd` flag:
|
||||
|
||||
@@ -194,9 +218,9 @@ The hooks will:
|
||||
`grep` or `read_file` calls without using any Serena tools in between.
|
||||
- **`activate`**: Prompt the agent to activate the project and read Serena's instructions at session start.
|
||||
- **`cleanup`**: Clean up hook session data when the session ends.
|
||||
- **`auto-approve`**: Auto-approve Serena tool calls whenever Claude Code is in `acceptEdits` mode,
|
||||
so blanket edit approvals cover Serena's destructive tools (e.g. `replace_symbol_body`,
|
||||
`rename_symbol`) instead of prompting on every call.
|
||||
- **`auto-approve`**: Auto-approve Serena tool calls whenever Claude Code is in a permissive
|
||||
permission mode (`acceptEdits` or `auto`), so blanket approvals cover Serena's destructive
|
||||
tools (e.g. `replace_symbol_body`, `rename_symbol`) instead of prompting on every call.
|
||||
|
||||
For more details on Claude Code's hook system, see the
|
||||
[Claude Code hooks documentation](https://code.claude.com/docs/en/hooks).
|
||||
|
||||
@@ -18,20 +18,22 @@ setting up a project with Serena typically involves the following steps:
|
||||
Project creation is the process of defining fundamental project settings that are relevant to Serena's operation.
|
||||
|
||||
You can create a project either
|
||||
* explicitly, using the project creation command (see below), or
|
||||
* implicitly, by just activating a directory as a project while already in a conversation; this will use default settings for your project (skip to the next section).
|
||||
* explicitly, using the project creation command, or
|
||||
|
||||
### Explicit Project Creation
|
||||
|
||||
To explicitly create a project, use the following command while in the project directory:
|
||||
|
||||
serena project create [options]
|
||||
serena project create [options] [project directory]
|
||||
|
||||
* For an empty project, you will need to specify the programming language
|
||||
(e.g., `--language python`).
|
||||
* For an existing project, the main programming language will be detected automatically,
|
||||
but you can choose to explicitly specify multiple languages by passing the `--language` parameter
|
||||
multiple times (e.g. `--language python --language typescript`).
|
||||
* The project directory defaults to the current directory if not specified.
|
||||
* For an existing project, the programming languages will be detected based on
|
||||
the source files present, and the main language will be activated automatically.
|
||||
If multiple languages are detected, you will be prompted whether you want to enable them.
|
||||
* For an empty project, you can optionally specify one or more languages
|
||||
to be activated explicitly via the `--language` parameter
|
||||
(e.g. `--language python --language typescript`).
|
||||
* You can optionally specify a custom project name with `--name my-name`.
|
||||
* You can immediately index the project after creation with `--index`.
|
||||
|
||||
@@ -42,6 +44,7 @@ After creation, you can adjust the project settings in the generated `.serena/pr
|
||||
within the project directory.
|
||||
|
||||
The file allows you to configure ...
|
||||
* the name by which you want to refer to the project (relevant when telling the LLM to dynamically activate the project)
|
||||
* 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 [language backend](per-project-language-backend) to use for this project (overriding the global setting)
|
||||
@@ -50,8 +53,8 @@ The file allows you to configure ...
|
||||
* write access
|
||||
* [additional workspace folders](additional-workspace-folders) for cross-package reference support in monorepos
|
||||
* 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)
|
||||
* the set of tools and modes to use by default
|
||||
* the set of tools and modes to use for the project
|
||||
* and some other settings.
|
||||
|
||||
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).
|
||||
|
||||
@@ -118,32 +118,26 @@ Examples of built-in modes include:
|
||||
|
||||
Find the concrete definitions of these modes [here](https://github.com/oraios/serena/tree/main/src/serena/resources/config/modes).
|
||||
|
||||
Active modes are configured in (from lowest to highest precedence):
|
||||
The modes to be activated are configured in:
|
||||
* the global configuration file (`serena_config.yml`)
|
||||
- defines `base_modes`, which are always included
|
||||
- defines `default_modes`, which can be overridden by projects or command line parameters
|
||||
* the project configuration file (`project.yml`)
|
||||
- defines `default_modes` (overriding the default modes in the global configuration)
|
||||
- defines `added_modes`, which are added on top
|
||||
* at startup via command-line parameters
|
||||
- can override default modes with `--mode`
|
||||
- can define modes to be added on top with `--add-mode`
|
||||
|
||||
The two former sources define both **base modes** and **default modes**.
|
||||
Ultimately, the active modes are the union of base modes and default modes (after applying all overrides).
|
||||
Command-line parameters override default modes but not base modes.
|
||||
Base modes should thus be used to define modes that you always want to be active, regardless of command-line parameters.
|
||||
Ultimately, the active modes are given by the union of
|
||||
* `base_modes` defined in the global configuration (always active)
|
||||
* `default_modes` (defined in the global configuration, optionally overridden by the project/CLI)
|
||||
* `added_modes` (defined in the project configuration/via CLI parameters)
|
||||
|
||||
Command-line parameters for overriding default modes:
|
||||
When launching the MCP sever, specify modes using `--mode <mode-name>`; multiple modes can be specified, e.g. `--mode planning --mode no-onboarding`.
|
||||
|
||||
:::{important}
|
||||
By default, Serena activates the two modes `interactive` and `editing` (as defined in the global configuration).
|
||||
|
||||
As soon as you start to specify modes via the command line, only the modes you explicitly specify will be active, however.
|
||||
Therefore, if you want to keep the default modes, you must specify them as well.
|
||||
For example, to add mode `no-memories` to the default behaviour, specify
|
||||
```shell
|
||||
--mode interactive --mode editing --mode no-memories
|
||||
```
|
||||
|
||||
If you want to keep certain modes as always active, regardless of command-line parameters,
|
||||
define them as *base modes* in the global or project configuration.
|
||||
:::
|
||||
So you should
|
||||
* define modes you definitely always want to use in `base_modes`,
|
||||
* define modes that you typically want to use but sometimes want to override in `default_modes`,
|
||||
* use `added_modes` to add modes that you need only for specific projects/sessions.
|
||||
|
||||
:::{note}
|
||||
**Mode Compatibility**: While you can combine modes, some may be semantically incompatible (e.g., `interactive` and `one-shot`).
|
||||
@@ -504,28 +498,72 @@ ls_specific_settings:
|
||||
|
||||
#### Java (`eclipse.jdt.ls`)
|
||||
|
||||
Java support has two installation modes:
|
||||
|
||||
1. **Default vscode-java VSIX mode** (no extra config required): Serena downloads the platform-specific
|
||||
vscode-java VSIX (~500 MB: JDTLS + bundled JRE 21 + Lombok + IntelliCode), Gradle distribution and
|
||||
IntelliCode VSIX from public hosts on first use.
|
||||
2. **Upstream JDTLS mode** (offline-friendly): Activated by setting both `jdtls_path` and `lombok_path`.
|
||||
Uses an existing JDTLS installation (~100 MB) and the system JDK 21+. Nothing is downloaded.
|
||||
Recommended for restricted-network/corporate environments.
|
||||
|
||||
**When to use which mode:**
|
||||
|
||||
- **Default vscode-java VSIX mode** — recommended for most users. No setup required;
|
||||
Serena downloads everything on first use.
|
||||
- **Upstream JDTLS mode** — recommended when:
|
||||
- you cannot reach `github.com`, `services.gradle.org` or `marketplace.visualstudio.com`
|
||||
from the host (corporate proxy, air-gapped network);
|
||||
- you want a smaller on-disk footprint (~100 MB vs ~500 MB);
|
||||
- you already maintain a JDTLS installation (e.g. for `nvim-jdtls` or another editor);
|
||||
- your security policy prohibits per-project runtime downloads.
|
||||
|
||||
**JDK 21+ is required** in upstream mode. Serena resolves the JDK in this order:
|
||||
`ls_specific_settings.java.java_home` → `JAVA_HOME` env var → first `java` on `PATH`.
|
||||
The resolved JVM is interrogated and rejected if its `java.specification.version` is below 21.
|
||||
|
||||
The following settings are supported for the Java language server:
|
||||
|
||||
| Setting | Default | Description |
|
||||
|---|---|---|
|
||||
| `jdtls_path` | `null` | Activates upstream JDTLS mode. Path to upstream JDTLS root (containing `plugins/` and `config_<platform>/`). Get via `brew install jdtls` or extract `jdt-language-server-*.tar.gz` from <https://download.eclipse.org/jdtls/snapshots/>. Must be set together with `lombok_path`. |
|
||||
| `lombok_path` | `null` | Path to the Lombok jar. Activates upstream JDTLS mode together with `jdtls_path`. Get from `~/.m2/repository/org/projectlombok/lombok/<ver>/lombok-<ver>.jar` or download from <https://projectlombok.org/downloads/>. |
|
||||
| `java_home` | `null` | (upstream-jdtls mode only) Path to JDK 21+ home directory used to launch JDTLS. Falls back to `JAVA_HOME` env var, then `which java`. |
|
||||
| `maven_user_settings` | `~/.m2/settings.xml` | Path to Maven `settings.xml` |
|
||||
| `gradle_user_home` | `~/.gradle` | Path to Gradle user home directory |
|
||||
| `gradle_wrapper_enabled` | `false` | Use the project's Gradle wrapper (`gradlew`) instead of the bundled Gradle distribution. Enable this for projects with custom plugins or repositories. |
|
||||
| `gradle_java_home` | `null` | Path to the JDK used by Gradle. When unset, Gradle uses the bundled JRE. |
|
||||
| `use_system_java_home` | `false` | Use the system's `JAVA_HOME` environment variable for JDTLS itself. Enable this if your project requires a specific JDK vendor or version for Gradle's JDK checks. |
|
||||
| `gradle_version` | `8.14.2` | Override the Gradle distribution version Serena downloads by default. |
|
||||
| `vscode_java_version` | `1.42.0-561` | Override the bundled `vscode-java` runtime bundle version Serena downloads by default. |
|
||||
| `intellicode_version` | `1.2.30` | Override the IntelliCode VSIX version Serena downloads by default. |
|
||||
| `gradle_version` | `8.14.2` | (vscode-java mode only) Override the Gradle distribution version Serena downloads by default. |
|
||||
| `vscode_java_version` | `1.42.0-561` | (vscode-java mode only) Override the bundled `vscode-java` runtime bundle version Serena downloads by default. |
|
||||
| `intellicode_version` | `1.2.30` | (vscode-java mode only) Override the IntelliCode VSIX version Serena downloads by default. |
|
||||
| `jdtls_xmx` | `3G` | Maximum heap size for the JDTLS server JVM. |
|
||||
| `jdtls_xms` | `100m` | Initial heap size for the JDTLS server JVM. |
|
||||
| `intellicode_xmx` | `1G` | Maximum heap size for the IntelliCode embedded JVM. |
|
||||
| `intellicode_xms` | `100m` | Initial heap size for the IntelliCode embedded JVM. |
|
||||
| `intellicode_xmx` | `1G` | (vscode-java mode only) Maximum heap size for the IntelliCode embedded JVM. |
|
||||
| `intellicode_xms` | `100m` | (vscode-java mode only) Initial heap size for the IntelliCode embedded JVM. |
|
||||
|
||||
Note:
|
||||
Notes:
|
||||
- When overriding `vscode_java_version`, Serena still assumes that the downloaded runtime bundle keeps the same internal
|
||||
directory layout and file names as the bundled default version.
|
||||
- In upstream-jdtls mode, IntelliCode is not loaded (it's an ML completions ranker that is irrelevant to Serena's
|
||||
symbol-tools workflow), and Serena does not ship a Gradle distribution. Maven projects work via JDTLS's bundled m2e.
|
||||
Gradle projects must have `./gradlew` in the project, or rely on a system-installed Gradle through Buildship's
|
||||
default discovery rules.
|
||||
- In upstream-jdtls mode the `gradle_version`, `vscode_java_version`, `intellicode_version`,
|
||||
`intellicode_xmx`, `intellicode_xms` settings are silently ignored — they only apply to the
|
||||
vscode-java VSIX mode.
|
||||
|
||||
Example for a project with custom Gradle plugins and JDK requirements:
|
||||
Example: upstream-jdtls mode (offline / corporate network):
|
||||
|
||||
```yaml
|
||||
ls_specific_settings:
|
||||
java:
|
||||
jdtls_path: "/opt/homebrew/Cellar/jdtls/1.50.0/libexec"
|
||||
lombok_path: "/Users/me/.m2/repository/org/projectlombok/lombok/1.18.36/lombok-1.18.36.jar"
|
||||
# java_home: "/opt/homebrew/opt/openjdk@21" # optional
|
||||
```
|
||||
|
||||
Example: default vscode-java VSIX mode for a project with custom Gradle plugins:
|
||||
|
||||
```yaml
|
||||
ls_specific_settings:
|
||||
|
||||
Reference in new issue
Block a user