Serena

https://oraios.github.io/serena
Admin
Serena is a free and open-source coding agent toolkit that provides IDE-like semantic code retrieval...
Tokens:43,883
Snippets:725
Trust Score:8.3
Update:3 months ago
Show doc for...
Tokens:
Raw
### Start Agno UI

Source: https://oraios.github.io/serena/03-special-guides/custom_agent.html

Navigate to the agent-ui directory and start the UI to connect to your agent.

```bash
cd agent-ui 
pnpm dev

```

--------------------------------

### Install OCaml language server and build tools

Source: https://oraios.github.io/serena/03-special-guides/ocaml_setup_guide_for_serena.html

Install the ocaml-lsp-server and the dune build system using opam.

```bash
opam install ocaml-lsp-server dune
```

--------------------------------

### Install Serena Agent

Source: https://oraios.github.io/serena/02-usage/010_installation.html

Installs the Serena agent using the 'uv' package manager. Ensure 'uv' is installed and on your PATH.

```bash
uv tool install -p 3.13 serena-agent

```

--------------------------------

### Get General Help

Source: https://oraios.github.io/serena/02-usage/020_running.html

Run this command to list all available commands in Serena.

```bash
<serena> --help

```

--------------------------------

### Groovy Project Structure Example

Source: https://oraios.github.io/serena/03-special-guides/groovy_setup_guide_for_serena.html

Recommended project structure for optimal Groovy Language Server performance.

```text
project-root/
├── src/
│   ├── main/
│   │   ├── groovy/
│   │   └── resources/
│   └── test/
│       ├── groovy/
│       └── resources/
├── build.gradle or build.gradle.kts
├── settings.gradle or settings.gradle.kts
└── gradle/
    └── wrapper/

```

--------------------------------

### Start Serena Project Server

Source: https://oraios.github.io/serena/02-usage/040_workflow.html

Use this command to start the Serena Project Server, which is required for symbolic tools to work with the LSP backend when querying external projects.

```bash
serena start-project-server

```

--------------------------------

### Clone and Install Agent UI Manually

Source: https://oraios.github.io/serena/03-special-guides/custom_agent.html

Alternatively, clone the agent-ui repository and install dependencies manually.

```bash
git clone https://github.com/agno-agi/agent-ui.git
cd agent-ui 
pnpm install 
pnpm dev

```

--------------------------------

### Initialize Serena with Default Backend

Source: https://oraios.github.io/serena/02-usage/010_installation.html

Initializes Serena using the default language intelligence backend (language servers). Run this command after installation.

```bash
serena init

```

--------------------------------

### Install opam

Source: https://oraios.github.io/serena/03-special-guides/ocaml_setup_guide_for_serena.html

Install the OCaml package manager (opam) using your system's package manager.

```bash
brew install opam
```

```bash
sudo apt install opam
```

```bash
sudo dnf install opam
```

--------------------------------

### Start MCP Server

Source: https://oraios.github.io/serena/02-usage/020_running.html

Basic command to start the MCP server. This is the default command and does not require additional options for standard I/O mode.

```bash
serena start-mcp-server [options]
```

```bash
serena start-mcp-server
```

--------------------------------

### Install Serena with Optional Requirements

Source: https://oraios.github.io/serena/03-special-guides/custom_agent.html

Install Serena along with optional extras, such as those required for Agno integration. You can specify specific extras like 'agno,google' or 'agno,anthropic' if needed.

```bash
# You can also only select agno,google or agno,anthropic instead of all-extras
uv pip install --all-extras -r pyproject.toml -e .

```

--------------------------------

### Install ccls on Windows

Source: https://oraios.github.io/serena/03-special-guides/cpp_setup.html

Install the ccls language server on Windows using Chocolatey.

```powershell
choco install ccls

```

--------------------------------

### Setup Serena MCP Server for Claude Code

Source: https://oraios.github.io/serena/02-usage/030_clients.html

Run this command to set up the Serena MCP server for Claude Code.

```bash
serena setup claude-code

```

--------------------------------

### Verify OCaml and ocaml-lsp-server installation

Source: https://oraios.github.io/serena/03-special-guides/ocaml_setup_guide_for_serena.html

Verify the installation of the OCaml compiler and the ocaml-lsp-server by checking their versions using opam exec.

```bash
opam exec -- ocamllsp --version
opam exec -- ocaml -version
```

--------------------------------

### Install ccls on Ubuntu/Debian

