serena-config
Configure Serena across its two layers: the
machine-wide global config and a repo's per-project config.
Serena is configured in layers, each overriding or extending the one above:
- Global —
~/.serena/serena_config.yml. Defaults for every project: language
backend, default tools/modes, global ignore rules, language-server tuning.
- Project —
<repo>/.serena/project.yml. Per-repo overrides: languages,
ignore rules, write access, monorepo workspace folders, added modes.
- Contexts & modes — composable toolset/prompt presets, set globally,
per-project, or at startup.
- CLI args to
serena start-mcp-server — override or extend everything above.
<certain> Many project.yml keys extend or override serena_config.yml.
Put machine-wide defaults in the global file; put only repo-specific aspects in
the project file.
Route to the right reference
| The user wants to… |
Read |
Tune a single repo: wrong language, monorepo cross-refs, ignore vendor//generated dirs, read-only repo, per-repo LSP path |
references/project-config.md |
Create / index / activate a project; understand project.local.yml local overrides |
references/project-config.md |
| Set machine-wide defaults: language backend, default tools/modes, global ignore, logging |
references/global-config.md |
Pick or change a context (claude-code, ide, desktop-app, …) |
references/global-config.md |
Add / override modes (planning, editing, no-memories, query-projects, …) |
references/global-config.md |
Point Serena at a self-installed language server (ls_path) or pin an LSP version |
references/global-config.md |
Move the data directory (SERENA_HOME) or the per-project .serena folder |
references/global-config.md |
When to act (and when not to)
Serena auto-creates both config files with sensible defaults — global on first run,
project on first activation of a repo. Most repos need no edits. Touch a config
only when one of these is true:
| Symptom |
Layer |
Fix lives in |
| LSP can't resolve symbols across package boundaries (monorepo) |
project |
additional_workspace_folders |
find_symbol returns wrong-language results or LSP errors at startup |
project |
languages: |
Symbol search floods from vendor/, node_modules/, dist/, generated code |
project |
ignored_paths: |
| Repo is review-only and Serena should not write |
project |
read_only: true |
| Wrong toolset for the harness (e.g. Claude Code duplicating built-ins) |
global |
--context |
| Want planning-only or memory-free behavior |
global |
modes |
| Self-installed LSP, or need to pin an LSP/runtime version |
either |
ls_specific_settings |
If none apply, leave the config alone — the bootstrap is correct.
The one proactive exception — ignored_paths. Unlike the rows above, this is
worth setting before you feel pain in any repo that commits vendored or
generated code (vendor/, checked-in dist/, generated clients, snapshot
fixtures). .gitignore is honored by default, but committed noise pollutes
find_symbol / get_symbols_overview (and can cut the LSP's initial indexing). See
references/project-config.md § "ignored_paths — set this in most non-trivial
repos". ls_path, by contrast, stays an escape hatch — managed-first is the
recommended default (see references/global-config.md).
Editing discipline
- Never hand-create a config from scratch. Let Serena bootstrap it
(
serena project create for a project, first run for the global file), then
edit. The generated files carry inline documentation comments and fields added
by newer versions — preserve them.
- Verify after editing.
serena print-system-prompt "$(pwd)" renders the
resolved config; confirm the project name, language list, active modes, and
excluded tools are what you expect. Then probe the LSP with a find_symbol
call against a known symbol — a clean record means the languages parsed; an LSP
startup error means languages: or ls_specific_settings: is wrong.
- On LSP weirdness after a change, delete
.serena/cache/ to force a rebuild;
some servers also need the MCP server restarted to fully reset.
References
1---2name: serena-config3description: Configure the Serena MCP server — its global defaults and a repo's per-project settings. Use when the user says "configure serena", "set up serena for this repo", "serena project config", "serena global config", "tune serena for this codebase", "edit serena_config.yml", "edit project.yml", "monorepo serena", "serena picked the wrong language", "serena is indexing vendor/node_modules", "make serena read-only here", "serena contexts and modes", "what context for claude-code", "disable serena memory/onboarding", "point serena at my installed language server", "ls_specific_settings", "ls_path", "SERENA_HOME", or "move the .serena folder". Routes per-repo `.serena/project.yml` questions to `references/project-config.md` and machine-wide `~/.serena/serena_config.yml` (settings, contexts, modes, language-server tuning) to `references/global-config.md`. Do NOT use for general "use serena to find / edit X" routing — that is an MCP-routing concern, not configuration.4license: MIT5---67# serena-config89Configure [Serena](https://oraios.github.io/serena/) across its two layers: the10machine-wide global config and a repo's per-project config.1112Serena is configured in layers, each overriding or extending the one above:13141. **Global** — `~/.serena/serena_config.yml`. Defaults for every project: language15 backend, default tools/modes, global ignore rules, language-server tuning.162. **Project** — `<repo>/.serena/project.yml`. Per-repo overrides: languages,17 ignore rules, write access, monorepo workspace folders, added modes.183. **Contexts & modes** — composable toolset/prompt presets, set globally,19 per-project, or at startup.204. **CLI args** to `serena start-mcp-server` — override or extend everything above.2122> `<certain>` Many `project.yml` keys *extend* or *override* `serena_config.yml`.23> Put machine-wide defaults in the global file; put only repo-specific aspects in24> the project file.2526## Route to the right reference2728| The user wants to… | Read |29| --- | --- |30| Tune a single repo: wrong language, monorepo cross-refs, ignore `vendor/`/generated dirs, read-only repo, per-repo LSP path | `references/project-config.md` |31| Create / index / activate a project; understand `project.local.yml` local overrides | `references/project-config.md` |32| Set machine-wide defaults: language backend, default tools/modes, global ignore, logging | `references/global-config.md` |33| Pick or change a **context** (`claude-code`, `ide`, `desktop-app`, …) | `references/global-config.md` |34| Add / override **modes** (`planning`, `editing`, `no-memories`, `query-projects`, …) | `references/global-config.md` |35| Point Serena at a self-installed language server (`ls_path`) or pin an LSP version | `references/global-config.md` |36| Move the data directory (`SERENA_HOME`) or the per-project `.serena` folder | `references/global-config.md` |3738## When to act (and when not to)3940Serena auto-creates both config files with sensible defaults — global on first run,41project on first activation of a repo. **Most repos need no edits.** Touch a config42only when one of these is true:4344| Symptom | Layer | Fix lives in |45| --- | --- | --- |46| LSP can't resolve symbols across package boundaries (monorepo) | project | `additional_workspace_folders` |47| `find_symbol` returns wrong-language results or LSP errors at startup | project | `languages:` |48| Symbol search floods from `vendor/`, `node_modules/`, `dist/`, generated code | project | `ignored_paths:` |49| Repo is review-only and Serena should not write | project | `read_only: true` |50| Wrong toolset for the harness (e.g. Claude Code duplicating built-ins) | global | `--context` |51| Want planning-only or memory-free behavior | global | modes |52| Self-installed LSP, or need to pin an LSP/runtime version | either | `ls_specific_settings` |5354If none apply, leave the config alone — the bootstrap is correct.5556**The one proactive exception — `ignored_paths`.** Unlike the rows above, this is57worth setting *before* you feel pain in any repo that commits vendored or58generated code (`vendor/`, checked-in `dist/`, generated clients, snapshot59fixtures). `.gitignore` is honored by default, but committed noise pollutes60`find_symbol` / `get_symbols_overview` (and can cut the LSP's initial indexing). See61`references/project-config.md` § "`ignored_paths` — set this in most non-trivial62repos". `ls_path`, by contrast, stays an escape hatch — managed-first is the63recommended default (see `references/global-config.md`).6465## Editing discipline6667- **Never hand-create a config from scratch.** Let Serena bootstrap it68 (`serena project create` for a project, first run for the global file), then69 edit. The generated files carry inline documentation comments and fields added70 by newer versions — preserve them.71- **Verify after editing.** `serena print-system-prompt "$(pwd)"` renders the72 resolved config; confirm the project name, language list, active modes, and73 excluded tools are what you expect. Then probe the LSP with a `find_symbol`74 call against a known symbol — a clean record means the languages parsed; an LSP75 startup error means `languages:` or `ls_specific_settings:` is wrong.76- **On LSP weirdness after a change**, delete `.serena/cache/` to force a rebuild;77 some servers also need the MCP server restarted to fully reset.7879## References8081- Project config schema (template): <https://github.com/oraios/serena/blob/main/src/serena/resources/project.template.yml>82- Global config schema (template): <https://github.com/oraios/serena/blob/main/src/serena/resources/serena_config.template.yml>83- Language enum (valid `languages:` / `ls_specific_settings` keys): <https://github.com/oraios/serena/blob/main/src/solidlsp/ls_config.py>84- Workflow docs: <https://oraios.github.io/serena/02-usage/040_workflow.html>85- Configuration docs: <https://oraios.github.io/serena/02-usage/050_configuration.html>
paulnsorensen