Install Serena for Codex and Claude Code on Linux (2026)

Reviewed August 15, 2026. Serena’s official installation path has changed materially. Its current README says not to install through MCP or plugin marketplaces because their commands may be outdated. The documented quick start uses uv tool install -p 3.13 serena-agent, followed by serena init, then client-specific launch configuration from the Serena client guide.

Serena supplies semantic code-query and editing tools through MCP; the connected AI client still decides how to use them. Installation does not grant authority to edit every project or execute unrestricted shell commands. Configure the correct client context, project scope, and least-privilege permissions.

Prepare uv, Python, and language tooling

Do not run unreviewed installer commands as root. Keep Serena user configuration and project configuration owned by the developer or managed service identity that will run the client.

• Install uv from its official documentation and verify the executable and version.
• Ensure Python 3.13 is available through the supported uv workflow.
• Inventory the programming languages in the pilot repository and install only required language-server dependencies.
• Use a non-sensitive pilot project without production secrets or unrelated filesystem mounts.
• Decide whether to use the default language-server backend or the separately documented JetBrains backend.

Install and initialize Serena

Avoid copied historical commands that use old repository entry points, obsolete flags, or a generic desktop context. Serena's client documentation is authoritative for the current MCP command and client-specific context.

1. Run uv tool install -p 3.13 serena-agent using the official quick start.
2. Confirm the serena command is available in the intended user environment.
3. Run serena init and review the resulting configuration and success output.
4. Read the client-specific instructions for Codex or Claude Code and configure the documented launch command.
5. Start the client, activate the exact pilot project, and confirm the expected language backend.

Validate semantic behavior

If a language server fails, diagnose its runtime and project configuration. Do not enable broad shell or raw filesystem tools merely to work around a missing language dependency.

• Request a symbols overview and locate a known declaration without changing files.
• Find references to a known symbol and compare them with the language server or repository search.
• Make one bounded test edit on a disposable branch and inspect the exact diff.
• Run the repository’s normal validation and revert the test change.
• Restart the client and verify project activation, configuration ownership, and reproducibility.

Secure the MCP integration

MCP server instructions and tool output are part of the agent's trust boundary. Keep human review and repository tests between an agent-generated change and any release.

Implementation and review gate

Recheck the Serena README and client guide immediately before publication. Do not publish marketplace commands, local user paths, project secrets, tokens, or a client configuration that was not tested on current Codex and Claude Code versions.

ITECS can help Dallas organizations plan and validate this work through AI consulting and strategy services. Product, legal, security, and compliance decisions remain subject to the organization’s current requirements and the named review gate below.

Primary sources

• Serena official README and quick start
• Serena client configuration guide
• Serena language support
• Astral uv installation