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.

feat(cli): add `wrap openclaude` for OpenClaude CLI (#1416)

Ben Younes541500811fa4
diff --git a/headroom/cli/wrap.py b/headroom/cli/wrap.py
index 7f54b570a..a794542bb 100644
--- a/headroom/cli/wrap.py
+++ b/headroom/cli/wrap.py
@@ -5,6 +5,7 @@ Usage:
headroom wrap copilot -- --model ... # Start proxy + launch GitHub Copilot CLI
headroom wrap codex # Start proxy + OpenAI Codex CLI
headroom wrap aider # Start proxy + aider
+ headroom wrap openclaude # Start proxy + OpenClaude
headroom wrap vibe # Start proxy + Mistral Vibe
headroom wrap cursor # Start proxy + print Cursor config instructions
headroom wrap openclaw # Install + configure OpenClaw plugin
@@ -174,7 +175,6 @@ _WRAP_PROXY_TIMEOUT_ENV = "HEADROOM_WRAP_PROXY_TIMEOUT"
_WRAP_PROXY_TIMEOUT_DEFAULT_SECONDS = 45
_WRAP_PROXY_TIMEOUT_ML_DEFAULT_SECONDS = 90
_WRAP_PROXY_TIMEOUT_ML_MODULES = ("torch", "sentence_transformers", "spacy")
-
# Issue #746: Claude Code disables on-demand tool loading (deferral) when
# ANTHROPIC_BASE_URL is a custom host and ENABLE_TOOL_SEARCH is unset, which
# inflates the local context window by tens of K tokens. Setting the env var
@@ -197,6 +197,7 @@ _CONTEXT_1M_SUFFIX = "[1m]"
# Only used when no model is otherwise selected (no ANTHROPIC_MODEL set). The
# current default Opus; the suffix logic preserves any model the user did set.
_DEFAULT_1M_MODEL = "claude-opus-4-8"
+_OPENCLAUDE_INSTRUCTIONS_FILE = "CONVENTIONS.md"
def _resolve_1m_model(current: str | None) -> str:
@@ -3835,6 +3836,7 @@ def wrap() -> None:
headroom wrap codex # OpenAI Codex CLI
headroom wrap copilot -- --model claude-sonnet-4-20250514
headroom wrap aider # Aider
+ headroom wrap openclaude # OpenClaude
headroom wrap vibe # Mistral Vibe
headroom wrap cursor # Cursor (prints config instructions)
headroom wrap cline # Cline (VS Code; prints config instructions)
@@ -5135,6 +5137,108 @@ def aider(
)
+# =============================================================================
+# OpenClaude
+# =============================================================================
+
+
[email protected](context_settings={"ignore_unknown_options": True})
[email protected]("--port", "-p", default=8787, type=int, help="Proxy port (default: 8787)")
+ "--no-context-tool",
+ "--no-rtk",
+ "no_rtk",
+ is_flag=True,
+ help="Skip CLI context-tool setup",
+)
+ "--code-graph",
+ is_flag=True,
+ help="Enable code graph indexing via codebase-memory-mcp (optional)",
+)
[email protected]("--no-proxy", is_flag=True, help="Skip proxy startup (use existing proxy)")
[email protected]("--learn", is_flag=True, help="Enable live traffic learning")
[email protected]("--memory", is_flag=True, help="Enable persistent cross-session memory")
+ "--backend", default=None, help="API backend: 'anthropic', 'anyllm', 'litellm-vertex', etc."
+)
[email protected]("--anyllm-provider", default=None, help="Provider for any-llm backend")
[email protected]("--region", default=None, help="Cloud region for Bedrock/Vertex")
[email protected]("--verbose", "-v", is_flag=True, help="Verbose output")
[email protected]("--prepare-only", is_flag=True, hidden=True)
[email protected]("openclaude_args", nargs=-1, type=click.UNPROCESSED)
+def openclaude(
+ port: int,
+ no_rtk: bool,
+ code_graph: bool,
+ no_proxy: bool,
+ learn: bool,
+ memory: bool,
+ backend: str | None,
+ anyllm_provider: str | None,
+ region: str | None,
+ verbose: bool,
+ prepare_only: bool,
+ openclaude_args: tuple,
+) -> None:
+ """Launch OpenClaude through Headroom proxy.
+
+ \b
+ OpenClaude is a prose-format coding CLI (like Aider / Cline); it speaks
+ OpenAI- and Anthropic-compatible HTTP, so wrap routes both base URLs
+ through the local proxy — same env shape as `wrap aider`.
+
+ \b
+ Examples:
+ headroom wrap openclaude # Start proxy + openclaude
+ headroom wrap openclaude -- --model gpt-4o # Pass args to openclaude
+ headroom wrap openclaude --no-context-tool # Skip CLI context-tool setup
+ """
+ openclaude_instructions: Path | None = (
+ Path.cwd() / _OPENCLAUDE_INSTRUCTIONS_FILE if not no_rtk else None
+ )
+ if not no_rtk:
+ _setup_context_tool_for_agent(
+ agent="openclaude",
+ agent_display="OpenClaude",
+ marker_path=openclaude_instructions,
+ on_rtk_ready=lambda _rtk: _inject_rtk_instructions(
+ cast(Path, openclaude_instructions), verbose=verbose
+ ),
+ verbose=verbose,
+ )
+
+ if prepare_only:
+ return
+
+ openclaude_bin = shutil.which("openclaude")
+ if not openclaude_bin:
+ click.echo("Error: 'openclaude' not found in PATH.")
+ click.echo("Install OpenClaude before running `headroom wrap openclaude`.")
+ raise SystemExit(1)
+
+ env, env_vars_display = _build_aider_launch_env(
+ port, os.environ, project=_project_name_from_cwd()
+ )
+
+ _launch_tool(
+ binary=openclaude_bin,
+ args=openclaude_args,
+ env=env,
+ port=port,
+ no_proxy=no_proxy,
+ tool_label="OPENCLAUDE",
+ env_vars_display=env_vars_display,
+ learn=learn,
+ memory=memory,
+ agent_type="openclaude",
+ code_graph=code_graph,
+ backend=backend,
+ anyllm_provider=anyllm_provider,
+ region=region,
+ )
+
+
# =============================================================================
# Mistral Vibe
# =============================================================================
diff --git a/tests/test_cli/test_wrap_openclaude.py b/tests/test_cli/test_wrap_openclaude.py
new file mode 100644
index 000000000..6234fcba6
--- /dev/null
+++ b/tests/test_cli/test_wrap_openclaude.py
@@ -0,0 +1,111 @@
+"""Tests for `headroom wrap openclaude` command (issue #1411)."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from unittest.mock import patch
+from urllib.parse import quote
+
+import pytest
+from click.testing import CliRunner
+
+import headroom.cli.wrap as wrap_cli
+from headroom.cli.main import main
+
+OPENCLAUDE_BINARY = "openclaude"
+OPENCLAUDE_INSTRUCTIONS_FILE = "CONVENTIONS.md"
+OPENCLAUDE_MODEL_ARG = "gpt-4o"
+RTK_BINARY = "rtk"
+UTF8_ENCODING = "utf-8"
+WINDOWS_DEFAULT_TEXT_ENCODING = "cp1252"
+
+
+def _expected_project_prefix() -> str:
+ return f"/p/{quote(Path.cwd().name, safe='')}"
+
+
+def runner() -> CliRunner:
+ return CliRunner()
+
+
+def test_wrap_openclaude_routes_proxy_envs(
+ runner: CliRunner, tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+ monkeypatch.chdir(tmp_path)
+ captured: dict[str, object] = {}
+
+ def fake_launch_tool(**kwargs): # noqa: ANN003
+ captured.update(kwargs)
+
+ with patch("headroom.cli.wrap.shutil.which", return_value=OPENCLAUDE_BINARY):
+ with patch("headroom.cli.wrap._launch_tool", side_effect=fake_launch_tool):
+ result = runner.invoke(
+ main,
+ ["wrap", "openclaude", "--no-rtk", "--", "--model", OPENCLAUDE_MODEL_ARG],
+ )
+
+ assert result.exit_code == 0, result.output
+ env = captured["env"]
+ assert isinstance(env, dict)
+ prefix = _expected_project_prefix()
+ assert env["OPENAI_API_BASE"] == f"http://127.0.0.1:8787{prefix}/v1"
+ assert env["ANTHROPIC_BASE_URL"] == f"http://127.0.0.1:8787{prefix}"
+ assert captured["tool_label"] == "OPENCLAUDE"
+ assert captured["agent_type"] == "openclaude"
+ assert captured["args"] == ("--model", OPENCLAUDE_MODEL_ARG)
+
+
+def test_wrap_openclaude_default_rtk_injects_instructions(
+ runner: CliRunner, tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+ monkeypatch.chdir(tmp_path)
+ original_write_text = Path.write_text
+
+ def write_text_with_windows_default(
+ self: Path,
+ data: str,
+ encoding: str | None = None,
+ errors: str | None = None,
+ newline: str | None = None,
+ ) -> int:
+ if encoding is None:
+ encoded = data.encode(WINDOWS_DEFAULT_TEXT_ENCODING, errors=errors or "strict")
+ self.write_bytes(encoded)
+ return len(data)
+ return original_write_text(
+ self,
+ data,
+ encoding=encoding,
+ errors=errors,
+ newline=newline,
+ )
+
+ def fake_launch_tool(**_kwargs): # noqa: ANN003
+ return None
+
+ with patch("headroom.cli.wrap.shutil.which", return_value=OPENCLAUDE_BINARY):
+ with patch("headroom.cli.wrap._ensure_rtk_binary", return_value=tmp_path / RTK_BINARY):
+ with patch.object(
+ Path,
+ "write_text",
+ autospec=True,
+ side_effect=write_text_with_windows_default,
+ ):
+ with patch("headroom.cli.wrap._launch_tool", side_effect=fake_launch_tool):
+ result = runner.invoke(main, ["wrap", "openclaude"])
+
+ instructions = tmp_path / OPENCLAUDE_INSTRUCTIONS_FILE
+ assert result.exit_code == 0, result.output
+ assert instructions.exists()
+ assert wrap_cli._RTK_MARKER in instructions.read_text(encoding=UTF8_ENCODING)
+
+
+def test_wrap_openclaude_missing_binary_errors(
+ runner: CliRunner, tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+ monkeypatch.chdir(tmp_path)
+ with patch("headroom.cli.wrap.shutil.which", return_value=None):
+ result = runner.invoke(main, ["wrap", "openclaude", "--no-rtk"])
+ assert result.exit_code == 1
+ assert "openclaude" in result.output.lower()