### 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 --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 with your actual secret key. The --project flag should point to your codebase root. ```bash uvx mcpo --port 8000 --api-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:/mcp`. ```bash serena start-mcp-server --transport streamable-http --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 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 -- ` 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 --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 --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 \Binaries\DotNET\UnrealBuildTool\UnrealBuildTool.exe -mode=GenerateClangDatabase -project=".uproject" Editor Win64 Development -OutputDir="" ``` -------------------------------- ### 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: : 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 ```