Skip to content

Monster branch rebased #1223

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
MischaPanch wants to merge 16 commits into
base: main
Choose a base branch
from
Open

Monster branch rebased #1223

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
16 commits
Select commit Hold shift + click to select a range
621fe02
Conftest: added get_pytest_markers
MischaPanch Mar 25, 2026
5ae7314
Feature: move symbol WIP
MischaPanch Mar 5, 2026
6a281d5
Added safe_delete and inline_symbol tools (JB backend)
MischaPanch Mar 22, 2026
bc5a6e1
Added SafeDeleteSymbol in LS world
MischaPanch Mar 24, 2026
dc812ea
Gitignore
MischaPanch Mar 25, 2026
86ea36f
Add TY support for python, mark LS that support implementation request
MischaPanch Mar 25, 2026
fcce94b
LS: mark LS that support implementation request
MischaPanch Mar 25, 2026
6b556f9
Exclude test resources from formating
MischaPanch Mar 25, 2026
f44f38f
Diagnostics, find defining and implementing symbol tools, WIP
MischaPanch Mar 25, 2026
a3d804d
Security enhancement: pinned all runtime deps, verify checksums
MischaPanch Mar 25, 2026
69f70e8
Restructured serena_agent tests, reifying the cases
MischaPanch Mar 25, 2026
a9bb52a
JB inspection and implementation tools, WIP
MischaPanch Mar 24, 2026
e9a090d
Fixes in CORE PATH LOGIC: get_relative_path
MischaPanch Mar 26, 2026
62c09c2
Fixes in CORE PATH LOGIC: propagate changes from past commit
MischaPanch Mar 26, 2026
e24952c
Fix in test_serena_agent.py: use normalize_relative_path - fixup this…
MischaPanch Mar 26, 2026
cb3b20a
Added dedicated doc on features, WIP
MischaPanch Mar 26, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions .gitignore
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -223,6 +223,9 @@ tmp/
# Exception: Don't ignore Elixir test repository lib directory (contains source code)
!/test/resources/repos/elixir/test_repo/lib

#Cpp
/test/resources/repos/cpp/test_repo/.ccls-cache

# Exception: Don't ignore Nix test repository lib directory (contains source code)
!/test/resources/repos/nix/test_repo/lib

Expand Down
14 changes: 14 additions & 0 deletions .serena/project.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -150,3 +150,17 @@ read_only_memory_patterns: []
# line ending convention for file writes: unset (use global setting, "lf", "crlf", or "native" (platform default)
# If not undefined, overrides the global setting in serena_config.yml
line_ending:

# list of regex patterns for memories to completely ignore.
# Matching memories will not appear in list_memories or activate_project output
# and cannot be accessed via read_memory or write_memory.
# To access ignored memory files, use the read_file tool on the raw file path.
# Extends the list from the global configuration, merging the two lists.
# Example: ["_archive/.*", "_episodes/.*"]
ignored_memory_patterns: []

# advanced configuration option allowing to configure language server-specific options.
# Maps the language key to the options.
# Have a look at the docstring of the constructors of the LS implementations within solidlsp (e.g., for C# or PHP) to see which options are available.
# No documentation on options means no options are available.
ls_specific_settings: {}
165 changes: 165 additions & 0 deletions docs/02-usage/001_features.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,165 @@
# Features

Serena is essentially an **IDE for coding agents** -- it gives LLMs the same kind of structural code understanding
that human developers get from their IDEs, but through interfaces purpose-built for agents.
Serena supports both the **Language Server (LS)** backend (free, open-source) and the **JetBrains (JB)** plugin backend.
The LS backend is the broadly available baseline.
The JetBrains backend is the premium option, offering a deeper IDE-native workflow and significantly broader functionality.

## General

Serena is designed around a few core principles:

- **Agent-first tool design** -- Serena's tools operate on **symbols and name paths** rather than on lines and columns.
This is a deliberate design choice: line numbers and column offsets are fragile and shift with every edit,
making them unreliable anchors for agents working on evolving code.
Symbols (classes, methods, functions) are stable, meaningful identifiers that agents can reason about naturally.
Tool results are compact JSON, keeping token usage low and output qujuality high.
Copy link
Copy Markdown

@coderabbitai coderabbitai bot Mar 26, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

Fix typo: "qujuality" should be "quality".

There's a spelling error in the word "quality" that should be corrected for professional documentation.

📝 Proposed fix 
-  Tool results are compact JSON, keeping token usage low and output qujuality high.
+  Tool results are compact JSON, keeping token usage low and output quality high.
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
Tool results are compact JSON, keeping token usage low and output qujuality high.
Tool results are compact JSON, keeping token usage low and output quality high.
🧰 Tools
🪛 LanguageTool

[grammar] ~17-~17: Ensure spelling is correct
Context: ...SON, keeping token usage low and output qujuality high. - **LLM- and framework-independen...

(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)

🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In `@docs/02-usage/001_features.md` at line 17, The sentence "Tool results are
compact JSON, keeping token usage low and output qujuality high." contains a
typo: replace "qujuality" with "quality" so it reads "Tool results are compact
JSON, keeping token usage low and output quality high." Edit the line in
001_features.md where that sentence appears (look for the exact string "output
qujuality high") and save the change.

- **LLM- and framework-independent** -- Serena is not tied to any specific LLM, agent framework, or interface. It works with any MCP-compatible client
and can be integrated into custom agent pipelines.
- **Lightweight** -- Serena runs as a standalone MCP server. Language servers are downloaded automatically on demand. With the JetBrains backend, no additional downloads or processes are required.
- **Project-based configuration** -- Each project can have its own configuration, language servers, and memory store. Modes and contexts allow
tailoring the active tool set to the workflow at hand.
- **Memories** -- A simple but effective Markdown-based memory system allows agents to persist and retrieve project knowledge across sessions,
including automatic onboarding for new projects.

## Navigation

Serena's navigation tools allow agents to explore codebases at the symbol level, understanding structure and relationships
without reading entire files.

| Capability | Language Server | JetBrains Plugin |
|-------------------------------------|--------------------------------------|-----------------------|
| **Symbol overview** (file outline) | yes | yes |
| **Find symbol** (by name path) | yes | yes |
| **Find referencing symbols** | yes | yes |
| **Find implementations** | yes (limited language support) | yes (all languages) |
| **Go to definition** | yes | yes |
| **Type hierarchy** (super/subtypes) | -- | yes |
| **Search in dependencies** | -- | yes |

The JetBrains backend supports **find implementations** across all languages, whereas the LS backend is limited to
languages whose language server supports it (e.g., not Python). The **type hierarchy** and **dependency search** are
JetBrains-exclusive features.

<!-- TODO: Add navigation demo video here
<video src=""
controls
preload="metadata"
style="max-width: 100%; height: auto;">
Your browser does not support the video tag.
</video>
-->

## Refactoring

Serena supports safe, codebase-wide refactoring operations.

| Capability | Language Server | JetBrains Plugin |
|---------------------------------------------|-----------------|------------------|
| **Rename symbol** | yes | yes |
| **Safe delete** | yes | yes |
| **Propagate deletions, remove unused code** | -- | yes |
| **Move** (symbol, file, directory) | -- | yes |
| **Inline method** | -- | yes |

**Rename** updates all references across the codebase automatically.
The JetBrains backend adds **move** (relocate symbols, files, or directories with automatic reference updates),
**inline method** (replace a method with its body at all call sites), and **safe delete** (delete a symbol only
after verifying it is unused, or propagate the deletion to remove all usages).

<!-- TODO: Add refactoring demo video here
<video src=""
controls
preload="metadata"
style="max-width: 100%; height: auto;">
Your browser does not support the video tag.
</video>
-->

## Diagnostics

Diagnostics expose compiler errors, warnings, and hints to the agent, enabling it to identify and fix issues
without running external build commands.

| Capability | Language Server | JetBrains Plugin |
|---------------------------------------|-----------------|------------------|
| **File diagnostics** (by line range) | yes | yes |
| **Symbol diagnostics** (+ references) | yes | yes |
| **Automatic post-edit diagnostics** | yes | yes |
| **Quick fixes** | -- | yes |

Both backends surface compiler errors, warnings, and hints. Serena's editing tools automatically report new diagnostics
after every edit, giving the agent immediate feedback on whether its changes introduced errors.

The JetBrains backend provides diagnostics customized to the user's IDE inspection profile and can offer
**quick fixes** -- automated, one-click resolutions for common issues.

<!-- TODO: Add diagnostics demo video here
<video src=""
controls
preload="metadata"
style="max-width: 100%; height: auto;">
Your browser does not support the video tag.
</video>
-->

## Debugging

Debugging integration is included **only for the JetBrains backend**.

<!-- TODO: Add debugging demo video here
<video src=""
controls
preload="metadata"
style="max-width: 100%; height: auto;">
Your browser does not support the video tag.
</video>
-->

## Editing

Serena provides both symbol-level and file-level editing tools for precise code modifications.

| Capability | Language Server | JetBrains Plugin |
|-------------------------------|-----------------|--------------------|
| **Replace symbol body** | yes | yes |
| **Insert after symbol** | yes | yes |
| **Insert before symbol** | yes | yes |
| **Auto-format after edit** | -- | yes |

Symbol-level editing is Serena's recommended approach: the agent retrieves a symbol's body, modifies it, and writes
it back using `replace_symbol_body`. This avoids line-number fragility and ensures precise edits.

The JetBrains backend automatically **formats code** after every edit using the project's configured code style,
so the agent doesn't need to worry about indentation or formatting conventions.

<!-- TODO: Add editing demo video here
<video src=""
controls
preload="metadata"
style="max-width: 100%; height: auto;">
Your browser does not support the video tag.
</video>
-->

## Basic Features

Beyond its semantic capabilities, Serena includes a set of basic utilities for completeness.
When Serena is used inside an agentic harness such as Claude Code or Codex, these tools are typically disabled by default,
since the surrounding harness already provides overlapping file, search, and shell capabilities.

- **`search_for_pattern`** -- Flexible regex search across the codebase with glob-based file filtering, context lines,
and the option to restrict to code files only. Useful when you don't know the exact symbol name.
- **`list_dir` / `find_file`** -- Directory listing and file search with glob support. Helps agents orient themselves
in unfamiliar projects.
- **`read_file`** -- Read files or file chunks by line range, for cases where symbolic access isn't applicable
(e.g. configuration files, HTML templates).
- **`execute_shell_command`** -- Run shell commands (builds, tests, linters) directly from the agent,
with configurable working directory and output limits.
- **Memories** (`write_memory`, `read_memory`, `list_memory`, `edit_memory`, `delete_memory`, `rename_memory`) --
Persistent, Markdown-based project knowledge that survives across sessions. Supports hierarchical topics
and global (cross-project) memories.
- **Onboarding** -- Automatic project familiarization on first encounter, storing key information as memories for future use.
- **Thinking tools** -- Structured reflection prompts (`think_about_collected_information`, `think_about_task_adherence`,
`think_about_whether_you_are_done`) that improve agent reasoning quality during complex tasks.
99 changes: 91 additions & 8 deletions docs/02-usage/050_configuration.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -226,11 +226,55 @@ ls_specific_settings:
# language-server-specific keys
```

:::{attention}
Most settings are currently undocumented. Please refer to the
[source code of the respective language server](https://github.com/oraios/serena/tree/main/src/solidlsp/language_servers)
implementation to determine supported settings.
:::
The following table summarizes the currently supported `ls_specific_settings` keys.
Version keys override Serena's bundled default for managed downloads or installs.

| Language key | Supported settings |
|---|---|
| `al` | `al_extension_version` |
| `ansible` | `ls_path`, `ansible_language_server_version`, `npm_registry`, `ansible_path`, `ansible_settings`, `lint_enabled`, `lint_path`, `python_interpreter_path`, `python_activation_script` |
| `bash` | `ls_path`, `bash_language_server_version`, `npm_registry` |
| `clojure` | `ls_path`, `clojure_lsp_version` |
| `cpp` | `ls_path`, `compile_commands_dir`, `clangd_version` |
| `cpp_ccls` | `ls_path` |
| `csharp` | `csharp_language_server_version`, `runtime_dependencies` |
| `csharp_omnisharp` | `omnisharp_version`, `razor_omnisharp_version` |
| `dart` | `dart_sdk_version` |
| `elixir` | `expert_version` |
| `elm` | `elm_language_server_version`, `npm_registry` |
| `fsharp` | `fsautocomplete_version` |
| `go` | `gopls_settings` |
| `groovy` | `ls_jar_path`, `ls_java_home_path`, `ls_jar_options`, `vscode_java_version` |
| `hlsl` | `ls_path`, `version` |
| `java` | `maven_user_settings`, `gradle_user_home`, `gradle_wrapper_enabled`, `gradle_java_home`, `use_system_java_home`, `gradle_version`, `vscode_java_version`, `intellicode_version` |
| `kotlin` | `ls_path`, `kotlin_lsp_version`, `jvm_options` |
| `lean4` | `ls_path` |
| `lua` | `lua_language_server_version` |
| `luau` | `ls_path`, `luau_lsp_version`, `platform`, `roblox_security_level` |
| `markdown` | `ls_path`, `marksman_version` |
| `matlab` | `matlab_path`, `matlab_extension_version` |
| `pascal` | `pasls_version`, `pp`, `fpcdir`, `lazarusdir`, `fpc_target`, `fpc_target_cpu` |
| `php` | `ls_path`, `intelephense_version`, `npm_registry`, `ignore_vendor`, `maxFileSize`, `maxMemory` |
| `php_phpactor` | `ls_path`, `phpactor_version`, `ignore_vendor` |
| `powershell` | `pses_version` |
| `python` | `ls_path` |
| `python_ty` | `ls_path`, `ty_version` |
| `ruby` | `ruby_lsp_version` |
| `rust` | `ls_path` |
| `scala` | `metals_version`, `client_name`, `on_stale_lock`, `log_multi_instance_notice` |
| `solidity` | `ls_path`, `solidity_language_server_version`, `npm_registry` |
| `systemverilog` | `ls_path`, `verible_version` |
| `terraform` | `terraform_ls_version` |
| `toml` | `ls_path`, `taplo_version` |
| `typescript` | `ls_path`, `typescript_version`, `typescript_language_server_version`, `npm_registry` |
| `vts` | `vtsls_version`, `npm_registry` |
| `vue` | `vue_language_server_version`, `typescript_version`, `typescript_language_server_version`, `npm_registry` |
| `yaml` | `ls_path`, `yaml_language_server_version`, `npm_registry` |

Notes:
- `ls_path` means Serena uses your explicitly provided executable instead of the managed installation.
- Version overrides apply only to Serena-managed installs or downloads for that language server.
- If a language is not listed above, Serena currently does not document any `ls_specific_settings` for it.

(override-ls-path)=
#### Overriding the Language Server Path
Expand All @@ -246,9 +290,10 @@ ls_specific_settings:
ls_path: "/path/to/language-server"
```

This is supported by all language servers deriving their dependency provider from `LanguageServerDependencyProviderSinglePath`.
Currently, this includes the following languages: `bash`, `clojure`, `cpp`, `kotlin`, `markdown`, `php`, `php_phpactor`, `python`, `rust`, `toml`, `typescript`, `yaml`.
We will add support for more languages over time.
This is supported by all language servers deriving their dependency provider from `LanguageServerDependencyProviderSinglePath`,
and by some additional wrappers that explicitly expose `ls_path`.
Common examples include: `ansible`, `bash`, `clojure`, `cpp`, `cpp_ccls`, `hlsl`, `kotlin`, `lean4`, `luau`, `markdown`, `php`,
`php_phpactor`, `python`, `python_ty`, `rust`, `solidity`, `systemverilog`, `toml`, `typescript`, and `yaml`.

#### C# (Roslyn Language Server)

Expand All @@ -266,12 +311,14 @@ Automatic download is supported for: Windows (x64, ARM64), macOS (x64, ARM64), L
**Configuration:**

The `runtime_dependencies` setting allows you to override the download URLs for the Roslyn Language Server. This is useful if you need to use a private package mirror or a specific version.
For the common case of changing only the package version, use `csharp_language_server_version`.

Example configuration to override the language server download URL:

```yaml
ls_specific_settings:
csharp:
csharp_language_server_version: "5.5.0-2.26078.4"
runtime_dependencies:
- id: "CSharpLanguageServer"
platform_id: "linux-x64" # or win-x64, win-arm64, osx-x64, osx-arm64, linux-arm64
Expand Down Expand Up @@ -318,6 +365,33 @@ Notes:
- `GOFLAGS` (from the environment you start Serena in) may also affect the Go build context. Prefer `buildFlags` for tags.
- Build context changes are only picked up when `gopls` starts. After changing `gopls_settings` (or relevant env vars like `GOFLAGS`), restart the Serena process (or server) that hosts the Go language server, or use your client's "Restart language server" action if it causes `gopls` to restart.

#### Groovy

Serena uses a user-provided Groovy Language Server JAR for Groovy support. If `ls_java_home_path` is not set, Serena downloads
a bundled Java runtime for launching that JAR.

Supported settings:

| Setting | Default | Description |
|---|---|---|
| `ls_jar_path` | required | Path to the Groovy Language Server JAR |
| `ls_java_home_path` | `null` | Path to a Java installation to use instead of Serena's managed runtime |
| `ls_jar_options` | `""` | Additional options passed when launching the Groovy LS JAR |
| `vscode_java_version` | `1.42.0-561` | Override the bundled Java runtime bundle version Serena downloads by default |

Note:
- 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.

Example:

```yaml
ls_specific_settings:
groovy:
ls_jar_path: "/path/to/groovy-language-server-all.jar"
vscode_java_version: "1.42.0-561"
```

#### Java (`eclipse.jdt.ls`)

The following settings are supported for the Java language server:
Expand All @@ -329,6 +403,13 @@ The following settings are supported for the Java language server:
| `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. |

Note:
- 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.

Example for a project with custom Gradle plugins and JDK requirements:

Expand Down Expand Up @@ -373,6 +454,7 @@ Serena uses [`luau-lsp`](https://github.com/JohnnyMorganz/luau-lsp) for Luau sup
ls_specific_settings:
luau:
ls_path: "/path/to/luau-lsp" # Optional: override the language server executable
luau_lsp_version: "1.63.0" # Optional: override the bundled luau-lsp version
platform: "roblox" # "roblox" (default) or "standard"
roblox_security_level: "PluginSecurity" # Roblox only: None, PluginSecurity, LocalUserSecurity, RobloxScriptSecurity
```
Expand Down Expand Up @@ -405,6 +487,7 @@ Configure pasls via `ls_specific_settings.pascal` in `serena_config.yml`:

| Setting | Description |
| ---------------- | --------------------------------------------------------------------------- |
| `pasls_version` | Override the pinned pasls version Serena downloads by default |
| `pp` | Path to FPC compiler driver (must be `fpc` or `fpc.exe`, not `ppc386.exe`) |
| `fpcdir` | Path to FPC source directory |
| `lazarusdir` | Path to Lazarus directory (required for LCL projects) |
Expand Down
Loading
Loading