mcpField
S
serena-config

serena-config

github.com/paulnsorensenAgent workflows157 installsUpdated today
Repository

About serena-config

A skill for configuring Serena's global and per-project settings. It helps Serena users choose the right configuration layer, diagnose language-server and indexing issues, and verify changes.

Key features

  1. 01Guidance for global and project configuration
  2. 02Routing to relevant configuration references
  3. 03Troubleshooting language and workspace settings
  4. 04Config verification with system prompt and symbol lookup
  5. 05Cache reset and MCP server restart guidance

Use cases

  1. 01Configuring language and ignore rules for a repository
  2. 02Setting global contexts, modes, or toolsets
  3. 03Diagnosing symbol lookup and language-server errors

MCP support

Serena can run as an MCP server via `serena start-mcp-server`. The skill covers configuration options for its startup arguments and notes when a server restart may be needed.

Install

Copy the command and run it in a terminal.

$npx skills add https://github.com/paulnsorensen/skillz-that-grillz --skill serena-config

After installing, type/serena-configin Claude Code to confirm it loaded.

Bundled filesreferences/global-config.mdreferences/project-config.md

Details

From the project README

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:

  1. Global — ~/.serena/serena_config.yml. Defaults for every project: language backend, default tools/modes, global ignore rules, language-server tuning.
  2. Project — <repo>/.serena/project.yml. Per-repo overrides: languages, ignore rules, write access, monorepo workspace folders, added modes.
  3. Contexts & modes — composable toolset/prompt presets, set globally, per-project, or at startup.
  4. 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 pathreferences/project-config.md
Create / index / activate a project; understand project.local.yml local overridesreferences/project-config.md
Set machine-wide defaults: language backend, default tools/modes, global ignore, loggingreferences/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 versionreferences/global-config.md
Move the data directory (SERENA_HOME) or the per-project .serena folderreferences/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:

SymptomLayerFix lives in
LSP can't resolve symbols across package boundaries (monorepo)projectadditional_workspace_folders
find_symbol returns wrong-language results or LSP errors at startupprojectlanguages:
Symbol search floods from vendor/, node_modules/, dist/, generated codeprojectignored_paths:
Repo is review-only and Serena should not writeprojectread_only: true
Wrong toolset for the harness (e.g. Claude Code duplicating built-ins)global--context
Want planning-only or memory-free behaviorglobalmodes
Self-installed LSP, or need to pin an LSP/runtime versioneitherls_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

Comments

Markdown supported