Schonarth Pivot Setting Up Serena

Setting Up Serena

Serena is an MCP server that gives coding agents semantic, symbol-level code intelligence. It replaces grep-based search with precise go-to-definition, find-references, and atomic rename across the codebase.

When to Use

• User asks to install or configure Serena
• Serena MCP tools are unavailable in a session
• A new project needs Serena onboarding
• The TypeScript LSP is missing (Serena symbolic tools silently fail on .ts/.tsx without it)

Instructions

Step 1 — Install Serena

Requires uv. If uv is not installed, tell the user to install it first: https://docs.astral.sh/uv/getting-started/installation/

uv tool install -p 3.13 serena-agent@latest --prerelease=allow

Then register Serena as a user-scoped MCP server in the clients you use:

Claude Code:

claude mcp add --scope user serena -- \
  serena start-mcp-server --context claude-code \
  --project-from-cwd

Codex:

codex mcp add serena -- \
  serena start-mcp-server --context=codex \
  --project-from-cwd

Verify registration:

claude mcp list
codex mcp list

serena must appear in the output for each client you plan to use.

Step 2 — Install Claude Code Hooks

Add the following to .claude/settings.json (create the file if it does not exist). Merge with any existing content — do not overwrite other hooks.

See references/hooks-config.md for the full hooks block.

The hooks do four things:

Codex does not use Claude's hooks file. Register Serena in Codex separately via codex mcp add ... above.

Step 3 — Install TypeScript LSP

Serena's symbolic tools for .ts/.tsx files require the TypeScript language server binary and the Claude Code plugin.

Install the binary:

npm install -g typescript-language-server typescript
which typescript-language-server   # must return a path

Install the plugin for Claude Code:

/plugin install typescript-lsp@claude-plugins-official
/reload-plugins

If the marketplace is not available, add it first:

/plugin marketplace add anthropics/claude-plugins-official
/plugin install typescript-lsp@claude-plugins-official
/reload-plugins

Verify: run /plugin → Installed tab → typescript-lsp must be listed and active.

Codex uses Serena's codex MCP context and does not need the Claude plugin install step.

Step 4 — Configure the Project Language

Serena needs to know the project language to activate the LSP. Check .serena/project.yml:

cat .serena/project.yml 2>/dev/null || echo "NOT FOUND"

If the file does not exist or typescript is not listed under languages:, add it:

languages:
  - typescript

Step 5 — Run Project Onboarding

Start a fresh conversation after completing the steps above (the MCP server must be active). Then call:

mcp__serena__onboarding

Serena will read the project structure and write memory files under .serena/memories/. After onboarding completes, start another fresh conversation — onboarding fills context and the next session benefits from the generated memories.

Review the generated memories and adjust any that are inaccurate.

Common Edge Cases

• serena start-mcp-server not found: The uv tool install step was skipped or failed. Re-run it.
• MCP tools still missing after install: Restart the client (Claude Code or Codex) to reload the MCP server list.
• TypeScript LSP errors tab shows "Executable not found": typescript-language-server is not on $PATH. Re-run npm install -g typescript-language-server typescript.
• Hooks not firing: The serena-hooks binary must be on $PATH — it is installed alongside Serena via uv tool install. Verify with which serena-hooks.
• Onboarding fills context: Always start a fresh conversation before and after running onboarding.

Related Skills

• .claude/skills/managing-design-system/ — requires Serena and the TypeScript LSP to function
• .claude/skills/building-skills/ — for creating new skills

Source: schonarth/pivot — distributed by TomeVault.