Source: https://oraios.github.io/serena/03-special-guides/cpp_setup.html

Install the ccls language server on Ubuntu or Debian-based systems using apt-get.

```bash
# Ubuntu/Debian (22.04+)
sudo apt-get install ccls

```

--------------------------------

### Clone and Install Serena Repository

Source: https://oraios.github.io/serena/02-usage/020_running.html

Clone the Serena repository locally and navigate into the directory. This is a prerequisite for running Serena from the cloned source.

```bash
git clone https://github.com/oraios/serena
cd serena

```

--------------------------------

### Start Serena MCP Server via MCPO

Source: https://oraios.github.io/serena/03-special-guides/serena_on_chatgpt.html

Launches the Serena MCP server using uvx. Ensure you replace <YOUR_SECRET_KEY> with your actual secret key. The --project flag should point to your codebase root.

```bash
uvx mcpo --port 8000 --api-key <YOUR_SECRET_KEY> -- \
  serena start-mcp-server --context chatgpt --project $(pwd)
```

--------------------------------

### Read Plugin Configuration

Source: https://oraios.github.io/serena/04-evaluation/030_results/020_codex_on_jbplugin.html

Reads the plugin's main configuration file. This is a common step for understanding project setup.

```powershell
Get-Content plugin.xml
```

--------------------------------

### Configure Go Language Server Settings (gopls)

Source: https://oraios.github.io/serena/02-usage/050_configuration.html

Forward initialization options to the Go language server (gopls), such as build tags and environment variables. This example enables build tags and sets GOOS and GOARCH.

```yaml
ls_specific_settings:
  go:
    gopls_settings:
      buildFlags:
        - "-tags=foo"
      env:
        GOOS: "linux"
        GOARCH: "amd64"
        CGO_ENABLED: "0"

```

--------------------------------

### Start MCP Server in Streamable HTTP Mode

Source: https://oraios.github.io/serena/02-usage/020_running.html

Command to start the MCP server using streamable HTTP transport. Specify the port for the server to listen on. The client should then connect to `http://localhost:<port>/mcp`.

```bash
serena start-mcp-server --transport streamable-http --port <port>
```

--------------------------------

### Get MCP Server Help

Source: https://oraios.github.io/serena/02-usage/020_running.html

Command to display all available command-line options for the MCP server. This is useful for exploring advanced configurations.

```bash
<serena> start-mcp-server --help
```

--------------------------------

### Start Agno Agent Script

Source: https://oraios.github.io/serena/03-special-guides/custom_agent.html

Run the Agno agent script to start the agent. This script defaults to using Claude but can be configured to use any model supported by Agno.

```bash
uv run python scripts/agno_agent.py

```

--------------------------------

### Run Latest Serena Source with uvx

Source: https://oraios.github.io/serena/02-usage/020_running.html

Execute the latest Serena version directly from its GitHub repository using uvx. This method avoids local installation but may involve re-synchronization with each run.

```bash
uvx -p 3.13 --from git+https://github.com/oraios/serena serena 

```

--------------------------------

### Run Serena from Cloned Source (External Directory)

Source: https://oraios.github.io/serena/02-usage/020_running.html

Execute Serena from a directory outside its cloned repository using the '--directory' option. This sets the working directory to the Serena installation path.

```bash
uv run --directory /abs/path/to/serena serena

```

--------------------------------

### Configure Serena MCP Server for Read-Only or Restricted Tools

Source: https://oraios.github.io/serena/03-special-guides/serena_on_chatgpt.html

Configuration example for disabling specific tools or setting the server to read-only mode within the project's .serena/project.yml or global config. This enhances security by limiting ChatGPT's capabilities.

```yaml
excluded_tools:
  - execute_shell_command
  - ...
read_only: true
```

--------------------------------

### Evaluation Prompt for Serena's Tools vs. Built-ins

Source: https://oraios.github.io/serena/04-evaluation/020_prompts/010_evaluation-prompt.html

This prompt is used to guide an agent in evaluating the added value of Serena's tools compared to built-in agent tools. It focuses on a neutral, evidence-based comparison of capabilities and efficiency differences.

