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.
Python agentaianthropicclaude-codecompressioncontext-engineeringcontext-windowcursorfastapilangchainllmmcpopenaiprompt-engineeringproxypythonragtoken-optimizationtokenstypescript
feat(learn): add agy (Antigravity CLI) as an analysis backend (#3939)
Trîggered4ba231ab3d51
diff --git a/headroom/cli/learn.py b/headroom/cli/learn.pyindex 4a469e45f..b3722184b 100644--- a/headroom/cli/learn.py+++ b/headroom/cli/learn.py@@ -161,7 +161,7 @@ def learn("""import os- from ..learn.analyzer import SessionAnalyzer, _detect_default_model+ from ..learn.analyzer import SessionAnalyzer, _detect_default_model, _require_agy_opt_infrom ..learn.registry import auto_detect_plugins, get_plugin# Flag-combination validation — reject contradictory/no-op combinations up@@ -202,7 +202,9 @@ def learn(# Resolve model early to fail fast with a clear messagetry:resolved_model = model or _detect_default_model()- except RuntimeError as e:+ if resolved_model == "agy-cli":+ _require_agy_opt_in()+ except (RuntimeError, ValueError) as e:click.echo(f"Error: {e}")raise SystemExit(1) from Nonediff --git a/headroom/learn/analyzer.py b/headroom/learn/analyzer.pyindex dc5075383..9ce974579 100644--- a/headroom/learn/analyzer.py+++ b/headroom/learn/analyzer.py@@ -8,7 +8,7 @@ structured recommendations for CLAUDE.md / MEMORY.md.Supports any LLM provider via LiteLLM: Anthropic, OpenAI, Google, Bedrock,Ollama, and 100+ others. Auto-detects the best available model from env vars.-Also supports CLI-based backends (claude, gemini, codex) for subscription+Also supports CLI-based backends (claude, gemini, codex, agy) for subscriptionusers without raw API keys."""@@ -92,8 +92,17 @@ _CLI_BACKENDS: list[tuple[str, str, list[str]]] = [),("gemini", "gemini-cli", ["gemini", "-p"]),("codex", "codex-cli", ["codex", "exec", "--skip-git-repo-check"]),+ # agy's -p takes the prompt as an argument, so stdin is only read as a+ # stream-json user event; the answer arrives in the final `result` event.+ ("agy", "agy-cli", ["agy", "--input-format", "stream-json", "--output-format", "stream-json"]),]+# agy has no flag that starts a zero-tool session (--sandbox still writes+# files, --mode plan still reads them), so transcript text could drive its+# tools under the user's permissions. It is never auto-detected and only runs+# when the user sets this env var to "1".+_AGY_UNSAFE_OPT_IN_ENV = "HEADROOM_LEARN_ALLOW_UNSAFE_AGY"+# Set of valid CLI model identifiers, derived from _CLI_BACKENDS._CLI_MODEL_IDS: set[str] = {model for _, model, _ in _CLI_BACKENDS}@@ -152,13 +161,23 @@ def _resolve_timeout_secs(env_var: str, default: int) -> int:return value+def _require_agy_opt_in() -> None:+ """Raise unless the user explicitly accepted agy's unsandboxed tool access."""+ if os.environ.get(_AGY_UNSAFE_OPT_IN_ENV) != "1":+ raise ValueError(+ "The agy backend cannot run without tool access, so session text could "+ "make it write files or run shell commands under your permissions. "+ f"Set {_AGY_UNSAFE_OPT_IN_ENV}=1 to accept this risk and use it anyway."+ )++def _detect_default_model() -> str:"""Pick the best available model based on API keys, env config, or CLI tools.Priority order:1. API key present → use corresponding LiteLLM model2. HEADROOM_LEARN_CLI env var → use specified CLI backend- 3. Auto-detect installed CLI tools (claude > gemini > codex)+ 3. Auto-detect installed CLI tools (claude > gemini > codex; agy is opt-in only)4. Raise RuntimeError with setup instructions"""# 1. API key detection (existing behavior)@@ -171,6 +190,8 @@ def _detect_default_model() -> str:if cli_override:for cli_name, model, _cmd in _CLI_BACKENDS:if cli_name == cli_override:+ if cli_name == "agy":+ _require_agy_opt_in()logger.info("HEADROOM_LEARN_CLI=%s — using %s CLI backend", cli_override, cli_name)return modelvalid = ", ".join(name for name, _, _ in _CLI_BACKENDS)@@ -180,7 +201,7 @@ def _detect_default_model() -> str:# 3. Auto-detect installed CLI toolsfor cli_name, model, _cmd in _CLI_BACKENDS:- if shutil.which(cli_name):+ if cli_name != "agy" and shutil.which(cli_name):logger.info("No API key found — auto-detected %s CLI as LLM backend", cli_name)return model@@ -189,8 +210,9 @@ def _detect_default_model() -> str:" export ANTHROPIC_API_KEY=sk-ant-... → uses claude-sonnet-4-6\n"" export OPENAI_API_KEY=sk-... → uses gpt-4o\n"" export GEMINI_API_KEY=... → uses gemini-flash-latest\n"- "Or set HEADROOM_LEARN_CLI to a coding agent CLI (claude, gemini, codex).\n"- "Or install one of those CLIs for auto-detection.\n"+ "Or set HEADROOM_LEARN_CLI to a coding agent CLI (claude, gemini, codex, agy).\n"+ " agy is never auto-detected and also needs HEADROOM_LEARN_ALLOW_UNSAFE_AGY=1.\n"+ "Or install claude, gemini, or codex for auto-detection.\n""Or specify a model directly: headroom learn --model <litellm-model-name>")@@ -715,6 +737,8 @@ def _call_cli_llm(--include-partial-messages (idle-timeout)gemini-cli → gemini -p (wall-clock timeout)codex-cli → codex exec (wall-clock timeout)+ agy-cli → agy --input-format stream-json --output-format stream-json+ (wall-clock timeout)The claude-cli path streams JSON events, letting the analyzer kill genuinehangs while letting long-but-active analyses run to completion.@@ -729,7 +753,8 @@ def _call_cli_llm(Parsed JSON recommendations from the CLI tool.Raises:- ValueError: If *model* is not a known CLI backend.+ ValueError: If *model* is not a known CLI backend, or is ``agy-cli``+ without the unsafe opt-in.RuntimeError: If the CLI is not installed, exits non-zero, or times out."""cmd: list[str] | None = None@@ -740,6 +765,13 @@ def _call_cli_llm(if cmd is None:raise ValueError(f"Unknown CLI model: {model}")+ if model == "agy-cli":+ _require_agy_opt_in()+ logger.warning(+ "agy-cli runs with tool access under your permissions; session text "+ "could trigger file writes or shell commands during analysis"+ )+prompt = _SYSTEM_PROMPT + "\n\n" + _USER_PROMPT_PREFIX + digesthard_cap = _resolve_timeout_secs("HEADROOM_LEARN_CLI_TIMEOUT_SECS", _CLI_TIMEOUT)@@ -749,10 +781,14 @@ def _call_cli_llm(cmd, prompt, hard_cap=hard_cap, idle_cap=idle_cap, on_progress=on_progress)+ stdin = prompt+ if model == "agy-cli":+ stdin = json.dumps({"event": "user", "message": {"content": prompt}}) + "\n"+try:result = run(cmd,- input=prompt,+ input=stdin,capture_output=True,text=True,timeout=hard_cap,@@ -766,7 +802,7 @@ def _call_cli_llm() from Nonecmd = shim_cmdtry:- result = run(cmd, input=prompt, capture_output=True, text=True, timeout=hard_cap)+ result = run(cmd, input=stdin, capture_output=True, text=True, timeout=hard_cap)except FileNotFoundError:raise RuntimeError(f"`{cmd[0]}` not found in PATH. Install it or use a different backend "@@ -787,8 +823,12 @@ def _call_cli_llm(if result.stderr and result.stderr.strip():logger.debug("CLI stderr (exit 0): %s", result.stderr[:_MAX_SNIPPET_LEN])+ output = result.stdout+ if model == "agy-cli":+ output = _agy_result_text(output)+try:- return _strip_fenced_json(result.stdout)+ return _strip_fenced_json(output)except json.JSONDecodeError as exc:stdout_snippet = _output_snippet(result.stdout or "")raise RuntimeError(@@ -975,6 +1015,19 @@ def _call_claude_cli_streaming() from exc+def _agy_result_text(stdout: str) -> str:+ """Return ``result.response`` from agy stream-json output, or "" if absent."""+ # Split on "\n" only: splitlines() also breaks on U+2028/U+2029, which JSON+ # allows unescaped inside strings, and would cut the result event apart.+ for line in reversed(stdout.split("\n")):+ event = _parse_stream_event(line)+ if event is not None and event.get("event") == "result":+ result = event.get("result")+ response = result.get("response") if isinstance(result, dict) else None+ return response if isinstance(response, str) else ""+ return ""++def _parse_stream_event(line: str) -> dict | None:"""Parse one line of claude-cli stream-json output, returning None on junk."""line = line.strip()diff --git a/tests/test_cli_learn.py b/tests/test_cli_learn.pyindex 012e318ff..f4341417a 100644--- a/tests/test_cli_learn.py+++ b/tests/test_cli_learn.py@@ -112,6 +112,38 @@ def test_learn_exits_cleanly_when_model_detection_fails(assert "Error: no model" in result.output+ ("args", "env"),+ [+ (["learn"], {"HEADROOM_LEARN_CLI": "agy"}),+ (["learn", "--model", "agy-cli"], {}),+ ],+)+def test_learn_agy_without_unsafe_opt_in_exits_cleanly(+ monkeypatch: pytest.MonkeyPatch, runner: CliRunner, args: list[str], env: dict[str, str]+) -> None:+ for var in (+ "ANTHROPIC_API_KEY",+ "OPENAI_API_KEY",+ "GEMINI_API_KEY",+ "HEADROOM_LEARN_CLI",+ "HEADROOM_LEARN_ALLOW_UNSAFE_AGY",+ ):+ monkeypatch.delenv(var, raising=False)+ for var, value in env.items():+ monkeypatch.setenv(var, value)+ monkeypatch.setattr(+ "headroom.learn.registry.auto_detect_plugins",+ lambda: pytest.fail("sessions must not be scanned without the agy opt-in"),+ )++ result = runner.invoke(main, args, catch_exceptions=False)++ assert result.exit_code == 1+ assert "Error:" in result.output+ assert "HEADROOM_LEARN_ALLOW_UNSAFE_AGY=1" in result.output++def test_learn_auto_agent_reports_no_detected_plugins(monkeypatch: pytest.MonkeyPatch, runner: CliRunner) -> None:diff --git a/tests/test_learn/test_analyzer.py b/tests/test_learn/test_analyzer.pyindex 7c8a4e11e..abd6b0e1c 100644--- a/tests/test_learn/test_analyzer.py+++ b/tests/test_learn/test_analyzer.py@@ -626,6 +626,29 @@ class TestDetectDefaultModel:)assert _detect_default_model() == "codex-cli"+ def test_cli_fallback_never_auto_detects_agy(self, monkeypatch):+ monkeypatch.delenv("ANTHROPIC_API_KEY", raising=False)+ monkeypatch.delenv("OPENAI_API_KEY", raising=False)+ monkeypatch.delenv("GEMINI_API_KEY", raising=False)+ monkeypatch.delenv("HEADROOM_LEARN_CLI", raising=False)+ monkeypatch.setenv("HEADROOM_LEARN_ALLOW_UNSAFE_AGY", "1")+ monkeypatch.setattr(+ "headroom.learn.analyzer.shutil.which",+ lambda name: f"/usr/bin/{name}" if name == "agy" else None,+ )+ with pytest.raises(RuntimeError, match="No LLM API key found"):+ _detect_default_model()++ def test_cli_fallback_prefers_existing_clis_over_agy(self, monkeypatch):+ monkeypatch.delenv("ANTHROPIC_API_KEY", raising=False)+ monkeypatch.delenv("OPENAI_API_KEY", raising=False)+ monkeypatch.delenv("GEMINI_API_KEY", raising=False)+ monkeypatch.setattr(+ "headroom.learn.analyzer.shutil.which",+ lambda name: f"/usr/bin/{name}" if name in ("codex", "agy") else None,+ )+ assert _detect_default_model() == "codex-cli"+def test_api_key_preferred_over_cli(self, monkeypatch):monkeypatch.setenv("ANTHROPIC_API_KEY", "sk-ant-test")monkeypatch.setattr(@@ -648,6 +671,23 @@ class TestDetectDefaultModel:monkeypatch.setenv("HEADROOM_LEARN_CLI", "codex")assert _detect_default_model() == "codex-cli"+ def test_env_var_selects_agy_with_unsafe_opt_in(self, monkeypatch):+ monkeypatch.delenv("ANTHROPIC_API_KEY", raising=False)+ monkeypatch.delenv("OPENAI_API_KEY", raising=False)+ monkeypatch.delenv("GEMINI_API_KEY", raising=False)+ monkeypatch.setenv("HEADROOM_LEARN_CLI", "agy")+ monkeypatch.setenv("HEADROOM_LEARN_ALLOW_UNSAFE_AGY", "1")+ assert _detect_default_model() == "agy-cli"++ def test_env_var_agy_without_unsafe_opt_in_raises(self, monkeypatch):+ monkeypatch.delenv("ANTHROPIC_API_KEY", raising=False)+ monkeypatch.delenv("OPENAI_API_KEY", raising=False)+ monkeypatch.delenv("GEMINI_API_KEY", raising=False)+ monkeypatch.delenv("HEADROOM_LEARN_ALLOW_UNSAFE_AGY", raising=False)+ monkeypatch.setenv("HEADROOM_LEARN_CLI", "agy")+ with pytest.raises(ValueError, match="HEADROOM_LEARN_ALLOW_UNSAFE_AGY=1"):+ _detect_default_model()+def test_env_var_invalid_raises(self, monkeypatch):monkeypatch.delenv("ANTHROPIC_API_KEY", raising=False)monkeypatch.delenv("OPENAI_API_KEY", raising=False)@@ -1031,6 +1071,64 @@ class TestCallCliLlm:cmd = mock_run.call_args[0][0]assert cmd == ["gemini", "-p"]+ @patch("headroom.learn.analyzer.subprocess.run")+ def test_agy_cli_sends_stream_json_and_parses_result_event(+ self, mock_run: MagicMock, monkeypatch+ ):+ monkeypatch.setenv("HEADROOM_LEARN_ALLOW_UNSAFE_AGY", "1")+ response = '```json\n{"context_file_rules": [], "memory_file_rules": []}\n```\n'+ mock_run.return_value = MagicMock(+ returncode=0,+ stdout="\n".join(+ [+ '{"event": "init", "init": {"permission_mode": "default"}}',+ '{"event": "step_update", "step_update": {"text_delta": "{"}}',+ json.dumps({"event": "result", "result": {"response": response}}),+ ]+ ),+ stderr="",+ )+ result = _call_cli_llm("test digest", "agy-cli")+ assert result == {"context_file_rules": [], "memory_file_rules": []}+ cmd = mock_run.call_args[0][0]+ assert cmd == ["agy", "--input-format", "stream-json", "--output-format", "stream-json"]+ sent = json.loads(mock_run.call_args.kwargs["input"])+ assert sent["event"] == "user"+ assert sent["message"]["content"].endswith("test digest")++ @patch("headroom.learn.analyzer.subprocess.run")+ def test_agy_cli_result_with_unicode_line_separator(self, mock_run: MagicMock, monkeypatch):+ monkeypatch.setenv("HEADROOM_LEARN_ALLOW_UNSAFE_AGY", "1")+ response = '{"context_file_rules": [], "memory_file_rules": [], "note": "a b"}'+ mock_run.return_value = MagicMock(+ returncode=0,+ stdout=json.dumps(+ {"event": "result", "result": {"response": response}}, ensure_ascii=False+ )+ + "\n",+ stderr="",+ )+ result = _call_cli_llm("test digest", "agy-cli")+ assert result["note"] == "a b"++ @patch("headroom.learn.analyzer.subprocess.run")+ def test_agy_cli_without_unsafe_opt_in_does_not_run(self, mock_run: MagicMock, monkeypatch):+ monkeypatch.delenv("HEADROOM_LEARN_ALLOW_UNSAFE_AGY", raising=False)+ with pytest.raises(ValueError, match="HEADROOM_LEARN_ALLOW_UNSAFE_AGY=1"):+ _call_cli_llm("test digest", "agy-cli")+ mock_run.assert_not_called()++ @patch("headroom.learn.analyzer.subprocess.run")+ def test_agy_cli_missing_result_event_raises(self, mock_run: MagicMock, monkeypatch):+ monkeypatch.setenv("HEADROOM_LEARN_ALLOW_UNSAFE_AGY", "1")+ mock_run.return_value = MagicMock(+ returncode=0,+ stdout='{"event": "init", "init": {}}\n',+ stderr="",+ )+ with pytest.raises(RuntimeError, match="unparseable output"):+ _call_cli_llm("test digest", "agy-cli")+@patch("headroom.learn.analyzer.subprocess.run")def test_codex_nonzero_exit_raises(self, mock_run: MagicMock):mock_run.return_value = MagicMock(diff --git a/wiki/learn.md b/wiki/learn.mdindex b0e423ba3..657dae18d 100644--- a/wiki/learn.md+++ b/wiki/learn.md@@ -218,7 +218,17 @@ export HEADROOM_LEARN_CLI=codexheadroom learn```-Valid values for `HEADROOM_LEARN_CLI`: `claude`, `gemini`, `codex`.+Valid values for `HEADROOM_LEARN_CLI`: `claude`, `gemini`, `codex`, `agy`.++`agy` (Antigravity CLI) is never auto-detected. It has no mode that starts a session without tools, so instructions embedded in analyzed session text could make it write files or run shell commands with your permissions. To use it anyway, opt in explicitly:++```bash+export HEADROOM_LEARN_CLI=agy+export HEADROOM_LEARN_ALLOW_UNSAFE_AGY=1+headroom learn+```++Without `HEADROOM_LEARN_ALLOW_UNSAFE_AGY=1`, selecting `agy` (via `HEADROOM_LEARN_CLI` or `--model agy-cli`) fails before any analysis runs.## Real-World Results