Serena w. multiple LLMs

[tomelgato]

Im using Serena with Claude, love it. Now i started to integrate Codex / Gemini CLI into the project for code review. Memories etc set up, everything looks good.

The big Q is how to run serena. One serena server for all (started by OS not by client) with multiple clients open or the usual client starts server setup where i assume i have to quit code, open codex,... to avoid having multiple serenas (if that is even possible) accessing the same files. Or... ???
P.S. concurrent access by the clients is excluded via memories to avoid 2 clients editing the same codebase

I did not find info regarding that. Would appreciate some hints :)

[tomelgato]

Does Serena support having the same project activated by multiple clients?

[opcode81]

When using HTTP transport, the supported mode of operation is: all clients working on the same project.
The server is stateful and can only have one project activated at the same time.
So if that's your use case, you can synchronise access to the project by using a single HTTP-based Serena server.

If you want to work on multiple projects in your various clients, then using stdio mode with the server being spawned by the respective client is the way to go.

[tomelgato]

Could i start the server via Code and the other clients connect to this started server? If HTTP based it should work, no? Or is it better to start it outside of the client for this use?

With different projects open concurrently i would do other Serenas on different Hostports, correct?

Web Dashboard has no option to set port? Afaiu it uses a higher port when the def port is already used, but can it be set to a fixed one?

[MischaPanch]

The http server must be started by yourself, outside the client. That's the case for all MCP servers, not just Serena

[devnix]

@MischaPanch I think that the sentry-spotlight mcp server launches an HTTP server only if it's required.

I have a similar pain point with multiple LLMs or even launching two or three different claude sessions, just to keep three different conversations (they are not working at the same time, just different contexts), and having three LSP instances initializing and indexing sometimes creates a brutal CPU/RAM hog. Even PHPStorm will load its own MCP instance for the AI Assistant.

A very welcome approach, in my opinion, would be to check if there's a running instance of Serena in the same project, and connect to it maybe via proxying from stdio to http (I've still never done an MCP, so I can't evaluate the difficulty or practicality of implementation details).

[tomelgato]

@devnix @MischaPanch

I ended up with a dockerized Serena where i bind mount my projects. Beside the 1 project at a time limitation i can access the projects from all my LLMs (partly running on my machine direct, partly in docker containers too). Works quite well, every LLM needs to activate the project to get its own token (?), its not enough just to access Serena in the hope the already active project can be accessed.
I did modify the Serena system-prompt, modes and context to implement a basic routing for LLM specific things. Like this my Claude main LLM is delegating audit tasks to gemini cli and codex cli which use the project memories to interact with Claude.

So right now im quite happy with that solution, it could be improved with some sort of prompts/context/modes based on LLM client, but it is not really necessary

[devnix]

Hi @tomelgato @MischaPanch!

Tired of risking having to hard reboot my computer if I just launch two or more Claude Code instances, I've vibed a bash script that acts as a proxy.

If there's no instance running, it creates one. If it exists one, it connects to it. serena-mcp.sh will start a new instance, while serena-mcp.sh status will tell you if the server is running and how many clients are connected to the server:

Serena server: RUNNING (port 9121)
Connected clients: 3
Server PID: 932229
Log file: /home/devnix/.serena/server-9121.log

Serena server: STOPPED
Connected clients: 0
Log file: /home/devnix/.serena/server-9121.log

Here is the configuration and the script, if it helps anyone and serves as inspiration for the maintainers!

// .mcp.json
"serena": {
    "type": "stdio",
    "command": "./etc/serena/serena-mcp.sh"
}