```text
# Evaluate Serena's Tools Against Built-Ins

You have access to Serena's coding tools alongside your built-in tools (Read,
Edit, Write, Glob, Grep, Bash, etc.). I want a thorough, evidence-based
evaluation of **what Serena's tools add on top of the built-ins**, assuming both
toolsets are used correctly.

This is an evaluation, not a user guide, and it is not a binary adoption pitch.
Your job is to answer: *if a competent user of both toolsets had only the
built-ins, what concrete capabilities and efficiency differences would they
experience, and by how much?* A reader who finishes your report should have a
clear, specific picture of what Serena adds — as well as where it provides no
meaningful improvement or introduces tradeoffs — in terms of capabilities,
workflows, and efficiency. Not a thumbs-up/thumbs-down, but a sharp description
of the delta.

Failure modes from misuse, silent-failure traps, gotcha comparisons, and "be
careful of X" warnings are out of scope. They belong in onboarding material for
a developer learning the tools, not in a delta analysis of what the tools add.

**Describe the measured differences clearly and neutrally.** Avoid generic or
non-informative framing such as "both have their place" unless supported by
concrete findings. If Serena adds substantial capabilities, name and quantify
them. If it adds marginal or no capabilities, say that and show why. If there
are regressions or tradeoffs, include them explicitly. The two toolsets are
complementary — that's a given, not the answer. Serena is an augmentation layer,
not a replacement. Do not penalize it for tasks it was not designed to address —
instead, note those tasks as "built-in only" and move on. The evaluation should
measure what Serena adds where it applies, not what it fails to add where it
doesn't.The answer is a specific list of what Serena contributes (or does not
contribute) to a correct-use workflow relative to built-ins.

Write the report to serena-evaluation.md in the repo root.



## Ground rules

### Starting conditions

- Start fresh. Do not read project memories, CLAUDE.md shortcuts, or prior notes
  about the repo. Do not read documentation files either. Explore as if you've
  never seen it, focusing on code.
- Use git as your safety net — experiment freely. Any edit can be reverted with
  `git checkout -- <file>` or `git stash`. Run edits for real; don't simulate. A
  hands-on comparison is worth far more than a thought experiment.
- After each experiment, verify the working tree is clean with
  `git status --short` before moving on.


### How to compare — correct use only

- **Correct-use rule.** Evaluate each tool on inputs and tasks it was designed
  for, called the way a competent user would call it. A tool doing exactly what
  its contract says is not a finding, even if a careless caller could misuse it.
- **Know the contract before you call.** Before invoking any tool, have a
  one-sentence understanding of what it does. If you expect an error or "not
  applicable," don't make the call.
- **Refactoring semantics are real.** Inlining requires a substitutable function
  (typically single-expression, no side effects); moving requires a legal
  target; safe-delete requires no surviving usages. If the repo has no suitable
  candidate for a given refactoring, report "no suitable candidate in this
  codebase" and skip it — don't contrive a broken input.


### How to compare — workflow level, not single-call level

- For every task, write out the full end-to-end call chain on each side before
  drawing conclusions. Include prerequisite reads and follow-up steps.
- Do not evaluate a tool based on criteria that only arise from mixing workflows
  incorrectly.
- Ephemeral addressing is a liability. Line numbers and byte offsets go stale
  after edits; stable addressing (name paths) may reduce rework.


### How to measure

- Track observations during execution. For every tool call, note: number of
  calls, approximate input size, output size, and any prerequisite or
  verification steps.
- Separate call count, input payload, output payload, and verification cost as
  distinct axes.
- Include prerequisite Reads and post-hoc verification steps in comparisons.

When a task falls entirely outside Serena's design scope (e.g., reading config
files, small text edits where Edit already sends minimal payload), classify it
as "not applicable" rather than as a negative delta. A negative delta requires
that Serena targets the task and performs worse, not that a tool designed for
something else is suboptimal when misapplied to it.

```

--------------------------------

### Create and Index Project

Source: https://oraios.github.io/serena/02-usage/020_running.html

Create a new Serena project and immediately index it.

```bash
serena project create --index

```

--------------------------------

### Install ccls on macOS

Source: https://oraios.github.io/serena/03-special-guides/cpp_setup.html

Install the ccls language server on macOS using Homebrew.

```bash
brew install ccls

```

--------------------------------

### Create New Serena Project

Source: https://oraios.github.io/serena/02-usage/020_running.html

Initiate a new Serena project in the current directory.

```bash
serena project create

```

--------------------------------

### Install ccls on Arch Linux

Source: https://oraios.github.io/serena/03-special-guides/cpp_setup.html

Install the ccls language server on Arch Linux using pacman.

```bash
# Arch Linux
sudo pacman -S ccls

```

--------------------------------

### Install ccls on Fedora/RHEL

