oraios/serena

A powerful MCP toolkit for coding, providing semantic retrieval and editing capabilities - the IDE for your agent

Serena – an IDE‑style toolkit for AI coding agents

What it is – Serena is a server‑side “toolbox” that gives large language‑model agents IDE‑level capabilities such as symbol‑aware code search, cross‑file refactoring, safe edits and (via a JetBrains plugin) interactive debugging. It does not contain its own LLM; instead it talks to any client that supports the Model Context Protocol (MCP) – e.g. Claude Code, Codex CLI, VS Code AI assistants, etc.

Why it matters – Current agents often operate on raw text, which makes large‑scale changes brittle. Serena lifts the agent to the symbol level, letting it understand declarations, references, hierarchies and perform atomic refactorings just like a human developer would. The README reports that agents using Serena cut the number of steps for typical tasks by 8‑12 and feel “sharper and calmer”.

Core features

Category	What you get
Retrieval	Find symbols, get symbol outlines, locate references, query external projects, diagnostics – all at the symbol level.
Refactoring	Symbol‑only rename (LSP), full rename/move/inline/delete with the JetBrains plugin.
Symbolic editing	Replace a symbol’s body, insert before/after a symbol, safe delete – without regex hacks.
Debugging (JetBrains only)	REPL‑style breakpoint setting, variable inspection, expression evaluation.
Basic utilities	Regex search, replace, directory/file listing, file reading, shell command execution.
Memory system	Simple persistent store so an agent can remember information across sessions.
Configurable	YAML‑based configuration layers (global, per‑project, per‑client, dynamic fragments).
Back‑ends	• Language‑server mode – uses any LSP server (covers >40 languages). • JetBrains plugin – leverages the full analysis engine of JetBrains IDEs (paid, free trial).

How it works

Install the serena-agent tool with the Python‑centric package manager uv (uv tool install -p 3.13 serena-agent).
Run serena init to start an MCP server (default LSP backend) or serena init -b JetBrains for the JetBrains plugin.
Configure your AI client (Claude Code, Codex, VS Code AI extensions, etc.) to launch or point at the MCP server. The client then sends tool‑use requests to Serena, which performs the semantic operation and returns the result.
Agents can chain these tools (e.g., find symbol → rename → commit) to accomplish complex development workflows.

Who should use it

Developers building agentic coding assistants who need reliable, symbol‑aware operations.
Researchers evaluating LLM‑based code‑generation pipelines – Serena provides a reproducible “IDE layer” for experiments.
Teams with large monorepos where cross‑file refactors and dependency navigation are common.

Quick start (from the README)

# 1. Install uv (if you don’t have it)
# 2. Install Serena
uv tool install -p 3.13 serena-agent

# 3. Initialise the server (LSP backend by default)
serena init

# 4. Follow the user‑guide to point your MCP‑enabled client at the server

Additional language‑specific dependencies may be required when using the LSP backend.

Documentation & community

Full docs – https://oraios.github.io/serena/
Discord – https://discord.com/invite/cVUNQmnV4r (support and discussion)
Video intro – YouTube link in the README.

License

Core SolidLSP component – MIT.
The rest of the Serena application – GPL‑3.0‑or‑later (GPL for combined distributions).
Contributions require signing a CLA.

Bottom line – Serena is a genuine open‑source project that supplies AI coding agents with IDE‑grade, symbol‑level tooling, making large‑scale automated code manipulation practical and reliable.