Serena onboard

Serena Onboard

Get a repository from "Serena not set up" to "Serena connected, codebase onboarded into a queryable memory store, symbol tools verified working" — in the correct order, respecting the one hard constraint that trips most attempts: an MCP server only loads on a fresh Claude Code session, so installation and use cannot happen in the same session.

Serena gives the agent LSP-backed, symbol-level retrieval (find_symbol, find_referencing_symbols, get_symbols_overview) plus a persistent project memory under .serena/memories/. The payoff is that "what calls this?" becomes one tool call instead of a grep storm, and orientation learned once is recalled across sessions without re-reading files. This skill makes that real for a repo that doesn't have it yet.

Step 0: Determine which state you're in

Run these checks before doing anything else. The right action depends entirely on the answer.

1. Are Serena MCP tools available in this session? Look for tools named mcp__serena__* (e.g. mcp__serena__find_symbol). If none exist, Serena is not loaded in this session.
2. Is the project already registered? Check for .serena/project.yml in the repo root.
3. Has onboarding already run? If Serena tools exist, call check_onboarding_performed. Otherwise check whether .serena/memories/ exists and contains .md files.

Map to one of three states:

• State A — Serena not loaded this session (no mcp__serena__* tools). → Do Phase 1 (host setup), then STOP and require a restart. You cannot proceed to onboarding in this session.
• State B — Serena loaded, not yet onboarded (tools present, check_onboarding_performed is false / no memories). → Skip Phase 1. Do Phase 2 (onboard + build memory).
• State C — already onboarded (tools present, memories exist). → No setup needed here. list_memories, read core, and report what's there. If the user wants to pick up code changes since last time, that's the serena-refresh skill's job, not a re-onboard. Do not re-run onboarding.

State A is the common case the first time you touch a repo.

---

Phase 1: Host setup (State A only)

Goal: install Serena, register it for this project only, wire the Claude Code tool-bias fixes, then hand the user a restart command. Do the work; don't just describe it.

Run the bundled bootstrap script from the repo root — it is idempotent and safe to re-run:

bash scripts/bootstrap.sh

It will: verify uv is installed; install Serena (uv tool install -p 3.13 serena-agent@latest --prerelease=allow) and run serena init; register the project with claude mcp add serena -- serena start-mcp-server --context claude-code --project "$(pwd)" only if not already registered; ensure MCP_TIMEOUT=60000 is exported (the TypeScript/Java/etc. language servers are slow to warm on large monorepos and the default timeout can drop the connection); and merge the four recommended Serena hooks into .claude/settings.json without clobbering existing keys.

If the script reports uv is missing, point the user to https://docs.astral.sh/uv/getting-started/installation/ and stop — installing uv is a system change they should make deliberately.

If any command errors or behaves oddly, the upstream commands may have moved. Read references/serena-commands.md, and if that's not enough, fetch the current docs (URLs are in that file) and adapt rather than guessing.

Why the tool-bias fixes matter

Recent Claude Code + Opus builds devote ~16k tokens to built-in tool descriptions that bias the agent strongly toward its own grep/read. Without counter-measures you get Serena connected but ignored — the worst outcome, because it looks set up but the agent still greps. The two counter-measures are the hooks (installed above) and a system-prompt override applied at launch.

Then STOP and require a restart

The MCP server is not yet in this session. Tell the user — clearly and verbatim — to relaunch Claude Code with the override:

claude --system-prompt="$(serena prompts print-cc-system-prompt-override)"

If they launch Claude Code from an editor/plugin (e.g. claudecode.nvim), note that the --system-prompt flag must be wired into the plugin's launch command, or for a one-off they can just run the above in a plain terminal in the repo root. Then they re-invoke this skill (or say "continue onboarding") in the new session, which lands in State B. End Phase 1 here.

---

Phase 2: Onboard and build the memory store (State B)

Now Serena tools are live. Build a memory store the agent will actually reload on every future session.

1. Activate if needed. Single-project claude-code context usually auto-activates (a SessionStart hook prompts it). If symbol tools complain there's no active project, activate the current directory, then call check_onboarding_performed.

2. Run Serena's onboarding tool once. It reads key files and seeds initial memories. Onboarding is at most once per conversation.

3. Fold in the repo's own guidance — do not reinvent or clobber it. Read any existing CLAUDE.md (root and subdirectory), AGENTS.md, .cursorrules / .cursor/rules/, .github/copilot-instructions.md, .clinerules. These encode hard-won conventions. Capture their substance in memories; never edit these tracked files.

4. Write a structured memory graph, not one dumping-ground note. Follow references/memory-blueprint.md for the exact set (a core root that links to architecture/*, tech_stack, commands, conventions, task_completion, tool_quirks) and how to generalise it across language/build systems. Detect the stack from manifests (package.json, pyproject.toml, go.mod, Cargo.toml, pom.xml, etc.) so the commands and verification rules are right for this repo, not boilerplate.

5. Capture a tool_quirks memory. Record any Serena parameter-name or behaviour quirks you hit (these vary by build — e.g. find_symbol taking name_path_pattern while find_referencing_symbols takes name_path), so future sessions don't waste turns on failed tool calls.

6. Verify with symbol tools ONLY. Pick a real "where does X actually happen?" question for this codebase and answer it using only get_symbols_overview, find_symbol, and find_referencing_symbols — no grep, no full-file reads. This is the acceptance test: it proves the language server is warm and the agent is routing through Serena. Report which tools you used. If you find yourself reaching for grep, the LSP isn't warm yet or the override/hooks aren't active — fix that before declaring success.

7. Set the refresh baseline. Record the current commit so the serena-refresh skill can later scope updates to just what changed:

   git rev-parse HEAD > .serena/last_refresh
   

8. Handoff. Summarise the memories written and the answer to the verification question. Note that .serena/ is local state; if the user doesn't want it committed, confirm it's gitignored (Serena usually adds this). Mention that future code changes are picked up with the serena-refresh skill.

---

Reference files

• scripts/bootstrap.sh — idempotent host setup for Phase 1.
• references/serena-commands.md — current install/registration commands, the hooks JSON, the system-prompt override, troubleshooting, and upstream doc URLs to consult if anything has drifted.
• references/memory-blueprint.md — the memory graph to write during Phase 2, generalised across stacks, plus the fold-in and verification recipes.

Hard-won notes

• The restart boundary is non-negotiable. Don't try to call Serena tools in the same session you installed it. State detection in Step 0 exists precisely to stop that mistake.
• Connected ≠ used. If post-restart the agent still greps, the system-prompt override almost certainly didn't apply (common with editor-launched CLIs).
• Big repos need patience on the first queries while the language server indexes; MCP_TIMEOUT covers the startup, but expect the first symbol lookups to be slow, then fast.
• Commands drift. Serena warns that third-party/marketplace install snippets go stale. Treat references/serena-commands.md as known-good-at-authoring-time and verify against upstream docs if something fails.