Source: https://oraios.github.io/serena/03-special-guides/cpp_setup.html

Install the ccls language server on Fedora or RHEL-based systems using dnf.

```bash
# Fedora/RHEL
sudo dnf install ccls

```

--------------------------------

### Create Agent UI with npx

Source: https://oraios.github.io/serena/03-special-guides/custom_agent.html

Use npx to quickly set up the agent-ui code.

```bash
npx create-agent-ui@latest

```

--------------------------------

### Initialize Serena with JetBrains Backend

Source: https://oraios.github.io/serena/02-usage/025_jetbrains_plugin.html

Run this command to set JetBrains as the default code intelligence backend in the global Serena configuration.

```bash
serena init -b JetBrains
```

--------------------------------

### Get Command-Specific Help

Source: https://oraios.github.io/serena/02-usage/020_running.html

Append --help to any command or sub-command to get detailed usage information and available options.

```bash
<serena> <command> --help

```

```bash
serena> tools list --help

```

--------------------------------

### Initialize Serena with JetBrains Backend

Source: https://oraios.github.io/serena/02-usage/010_installation.html

Initializes Serena using the JetBrains backend, which relies on the JetBrains plugin. This can be changed later via configuration.

```bash
serena init -b JetBrains

```

--------------------------------

### Get Help for Serena CLI

Source: https://oraios.github.io/serena/02-usage/020_running.html

Append --help to the serena command to get general help or help for a specific sub-command.

```bash
serena --help
```

```bash
serena <command> --help
```

--------------------------------

### List All Tools

Source: https://oraios.github.io/serena/02-usage/020_running.html

Use the --all flag with the 'tools list' command to see all available tools.

```bash
serena> tools list --all

```

--------------------------------

### Create a new Serena project

Source: https://oraios.github.io/serena/02-usage/040_workflow.html

Use this command to explicitly create a new project. The project directory defaults to the current directory if not specified. Options include specifying languages, a custom name, and immediate indexing.

```bash
serena project create [options] [project directory]

```

--------------------------------

### Get Tool Description

Source: https://oraios.github.io/serena/02-usage/020_running.html

Retrieve a detailed description for a specific tool by providing its name to the 'tools description' command.

```bash
serena> tools description find_symbol

```

--------------------------------

### Initialize opam and set environment

Source: https://oraios.github.io/serena/03-special-guides/ocaml_setup_guide_for_serena.html

Initialize opam if it's not already set up and evaluate the environment variables for the current shell session.

```bash
opam init
eval $(opam env)
```

--------------------------------

### Find Declaration with Body (Rust)

Source: https://oraios.github.io/serena/04-evaluation/030_results/030_copilot_cli_on_ente.html

Example of finding a Rust external symbol (Url) with its struct body included.

```rust
find_declaration(use reqwest::{ Response, Url };, include_body=true)
```

--------------------------------

### Edit Configuration

Source: https://oraios.github.io/serena/02-usage/020_running.html

Open Serena's configuration file for editing.

```bash
serena config edit

```

--------------------------------

### List Modes

Source: https://oraios.github.io/serena/02-usage/020_running.html

Show all available Serena modes.

```bash
serena mode list

```

--------------------------------

### Generate Clang Database with UnrealBuildTool

Source: https://oraios.github.io/serena/03-special-guides/unreal_engine_setup_guide_for_serena.html

Use UnrealBuildTool in 'GenerateClangDatabase' mode to emit clang-native commands. This method requires a Clang toolchain installed on Windows.

```bash
<Engine>\Binaries\DotNET\UnrealBuildTool\UnrealBuildTool.exe -mode=GenerateClangDatabase -project="<YourProject>.uproject" <YourProject>Editor Win64 Development -OutputDir="<YourProject's directory>"

```

--------------------------------

### Add Serena MCP Server for Current Project

Source: https://oraios.github.io/serena/02-usage/030_clients.html

Configure the Serena MCP server specifically for the current project in the current directory using the `pwd` command.

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

```

--------------------------------

### Override Language Server Path

Source: https://oraios.github.io/serena/02-usage/050_configuration.html

Set a custom path for a language server executable. This bypasses Serena's managed download or installation for the specified language server.

```yaml
ls_specific_settings:
  <language>:
    ls_path: "/path/to/language-server"
```

--------------------------------

### Create Context

Source: https://oraios.github.io/serena/02-usage/020_running.html

Create a new Serena context with a specified name.

```bash
serena context create my-custom-context

```
Tokens:
Raw