#!/usr/bin/env bash
# =============================================================================
# Serena MCP Singleton Wrapper
# =============================================================================
#
# This script acts as a stdio-to-HTTP bridge for the Serena MCP server.
# It implements a singleton pattern so that multiple Claude Code sessions
# share a single Serena server instance, saving RAM (~500MB-2GB per instance).
#
# How it works:
#   1. Claude Code launches this script as a stdio MCP server (via .mcp.json)
#   2. The script checks if a Serena HTTP server is already running
#   3. If not, it starts one in the background on the configured port
#   4. It bridges stdio <-> HTTP using mcp-proxy
#   5. When the last Claude Code session disconnects, the server auto-stops
#
# Client tracking:
#   Each running wrapper registers its PID in ~/.serena/clients-PORT/.
#   On exit (trap), it unregisters. When the last client unregisters,
#   the Serena server process is killed automatically.
#
# Requirements: uvx (from uv), curl, flock
# Env vars: SERENA_PORT (default: 9121)
# =============================================================================
set -euo pipefail

PORT="${SERENA_PORT:-9121}"
PROJECT_PATH="$(cd "$(dirname "$0")/../.." && pwd)"
LOG="${HOME}/.serena/server-${PORT}.log"
PIDFILE="${HOME}/.serena/server-${PORT}.pid"
LOCKFILE="${HOME}/.serena/server-${PORT}.lock"
CLIENTS_DIR="${HOME}/.serena/clients-${PORT}"
CLIENT_ID="$$"
PROXY_PID=""

# --- Shared functions --------------------------------------------------------

# Serena's MCP HTTP mode has no /health endpoint. We probe /mcp with a POST
# and check the HTTP status code. Any HTTP response (even 4xx) confirms the
# server is listening. Only a connection failure (status 000) means it's down.
is_running() {
    local code
    code=$(curl -s --connect-timeout 2 --max-time 3 -o /dev/null -w "%{http_code}" \
        "http://127.0.0.1:${PORT}/mcp" \
        -X POST -H "Content-Type: application/json" \
        -d '{"jsonrpc":"2.0","method":"ping","id":1}' 2>/dev/null)
    [ "$code" != "000" ]
}

# --- Subcommands -------------------------------------------------------------

# Stops the Serena server and cleans up all client tracking files.
cmd_stop() {
    if [ -f "$PIDFILE" ]; then
        kill "$(cat "$PIDFILE")" 2>/dev/null || true
        rm -f "$PIDFILE"
        rm -rf "$CLIENTS_DIR"
        echo "Serena server stopped."
    else
        echo "No Serena server found."
    fi
}

# Tails the Serena server log file.
cmd_logs() {
    if [ -f "$LOG" ]; then
        exec tail -f "$LOG"
    else
        echo "No log file found at $LOG" >&2
        exit 1
    fi
}

