Skip to content

Compress tool outputs, logs, files, and RAG chunks before they reach the LLM. 20% fewer tokens for coding agents, 60-95% fewer tokens for JSON, same answers. Library, proxy, MCP server.

fix(serena): stop the Serena dashboard popup and make --no-serena actually disable Serena (#1003)

Tejas Chopra919379a8a173
diff --git a/headroom/cli/wrap.py b/headroom/cli/wrap.py
index 3041f4fa7..e29c0f099 100644
--- a/headroom/cli/wrap.py
+++ b/headroom/cli/wrap.py
@@ -648,6 +648,41 @@ def _remove_headroom_installed_serena_mcp(registrar: Any) -> str:
return "failed"
+def _disable_serena_mcp(registrar: Any, *, verbose: bool = False) -> None:
+ """Make ``--no-serena`` actively disable Serena, not merely skip adding it.
+
+ Serena is registered by default, so a prior ``headroom wrap`` persists a
+ ``serena`` entry into the agent's MCP config; the agent then keeps
+ launching Serena on startup. Just *skipping* registration on a later
+ ``--no-serena`` run leaves that stale entry in place — so the flag has to
+ remove the entry Headroom installed. A user-managed Serena (absent from
+ our ledger) is reported but left untouched.
+ """
+ if not registrar.detect():
+ if verbose:
+ click.echo(f" Serena MCP: {registrar.display_name} not detected — skipping")
+ return
+
+ if registrar.get_server("serena") is None:
+ if verbose:
+ click.echo(" Skipping Serena MCP (--no-serena)")
+ return
+
+ status = _remove_headroom_installed_serena_mcp(registrar)
+ if status == "removed":
+ click.echo(" Removed previously-installed Serena MCP (--no-serena)")
+ click.echo(f" restart {registrar.display_name} if it was already running")
+ elif status == "not_headroom_owned":
+ click.echo(
+ " Serena MCP is present but user-managed — leaving it in place "
+ "(--no-serena only removes entries Headroom installed)"
+ )
+ else: # "failed"
+ click.echo(
+ " Serena MCP: removal failed — remove the 'serena' entry from your MCP config manually"
+ )
+
+
_CBM_MCP_SERVER_NAME = "codebase-memory-mcp"
@@ -2769,8 +2804,10 @@ def claude(
from headroom.mcp_registry import ClaudeRegistrar
_setup_serena_mcp(ClaudeRegistrar(), context="claude-code", verbose=verbose)
- elif verbose:
- click.echo(" Skipping Serena MCP (--no-serena)")
+ else:
+ from headroom.mcp_registry import ClaudeRegistrar
+
+ _disable_serena_mcp(ClaudeRegistrar(), verbose=verbose)
if code_graph:
_setup_code_graph(verbose=verbose)
@@ -3264,8 +3301,10 @@ def codex(
from headroom.mcp_registry import CodexRegistrar
_setup_serena_mcp(CodexRegistrar(), context="codex", verbose=verbose, force=True)
- elif verbose:
- click.echo(" Skipping Serena MCP (--no-serena)")
+ else:
+ from headroom.mcp_registry import CodexRegistrar
+
+ _disable_serena_mcp(CodexRegistrar(), verbose=verbose)
# Setup memory MCP server for Codex (native tool integration)
if memory:
@@ -4397,6 +4436,21 @@ def unwrap_codex(port: int, no_stop_proxy: bool) -> None:
)
click.echo(f" Nothing to undo: {config_file} has no Headroom wrap markers.")
+ # Serena is written as its own [mcp_servers.serena] table with Headroom
+ # markers, separate from the provider block handled above — a "cleaned"
+ # restore leaves it behind. Remove it explicitly (only if we installed it),
+ # mirroring unwrap_claude. Runs after the restore so a backup-restore that
+ # already dropped Serena makes this a safe no-op.
+ from headroom.mcp_registry import CodexRegistrar
+
+ codex_registrar = CodexRegistrar()
+ if codex_registrar.detect():
+ serena_status = _remove_headroom_installed_serena_mcp(codex_registrar)
+ if serena_status == "removed":
+ click.echo(" Removed Headroom-installed Serena MCP server from Codex.")
+ elif serena_status == "failed":
+ click.echo(" Serena MCP server matched Headroom ledger but could not be removed.")
+
click.echo()
click.echo("✓ Codex is no longer routed through the Headroom proxy.")
if not no_stop_proxy and status != "noop":
diff --git a/headroom/mcp_registry/install.py b/headroom/mcp_registry/install.py
index dbdb6628c..71401051a 100644
--- a/headroom/mcp_registry/install.py
+++ b/headroom/mcp_registry/install.py
@@ -38,7 +38,18 @@ def build_headroom_spec(proxy_url: str = DEFAULT_PROXY_URL) -> ServerSpec:
def build_serena_spec(context: str) -> ServerSpec:
- """Construct the canonical Serena MCP server spec for an agent context."""
+ """Construct the canonical Serena MCP server spec for an agent context.
+
+ ``--open-web-dashboard False`` suppresses Serena's browser popup on
+ startup. Headroom installs Serena by default, so without this flag every
+ wrapped session opens the Serena dashboard tab even for users who never
+ opted into Serena or created a ``~/.serena/serena_config.yml``. The flag
+ overrides Serena's own config at startup (it sets
+ ``web_dashboard_open_on_launch=False``), so it works regardless of the
+ user's local config. The dashboard backend still runs and remains
+ reachable at http://localhost:24282/dashboard/ for anyone who wants it —
+ only the automatic browser-open is disabled.
+ """
return ServerSpec(
name="serena",
command="uvx",
@@ -50,6 +61,8 @@ def build_serena_spec(context: str) -> ServerSpec:
"--project-from-cwd",
"--context",
context,
+ "--open-web-dashboard",
+ "False",
),
)
diff --git a/tests/test_cli/test_serena_disable.py b/tests/test_cli/test_serena_disable.py
new file mode 100644
index 000000000..e10067ee3
--- /dev/null
+++ b/tests/test_cli/test_serena_disable.py
@@ -0,0 +1,125 @@
+"""`--no-serena` must actively disable Serena, not merely skip adding it.
+
+Serena is installed by default, so a prior `headroom wrap` persists a
+`serena` MCP entry and the agent keeps launching it (dashboard popup and
+all). These tests pin that a later `--no-serena` removes the entry Headroom
+installed, leaves a user-managed entry alone, and that Codex unwrap also
+removes Serena.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from unittest.mock import patch
+
+import pytest
+from click.testing import CliRunner
+
+from headroom.cli import wrap as wrap_cli
+from headroom.cli.main import main
+from headroom.mcp_registry import build_serena_spec
+from headroom.mcp_registry.base import ServerSpec
+from headroom.mcp_registry.ledger import record_install
+
+
+def runner() -> CliRunner:
+ return CliRunner()
+
+
+class _FakeRegistrar:
+ """Minimal registrar capturing unregister calls."""
+
+ def __init__(self, name: str, *, detected: bool = True, server: ServerSpec | None = None):
+ self.name = name
+ self.display_name = name.capitalize()
+ self._detected = detected
+ self._server = server
+ self.unregistered: list[str] = []
+
+ def detect(self) -> bool:
+ return self._detected
+
+ def get_server(self, server_name: str) -> ServerSpec | None:
+ return self._server if server_name == "serena" else None
+
+ def unregister_server(self, server_name: str) -> bool:
+ self.unregistered.append(server_name)
+ self._server = None
+ return True
+
+
+def test_disable_removes_headroom_installed_serena(
+ monkeypatch: pytest.MonkeyPatch, tmp_path: Path, capsys: pytest.CaptureFixture[str]
+) -> None:
+ monkeypatch.setenv("HEADROOM_WORKSPACE_DIR", str(tmp_path / ".headroom"))
+ spec = build_serena_spec("claude-code")
+ record_install("claude", spec) # ledger now proves Headroom owns it
+ registrar = _FakeRegistrar("claude", server=spec)
+
+ wrap_cli._disable_serena_mcp(registrar, verbose=True)
+
+ assert registrar.unregistered == ["serena"]
+ assert "Removed previously-installed Serena MCP" in capsys.readouterr().out
+
+
+def test_disable_preserves_user_managed_serena(
+ monkeypatch: pytest.MonkeyPatch, tmp_path: Path, capsys: pytest.CaptureFixture[str]
+) -> None:
+ monkeypatch.setenv("HEADROOM_WORKSPACE_DIR", str(tmp_path / ".headroom"))
+ # Present in the agent config but NOT in Headroom's ledger → user-owned.
+ user_spec = ServerSpec(name="serena", command="/usr/local/bin/custom-serena")
+ registrar = _FakeRegistrar("claude", server=user_spec)
+
+ wrap_cli._disable_serena_mcp(registrar, verbose=True)
+
+ assert registrar.unregistered == [] # never touch a user-managed entry
+ assert "user-managed" in capsys.readouterr().out
+
+
+def test_disable_noop_when_serena_absent(
+ monkeypatch: pytest.MonkeyPatch, tmp_path: Path, capsys: pytest.CaptureFixture[str]
+) -> None:
+ monkeypatch.setenv("HEADROOM_WORKSPACE_DIR", str(tmp_path / ".headroom"))
+ registrar = _FakeRegistrar("claude", server=None)
+
+ wrap_cli._disable_serena_mcp(registrar, verbose=True)
+
+ assert registrar.unregistered == []
+ assert "Skipping Serena MCP (--no-serena)" in capsys.readouterr().out
+
+
+def test_disable_noop_when_agent_not_detected(
+ monkeypatch: pytest.MonkeyPatch, tmp_path: Path
+) -> None:
+ monkeypatch.setenv("HEADROOM_WORKSPACE_DIR", str(tmp_path / ".headroom"))
+ spec = build_serena_spec("claude-code")
+ record_install("claude", spec)
+ registrar = _FakeRegistrar("claude", detected=False, server=spec)
+
+ wrap_cli._disable_serena_mcp(registrar, verbose=True)
+
+ assert registrar.unregistered == [] # not detected → leave everything alone
+
+
+def test_unwrap_codex_removes_headroom_installed_serena(
+ runner: CliRunner, monkeypatch: pytest.MonkeyPatch, tmp_path: Path
+) -> None:
+ monkeypatch.setenv("HEADROOM_WORKSPACE_DIR", str(tmp_path / ".headroom"))
+ spec = build_serena_spec("codex")
+ record_install("codex", spec)
+ registrar = _FakeRegistrar("codex", server=spec)
+
+ with (
+ patch("headroom.mcp_registry.CodexRegistrar", return_value=registrar),
+ patch(
+ "headroom.cli.wrap._restore_codex_provider_config",
+ return_value=("noop", tmp_path / "config.toml"),
+ ),
+ patch("headroom.cli.wrap._stop_local_proxy_for_unwrap"),
+ ):
+ result = runner.invoke(main, ["unwrap", "codex"])
+
+ assert result.exit_code == 0, result.output
+ assert registrar.unregistered == ["serena"]
+ assert "Removed Headroom-installed Serena MCP server from Codex" in result.output
diff --git a/tests/test_mcp_registry/test_install.py b/tests/test_mcp_registry/test_install.py
index 3bd97dacc..af5cfcd43 100644
--- a/tests/test_mcp_registry/test_install.py
+++ b/tests/test_mcp_registry/test_install.py
@@ -81,10 +81,22 @@ def test_build_serena_spec_uses_agent_context() -> None:
"--project-from-cwd",
"--context",
"codex",
+ "--open-web-dashboard",
+ "False",
)
assert spec.env == {}
+def test_build_serena_spec_disables_dashboard_popup_by_default() -> None:
+ # Headroom installs Serena by default; the dashboard browser tab must not
+ # auto-open. The flag overrides the user's serena_config.yml at startup,
+ # so this holds even when the user never created a Serena config.
+ for context in ("codex", "claude-code"):
+ spec = build_serena_spec(context)
+ idx = spec.args.index("--open-web-dashboard")
+ assert spec.args[idx + 1] == "False"
+
+
# ----------------------------------------------------------------------
# install_everywhere
# ----------------------------------------------------------------------