Pod to App: Claude Code
How to install Serena in Claude Code
By Sophie Filer · Updated 11 Nov 2026 · Steps checked against Serena's own docs on 11 Nov 2026
The short answer
Install Serena with uv tool install -p 3.13 serena-agent, run serena init, then serena setup claude-code. Serena then gives Claude Code symbol-level search, rename and edit tools backed by a language server.
uv tool install -p 3.13 serena-agent
serena init
serena setup claude-code- Needs
- uv
- Languages
- 40+ via language servers
- Sign-in
- None
- Price
- Free; JetBrains plugin paid
Install it step by step
- Step 1: Install uv, then Serena:
uv tool install -p 3.13 serena-agent. Theserenacommand should now work in your shell. - Step 2: Run
serena initto set it up with the free language-server backend and check everything works. - Step 3: Run
serena setup claude-codeto connect it to Claude Code. - Step 4: Start Claude Code, run
/mcp, and reconnect serena if it shows as not ready. - Step 5: Ask: "Use Serena to find every caller of
createOrderand rename it toplaceOrder."
Add it by hand: one project or all of them
| Scope | Command |
|---|---|
| Every project | claude mcp add --scope user serena -- serena start-mcp-server --context claude-code --project-from-cwd |
| This project only | claude mcp add serena -- serena start-mcp-server --context claude-code --project "$(pwd)" |
The claude-code context matters: it turns off Serena's basic file and shell tools that Claude Code already has, so the two do not compete.
Add the hooks so Claude Code keeps using it
Serena's docs are frank: recent Claude Code versions often forget Serena's tools and drift back to grep and file reads. Their fix is a set of optional hooks. Add them to .claude/settings.json in the project, or ~/.claude/settings.json for everything:
{
"hooks": {
"PreToolUse": [
{ "matcher": "", "hooks": [{ "type": "command", "command": "serena-hooks remind --client=claude-code" }] },
{ "matcher": "mcp__serena__*", "hooks": [{ "type": "command", "command": "serena-hooks auto-approve --client=claude-code" }] }
],
"SessionStart": [
{ "matcher": "", "hooks": [{ "type": "command", "command": "serena-hooks activate --client=claude-code" }] }
],
"SessionEnd": [
{ "matcher": "", "hooks": [{ "type": "command", "command": "serena-hooks cleanup --client=claude-code" }] }
]
}
}remindnudges Claude Code toward Serena after several grep or file-read calls in a row.activateasks it to activate the project and read Serena's instructions when a session starts.auto-approveapproves Serena's tools when you are already in a permissive mode, instead of prompting every time.cleanuptidies session data at the end. Include only the hooks you want.
If it does not work
| What you see | What to do |
|---|---|
| serena times out on start | Big projects take time to index. Set export MCP_TIMEOUT=60000 in your shell profile. |
Command serena not found by Claude Code | Use the full path to the serena executable in the add command. |
| Connected, but Claude Code ignores it | Add the hooks above. Serena also offers a system prompt override: claude --system-prompt="$(serena prompts print-cc-system-prompt-override)". |
| A language is not understood | Some languages need extra language-server dependencies; see Serena's language support page. |
MCP Shelf take
Is Serena worth adding to Claude Code?
Serena makes the biggest difference on large codebases, where Claude Code would otherwise grep, read whole files and edit by text matching. With Serena it can jump to a symbol, find real references and rename across files in one step. It is not a no-brainer, though: setup takes a few commands, and you need the hooks or Claude Code tends to forget it exists. On a small project you may not notice it. On a big one in a typed language, it is one of the most useful servers on the shelf.
Sophie Filer
Questions
Is Serena free?
Yes, with the default language-server backend. The optional JetBrains plugin backend is paid, with a free trial, and adds things like moving files and type hierarchy.
Why does Claude Code not use Serena's tools?
Claude Code leans toward its own built-in tools. Serena provides hooks that remind it and activate the project, plus an optional system prompt override.
Should I install Serena from a marketplace?
No. Serena says marketplace entries carry outdated install commands. Install with uv and run serena setup claude-code.
Sources: the steps on this page are written in our own words from Serena's own install docs, the README, the README. If they disagree with this page, the project's docs win; please tell us from the server page.