# Shows the server status and connected client count.
cmd_status() {
    if is_running; then
        echo "Serena server: RUNNING (port ${PORT})"
    else
        echo "Serena server: STOPPED"
    fi

    if [ -d "$CLIENTS_DIR" ]; then
        local alive=0
        local pid
        local f
        shopt -s nullglob
        for f in "$CLIENTS_DIR"/*; do
            pid=$(basename "$f")
            if kill -0 "$pid" 2>/dev/null; then
                alive=$((alive + 1))
            fi
        done
        shopt -u nullglob
        echo "Connected clients: ${alive}"
    else
        echo "Connected clients: 0"
    fi

    if [ -f "$PIDFILE" ]; then
        echo "Server PID: $(cat "$PIDFILE")"
    fi
    echo "Log file: $LOG"
}

# Prints usage information.
cmd_help() {
    cat <<EOF
Serena MCP Singleton Wrapper

Usage: $(basename "$0") [COMMAND]

Commands:
  (none)    Start/connect to the shared Serena MCP server (default)
            Used automatically by Claude Code via .mcp.json
  stop      Stop the Serena server and clean up client tracking
  logs      Tail the Serena server log (follows new output)
  status    Show server status and connected client count
  help      Show this help message

Environment variables:
  SERENA_PORT   Port for the Serena HTTP server (default: 9121)

Examples:
  ./etc/serena/serena-mcp.sh             # connect (or start + connect)
  ./etc/serena/serena-mcp.sh status      # check if running
  ./etc/serena/serena-mcp.sh logs        # watch server logs
  ./etc/serena/serena-mcp.sh stop        # force stop server
  SERENA_PORT=9200 ./etc/serena/serena-mcp.sh   # use custom port
EOF
}

# --- Handle subcommands before entering connect mode -------------------------

case "${1:-}" in
    stop)        cmd_stop;   exit 0 ;;
    logs)        cmd_logs;   exit 0 ;;
    status)      cmd_status; exit 0 ;;
    help|--help) cmd_help;   exit 0 ;;
    "")          ;; # default: connect mode (below)
    *)           cmd_help >&2; exit 1 ;;
esac

# --- Connect mode (default) -------------------------------------------------

# Runs when this wrapper exits (session end, SIGINT, SIGTERM).
# Unregisters this client and stops the server if no clients remain.
cleanup() {
    if [ -n "$PROXY_PID" ]; then
        kill "$PROXY_PID" 2>/dev/null || true
        wait "$PROXY_PID" 2>/dev/null || true
    fi

    rm -f "${CLIENTS_DIR}/${CLIENT_ID}"

    local remaining
    remaining=$(find "$CLIENTS_DIR" -type f 2>/dev/null | wc -l | tr -d '[:space:]')
    if [ "$remaining" -eq 0 ]; then
        if [ -f "$PIDFILE" ]; then
            kill "$(cat "$PIDFILE")" 2>/dev/null || true
            rm -f "$PIDFILE"
        fi
        rmdir "$CLIENTS_DIR" 2>/dev/null || true
    fi
}
trap cleanup EXIT INT TERM

# Clean up stale client files from previous crashes (PIDs that no longer exist)
mkdir -p "$CLIENTS_DIR"
shopt -s nullglob
for f in "$CLIENTS_DIR"/*; do
    pid=$(basename "$f")
    if ! kill -0 "$pid" 2>/dev/null; then
        rm -f "$f"
    fi
done
shopt -u nullglob

# Register this session as an active client
touch "${CLIENTS_DIR}/${CLIENT_ID}"

# Start the Serena HTTP server if not already running.
# flock ensures only one session starts the server when multiple sessions
# connect concurrently, preventing orphaned server processes.
mkdir -p "$(dirname "$LOG")"
exec 200>"$LOCKFILE"
flock -x 200

if ! is_running; then
    if [ -f "$PIDFILE" ]; then
        kill "$(cat "$PIDFILE")" 2>/dev/null || true
        rm -f "$PIDFILE"
    fi

    uvx --from git+https://github.com/oraios/serena serena \
        start-mcp-server \
        --transport streamable-http \
        --port "${PORT}" \
        --host 127.0.0.1 \
        --context claude-code \
        --project "${PROJECT_PATH}" \
        >> "$LOG" 2>&1 &

    echo "$!" > "$PIDFILE"

    # Wait up to 30s for server readiness while holding the lock,
    # so concurrent sessions block until the server is confirmed ready.
    SERVER_PID=$(cat "$PIDFILE")
    for (( i = 0; i < 60; i++ )); do
        is_running && break
        if ! kill -0 "$SERVER_PID" 2>/dev/null; then
            echo "ERROR: Serena process exited early. Check $LOG" >&2
            exit 1
        fi
        sleep 0.5
    done

    if ! is_running; then
        echo "ERROR: Serena failed to start. Check $LOG" >&2
        exit 1
    fi
fi

flock -u 200
exec 200>&-

# Bridge stdio <-> HTTP. We intentionally avoid `exec` here so that bash
# stays alive and the EXIT trap fires when the session ends.
# The explicit `<&0` is required because bash redirects stdin from /dev/null
# for background processes in non-interactive scripts.
uvx mcp-proxy --log-level ERROR --transport streamablehttp "http://127.0.0.1:${PORT}/mcp" <&0 2>>"$LOG" &
PROXY_PID=$!
wait "$PROXY_PID"