Stop Burning Tokens on Full-File Reads: How Serena Gives Claude Code IDE-Level Symbol Navigation (3 Commands, 40+ Languages)

Last Verified: September 2026 — commands checked against Serena’s official GitHub docs and CLI source

You ask Claude Code to change one function, and it greps for the name, opens a 900-line file, reads half of it, opens three more files, and your context window is gone before the first edit. Then the rename it does is a dozen fragile find-and-replace edits that still miss a call site.

Serena fixes that by giving the agent the tools your IDE already has. It can jump straight to a symbol, list every reference to it, rename it across the project, or replace one function body without reading the rest of the file. Under the hood it runs real language servers (LSP) for 40+ languages. It’s free and open source (by Oraios AI, ~30k GitHub stars, updated daily), and setup is three commands.

uv tool install -p 3.13 serena-agent
serena init
serena setup claude-code

You have shell access and the `claude mcp` CLI on this machine. Set up the Serena MCP server and report back. Do not tell me it's done unless step 5 actually confirms it:

1. Check `uv --version`. If uv is missing, install it with the official installer for my OS:
   - macOS / Linux: `curl -LsSf https://astral.sh/uv/install.sh | sh`
   - Windows (PowerShell): `powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"`
   The installer puts uv in `~/.local/bin`, which may not be on this shell's PATH yet. Add it for this session (or call uv by its full path), then confirm `uv --version` works before continuing.
2. Install Serena: `uv tool install -p 3.13 serena-agent`, then run `serena init`.
3. Register it with Claude Code: `serena setup claude-code`. If that fails, fall back to: `claude mcp add --scope user serena -- serena start-mcp-server --context claude-code --project-from-cwd`
4. From my project root, run `serena project health-check` and show me the output.
5. Run `claude mcp list` and confirm serena shows as Connected.

If any step fails, give me the exact error and the command that produced it. Do not skip ahead.

What You’ll Need

Step-by-Step Setup

Prefer to do it by hand instead of delegating to the agent? Here’s the manual version.

curl -LsSf https://astral.sh/uv/install.sh | sh

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

uv tool install -p 3.13 serena-agent

serena init

serena setup claude-code

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

claude mcp add serena -- serena start-mcp-server --context claude-code --project "$(pwd)"

serena project index

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

{
  "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" }] }
    ]
  }
}

What Each Piece Does

The tools the agent gets

Verify It’s Actually Working

claude mcp list

“Connected” only proves the server started. Check that the language server can read your code:

serena project health-check

Then give the agent a task that needs symbol-level understanding, and watch which tools it calls:

Activate the current project with Serena. Then use Serena's tools (not grep) to find every place that calls [A FUNCTION IN YOUR CODE] and summarize how each caller uses it.

If the tool calls show mcp__serena__find_symbol and find_referencing_symbols instead of Grep and Read, it’s working end to end.

Common Mistakes to Avoid

• Installing it from an MCP or plugin marketplace. Serena’s README explicitly warns that marketplace listings carry outdated install commands. Use uv tool install as shown above.
• Assuming “Connected” means “used”. Claude Code often keeps reaching for its built-in grep/read tools. Use the system-prompt override (Step 6) and, for long sessions, the hooks (Step 7).
• Startup timeouts on big projects. If Serena doesn’t come up in time, raise the MCP timeout: export MCP_TIMEOUT=60000 in your shell profile (Windows: setx MCP_TIMEOUT 60000, then open a new terminal).
• serena not found by Claude Code. Even when it works in your terminal, the client may not see it on PATH. Replace serena in the claude mcp add command with the full path (which serena on macOS/Linux, where serena on Windows).
• Forgetting to activate the project with a global install. With --project-from-cwd, start Claude Code from the project root. Otherwise ask it to “activate the current directory as a project using Serena”.

Q&A

Official Resources

• Serena on GitHub — source, README, issue tracker
• Serena client setup docs — Claude Code, Codex, IDEs
• Serena language support — per-language requirements
• uv installation docs
• Claude Code MCP Documentation — the claude mcp command reference