Skip to content

Commit 9f98221

Browse files
MischaPanchMischaPanch
committed
Added dedicated doc on features, WIP
1 parent f9a6800 commit 9f98221

File tree

1 file changed

+165
-0
lines changed

1 file changed

+165
-0
lines changed

‎docs/02-usage/001_features.md‎

Lines changed: 165 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,165 @@
1+
# Features
2+
3+
Serena is essentially an **IDE for coding agents** -- it gives LLMs the same kind of structural code understanding
4+
that human developers get from their IDEs, but through interfaces purpose-built for agents.
5+
Serena supports both the **Language Server (LS)** backend (free, open-source) and the **JetBrains (JB)** plugin backend.
6+
The LS backend is the broadly available baseline.
7+
The JetBrains backend is the premium option, offering a deeper IDE-native workflow and significantly broader functionality.
8+
9+
## General
10+
11+
Serena is designed around a few core principles:
12+
13+
- **Agent-first tool design** -- Serena's tools operate on **symbols and name paths** rather than on lines and columns.
14+
This is a deliberate design choice: line numbers and column offsets are fragile and shift with every edit,
15+
making them unreliable anchors for agents working on evolving code.
16+
Symbols (classes, methods, functions) are stable, meaningful identifiers that agents can reason about naturally.
17+
Tool results are compact JSON, keeping token usage low and output qujuality high.
18+
- **LLM- and framework-independent** -- Serena is not tied to any specific LLM, agent framework, or interface. It works with any MCP-compatible client
19+
and can be integrated into custom agent pipelines.
20+
- **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.
21+
- **Project-based configuration** -- Each project can have its own configuration, language servers, and memory store. Modes and contexts allow
22+
tailoring the active tool set to the workflow at hand.
23+
- **Memories** -- A simple but effective Markdown-based memory system allows agents to persist and retrieve project knowledge across sessions,
24+
including automatic onboarding for new projects.
25+
26+
## Navigation
27+
28+
Serena's navigation tools allow agents to explore codebases at the symbol level, understanding structure and relationships
29+
without reading entire files.
30+
31+
| Capability | Language Server | JetBrains Plugin |
32+
|-------------------------------------|--------------------------------------|-----------------------|
33+
| **Symbol overview** (file outline) | yes | yes |
34+
| **Find symbol** (by name path) | yes | yes |
35+
| **Find referencing symbols** | yes | yes |
36+
| **Find implementations** | yes (limited language support) | yes (all languages) |
37+
| **Go to definition** | yes | yes |
38+
| **Type hierarchy** (super/subtypes) | -- | yes |
39+
| **Search in dependencies** | -- | yes |
40+
41+
The JetBrains backend supports **find implementations** across all languages, whereas the LS backend is limited to
42+
languages whose language server supports it (e.g., not Python). The **type hierarchy** and **dependency search** are
43+
JetBrains-exclusive features.
44+
45+
<!-- TODO: Add navigation demo video here
46+
<video src=""
47+
controls
48+
preload="metadata"
49+
style="max-width: 100%; height: auto;">
50+
Your browser does not support the video tag.
51+
</video>
52+
-->
53+
54+
## Refactoring
55+
56+
Serena supports safe, codebase-wide refactoring operations.
57+
58+
| Capability | Language Server | JetBrains Plugin |
59+
|---------------------------------------------|-----------------|------------------|
60+
| **Rename symbol** | yes | yes |
61+
| **Safe delete** | yes | yes |
62+
| **Propagate deletions, remove unused code** | -- | yes |
63+
| **Move** (symbol, file, directory) | -- | yes |
64+
| **Inline method** | -- | yes |
65+
66+
**Rename** updates all references across the codebase automatically.
67+
The JetBrains backend adds **move** (relocate symbols, files, or directories with automatic reference updates),
68+
**inline method** (replace a method with its body at all call sites), and **safe delete** (delete a symbol only
69+
after verifying it is unused, or propagate the deletion to remove all usages).
70+
71+
<!-- TODO: Add refactoring demo video here
72+
<video src=""
73+
controls
74+
preload="metadata"
75+
style="max-width: 100%; height: auto;">
76+
Your browser does not support the video tag.
77+
</video>
78+
-->
79+
80+
## Diagnostics
81+
82+
Diagnostics expose compiler errors, warnings, and hints to the agent, enabling it to identify and fix issues
83+
without running external build commands.
84+
85+
| Capability | Language Server | JetBrains Plugin |
86+
|---------------------------------------|-----------------|------------------|
87+
| **File diagnostics** (by line range) | yes | yes |
88+
| **Symbol diagnostics** (+ references) | yes | yes |
89+
| **Automatic post-edit diagnostics** | yes | yes |
90+
| **Quick fixes** | -- | yes |
91+
92+
Both backends surface compiler errors, warnings, and hints. Serena's editing tools automatically report new diagnostics
93+
after every edit, giving the agent immediate feedback on whether its changes introduced errors.
94+
95+
The JetBrains backend provides diagnostics customized to the user's IDE inspection profile and can offer
96+
**quick fixes** -- automated, one-click resolutions for common issues.
97+
98+
<!-- TODO: Add diagnostics demo video here
99+
<video src=""
100+
controls
101+
preload="metadata"
102+
style="max-width: 100%; height: auto;">
103+
Your browser does not support the video tag.
104+
</video>
105+
-->
106+
107+
## Debugging
108+
109+
Debugging integration is included **only for the JetBrains backend**.
110+
111+
<!-- TODO: Add debugging demo video here
112+
<video src=""
113+
controls
114+
preload="metadata"
115+
style="max-width: 100%; height: auto;">
116+
Your browser does not support the video tag.
117+
</video>
118+
-->
119+
120+
## Editing
121+
122+
Serena provides both symbol-level and file-level editing tools for precise code modifications.
123+
124+
| Capability | Language Server | JetBrains Plugin |
125+
|-------------------------------|-----------------|--------------------|
126+
| **Replace symbol body** | yes | yes |
127+
| **Insert after symbol** | yes | yes |
128+
| **Insert before symbol** | yes | yes |
129+
| **Auto-format after edit** | -- | yes |
130+
131+
Symbol-level editing is Serena's recommended approach: the agent retrieves a symbol's body, modifies it, and writes
132+
it back using `replace_symbol_body`. This avoids line-number fragility and ensures precise edits.
133+
134+
The JetBrains backend automatically **formats code** after every edit using the project's configured code style,
135+
so the agent doesn't need to worry about indentation or formatting conventions.
136+
137+
<!-- TODO: Add editing demo video here
138+
<video src=""
139+
controls
140+
preload="metadata"
141+
style="max-width: 100%; height: auto;">
142+
Your browser does not support the video tag.
143+
</video>
144+
-->
145+
146+
## Basic Features
147+
148+
Beyond its semantic capabilities, Serena includes a set of basic utilities for completeness.
149+
When Serena is used inside an agentic harness such as Claude Code or Codex, these tools are typically disabled by default,
150+
since the surrounding harness already provides overlapping file, search, and shell capabilities.
151+
152+
- **`search_for_pattern`** -- Flexible regex search across the codebase with glob-based file filtering, context lines,
153+
and the option to restrict to code files only. Useful when you don't know the exact symbol name.
154+
- **`list_dir` / `find_file`** -- Directory listing and file search with glob support. Helps agents orient themselves
155+
in unfamiliar projects.
156+
- **`read_file`** -- Read files or file chunks by line range, for cases where symbolic access isn't applicable
157+
(e.g. configuration files, HTML templates).
158+
- **`execute_shell_command`** -- Run shell commands (builds, tests, linters) directly from the agent,
159+
with configurable working directory and output limits.
160+
- **Memories** (`write_memory`, `read_memory`, `list_memory`, `edit_memory`, `delete_memory`, `rename_memory`) --
161+
Persistent, Markdown-based project knowledge that survives across sessions. Supports hierarchical topics
162+
and global (cross-project) memories.
163+
- **Onboarding** -- Automatic project familiarization on first encounter, storing key information as memories for future use.
164+
- **Thinking tools** -- Structured reflection prompts (`think_about_collected_information`, `think_about_task_adherence`,
165+
`think_about_whether_you_are_done`) that improve agent reasoning quality during complex tasks.

0 commit comments

Comments
 (0)