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(learn): add agy (Antigravity CLI) as an analysis backend (#3939)

Trîggered4ba231ab3d51
diff --git a/headroom/cli/learn.py b/headroom/cli/learn.py
index 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_in
from ..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 message
try:
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 None
diff --git a/headroom/learn/analyzer.py b/headroom/learn/analyzer.py
index 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 subscription
users 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 model
2. 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 model
valid = ", ".join(name for name, _, _ in _CLI_BACKENDS)
@@ -180,7 +201,7 @@ def _detect_default_model() -> str:
# 3. Auto-detect installed CLI tools
for 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 genuine
hangs 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 + digest
hard_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 None
cmd = shim_cmd
try:
- 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.py
index 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.py
index 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.md
index b0e423ba3..657dae18d 100644
--- a/wiki/learn.md
+++ b/wiki/learn.md
@@ -218,7 +218,17 @@ export HEADROOM_LEARN_CLI=codex
headroom 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