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.

refactor(cli): one missing-binary error for every wrap command (#4122)

Tejas Chopra2c2357ad342d
diff --git a/headroom/cli/wrap.py b/headroom/cli/wrap.py
index be1886852..58615a45c 100644
--- a/headroom/cli/wrap.py
+++ b/headroom/cli/wrap.py
@@ -1165,6 +1165,42 @@ _code_memory_scope_option = click.option(
)
+def _legacy_code_memory_options(command: Any) -> Any:
+ """Hidden pre-``--code-memory`` flags, still accepted by claude/codex/grok."""
+ for decorator in (
+ click.option(
+ "--no-serena",
+ is_flag=True,
+ hidden=True,
+ help="Deprecated: use --code-memory none. Register no code-memory MCP.",
+ ),
+ click.option(
+ "--serena",
+ is_flag=True,
+ hidden=True,
+ help="Deprecated: use --code-memory serena. Force the Serena MCP compressor on.",
+ ),
+ click.option(
+ "--no-tokensave",
+ is_flag=True,
+ hidden=True,
+ help="Deprecated and ignored: tokensave was retired; Serena is the default code memory.",
+ ),
+ ):
+ command = decorator(command)
+ return command
+
+
+def _require_binary(*names: str, install_hint: str) -> str:
+ """Return the first of ``names`` on PATH, or fail with how to install it."""
+ for name in names:
+ found = shutil.which(name)
+ if found:
+ return found
+ shown = f"'{names[0]}'" + "".join(f" (or '{name}')" for name in names[1:])
+ raise click.ClickException(f"{shown} not found in PATH.\n{install_hint}")
+
+
# Hook-command markers Headroom manages in Claude settings.json. unwrap drops
# any hook entry whose command contains one of these. (Retired rtk / lean-ctx
# hooks are removed separately, by
@@ -5838,24 +5874,7 @@ def _detect_inbound_anthropic_upstream(port: int) -> str | None:
)
@_code_memory_option
@_code_memory_scope_option
- "--no-tokensave",
- is_flag=True,
- hidden=True,
- help="Deprecated and ignored: tokensave was retired; Serena is the default code memory.",
-)
- "--serena",
- is_flag=True,
- hidden=True,
- help="Deprecated: use --code-memory serena. Force the Serena MCP compressor on.",
-)
- "--no-serena",
- is_flag=True,
- hidden=True,
- help="Deprecated: use --code-memory none. Register no code-memory MCP.",
-)
+@_legacy_code_memory_options
@click.option(
"--code-graph",
is_flag=True,
@@ -5955,11 +5974,9 @@ def claude(
if prepare_only:
return
- claude_bin = shutil.which("claude")
- if not claude_bin:
- click.echo("Error: 'claude' not found in PATH.")
- click.echo("Install Claude Code: https://docs.anthropic.com/en/docs/claude-code")
- raise SystemExit(1)
+ claude_bin = _require_binary(
+ "claude", install_hint="Install Claude Code: https://docs.anthropic.com/en/docs/claude-code"
+ )
# Validate --tool-search up front so a typo fails before we start the proxy.
if tool_search is not None:
@@ -6553,14 +6570,13 @@ def copilot(
explicitly with GITHUB_COPILOT_API_URL (the override flows through to upstream).
See TESTING-copilot-subscription.md for details.
"""
- copilot_bin = shutil.which("copilot")
- if not copilot_bin:
- click.echo("Error: 'copilot' not found in PATH.")
- click.echo(
+ copilot_bin = _require_binary(
+ "copilot",
+ install_hint=(
"Install GitHub Copilot CLI: "
"https://docs.github.com/en/copilot/how-tos/copilot-cli/set-up-copilot-cli/install-copilot-cli"
- )
- raise SystemExit(1)
+ ),
+ )
explicit_subscription = subscription
effective_backend = backend or os.environ.get("HEADROOM_BACKEND")
@@ -7162,11 +7178,9 @@ def _run_codex_wrap(
)
return
- codex_bin = shutil.which("codex")
- if not codex_bin:
- click.echo("Error: 'codex' not found in PATH.")
- click.echo("Install Codex CLI: npm install -g @openai/codex")
- raise SystemExit(1)
+ codex_bin = _require_binary(
+ "codex", install_hint="Install Codex CLI: npm install -g @openai/codex"
+ )
active_codex_home = _codex_home_dir()
_offer_dangling_codex_recovery(active_codex_home)
@@ -7226,24 +7240,7 @@ def _run_codex_wrap(
help="Skip headroom MCP server registration (compression markers will be unactionable)",
)
@_code_memory_option
- "--no-tokensave",
- is_flag=True,
- hidden=True,
- help="Deprecated and ignored: tokensave was retired; Serena is the default code memory.",
-)
- "--serena",
- is_flag=True,
- hidden=True,
- help="Deprecated: use --code-memory serena. Force the Serena MCP compressor on.",
-)
- "--no-serena",
- is_flag=True,
- hidden=True,
- help="Deprecated: use --code-memory none. Register no code-memory MCP.",
-)
+@_legacy_code_memory_options
@click.option(
"--code-graph",
is_flag=True,
@@ -7374,11 +7371,7 @@ def aider(
if prepare_only:
return
- aider_bin = shutil.which("aider")
- if not aider_bin:
- click.echo("Error: 'aider' not found in PATH.")
- click.echo("Install aider: pip install aider-chat")
- raise SystemExit(1)
+ aider_bin = _require_binary("aider", install_hint="Install aider: pip install aider-chat")
env, env_vars_display = _build_aider_launch_env(
port, os.environ, project=_project_name_from_cwd()
@@ -7445,11 +7438,9 @@ def vibe(
if prepare_only:
return
- vibe_bin = shutil.which("vibe")
- if not vibe_bin:
- click.echo("Error: 'vibe' not found in PATH.")
- click.echo("Install Mistral Vibe: https://github.com/mistralai/mistral-vibe")
- raise SystemExit(1)
+ vibe_bin = _require_binary(
+ "vibe", install_hint="Install Mistral Vibe: https://github.com/mistralai/mistral-vibe"
+ )
env, env_vars_display = _build_mistral_vibe_launch_env(
port, os.environ, project=_project_name_from_cwd()
@@ -7524,11 +7515,9 @@ def kimi(
if prepare_only:
return
- kimi_bin = shutil.which("kimi") or shutil.which("kimi-cli")
- if not kimi_bin:
- click.echo("Error: 'kimi' (or 'kimi-cli') not found in PATH.")
- click.echo("Install Kimi CLI: https://github.com/MoonshotAI/kimi-cli")
- raise SystemExit(1)
+ kimi_bin = _require_binary(
+ "kimi", "kimi-cli", install_hint="Install Kimi CLI: https://github.com/MoonshotAI/kimi-cli"
+ )
project = _project_name_from_cwd()
env, env_vars_display = _build_kimi_launch_env(port, os.environ, project=project)
@@ -7573,24 +7562,7 @@ def kimi(
@proxy_port_option()
@click.option("--no-mcp", is_flag=True, help="Skip headroom MCP server registration")
@_code_memory_option
- "--no-tokensave",
- is_flag=True,
- hidden=True,
- help="Deprecated and ignored: tokensave was retired; Serena is the default code memory.",
-)
- "--serena",
- is_flag=True,
- hidden=True,
- help="Deprecated: use --code-memory serena. Force the Serena MCP compressor on.",
-)
- "--no-serena",
- is_flag=True,
- hidden=True,
- help="Deprecated: use --code-memory none. Register no code-memory MCP.",
-)
+@_legacy_code_memory_options
@click.option(
"--code-graph",
is_flag=True,
@@ -7663,11 +7635,9 @@ def grok(
if prepare_only:
return
- grok_bin = shutil.which("grok")
- if not grok_bin:
- click.echo("Error: 'grok' not found in PATH.")
- click.echo("Install Grok CLI: https://docs.x.ai/docs/grok-cli")
- raise SystemExit(1)
+ grok_bin = _require_binary(
+ "grok", install_hint="Install Grok CLI: https://docs.x.ai/docs/grok-cli"
+ )
env, env_vars_display = _build_grok_launch_env(
port, os.environ, project=_project_name_from_cwd()
@@ -8462,11 +8432,9 @@ def opencode(
# config without launching, so it is exempt.
opencode_bin: str | None = None
if not prepare_only:
- opencode_bin = shutil.which("opencode")
- if not opencode_bin:
- click.echo("Error: 'opencode' not found in PATH.")
- click.echo("Install OpenCode: https://opencode.ai")
- raise SystemExit(1)
+ opencode_bin = _require_binary(
+ "opencode", install_hint="Install OpenCode: https://opencode.ai"
+ )
# Likewise refuse a reused proxy that cannot honor --openai-api-url before
# touching OpenCode's config or registering a client marker; the same check
@@ -8970,11 +8938,9 @@ def omp(
_inject_omp_models_override(port, _project_name_from_cwd())
return
- omp_bin = shutil.which("omp")
- if not omp_bin:
- click.echo("Error: 'omp' not found in PATH.")
- click.echo("Install Oh My Pi: npm install -g @oh-my-pi/pi-coding-agent")
- raise SystemExit(1)
+ omp_bin = _require_binary(
+ "omp", install_hint="Install Oh My Pi: npm install -g @oh-my-pi/pi-coding-agent"
+ )
env, env_vars_display = _build_omp_launch_env(
port, os.environ, project=_project_name_from_cwd()
@@ -9199,11 +9165,7 @@ def _make_registry_command(target: WrapTarget) -> click.Command:
if prepare_only:
return
- tool_bin = shutil.which(target.binary)
- if not tool_bin:
- click.echo(f"Error: '{target.binary}' not found in PATH.")
- click.echo(target.install_hint)
- raise SystemExit(1)
+ tool_bin = _require_binary(target.binary, install_hint=target.install_hint)
# Exported before proxy startup so _start_proxy forwards it as --mode;
# an explicit HEADROOM_MODE always wins.
diff --git a/tests/test_cli/test_wrap_helpers.py b/tests/test_cli/test_wrap_helpers.py
index 5b5f961da..973584e5b 100644
--- a/tests/test_cli/test_wrap_helpers.py
+++ b/tests/test_cli/test_wrap_helpers.py
@@ -1145,3 +1145,33 @@ def test_no_proxy_does_not_create_startup_lock(monkeypatch: pytest.MonkeyPatch)
assert wrap_mod._ensure_proxy(8787, True) == (None, 8787)
assert entered is False
+
+
+ ("argv", "expected"),
+ [
+ (
+ ["wrap", "aider"],
+ "Error: 'aider' not found in PATH.\nInstall aider: pip install aider-chat",
+ ),
+ (["wrap", "goose"], "Error: 'goose' not found in PATH."),
+ (["wrap", "kimi"], "Error: 'kimi' (or 'kimi-cli') not found in PATH."),
+ ],
+)
+def test_missing_binary_error_goes_to_stderr_only(
+ monkeypatch: pytest.MonkeyPatch, tmp_path: Path, argv: list[str], expected: str
+) -> None:
+ """The missing-binary error is a ClickException on stderr; stdout stays empty."""
+ monkeypatch.chdir(tmp_path)
+ monkeypatch.setattr(wrap_mod.shutil, "which", lambda name: None)
+
+ def no_proxy(*args: Any, **kwargs: Any) -> None:
+ raise AssertionError("a missing binary must fail before any proxy start")
+
+ monkeypatch.setattr(wrap_mod, "_ensure_proxy", no_proxy)
+
+ result = CliRunner().invoke(main, argv)
+
+ assert result.exit_code == 1
+ assert result.stdout == ""
+ assert result.stderr.startswith(expected)