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(wrap): reduce-at-source — SAFE quiet-CLI env defaults for the launched agent (#2548)

Tejas Choprac990cfb8037e
diff --git a/headroom/cli/wrap.py b/headroom/cli/wrap.py
index 5c5f37a79..06de0cc87 100644
--- a/headroom/cli/wrap.py
+++ b/headroom/cli/wrap.py
@@ -308,6 +308,54 @@ def _configure_tool_search_env(env: dict[str, str], flag_value: str | None) -> s
_TOOL_SEARCH_FALSY = {"false", "0", "no", "off"}
+# Reduce-at-source: CLI tools pad tool_result output with progress bars, pager
+# framing, funding/telemetry banners, and version nags — all zero-signal tokens
+# the agent never acts on. Setting conservative, SAFE env defaults in the
+# launched agent's environment makes those tools emit less AT THE SOURCE, so the
+# proxy never has to strip them. Only knobs that can't hide diffs, errors,
+# summaries, or search results are set here (no blanket --silent/--quiet).
+# Opt out entirely with HEADROOM_WRAP_QUIET=0 (or false/no/off).
+_QUIET_CLI_ENV = "HEADROOM_WRAP_QUIET"
+_QUIET_CLI_FALSY = {"0", "false", "no", "off"}
+# name -> value, injected only when the user has not already set it.
+_QUIET_CLI_DEFAULTS: dict[str, str] = {
+ "GIT_PAGER": "cat", # never page (keeps full content, drops pager framing)
+ "PIP_QUIET": "1", # drop "Requirement already satisfied"/download chatter
+ "PIP_DISABLE_PIP_VERSION_CHECK": "1", # drop the "new pip available" nag
+ "npm_config_fund": "false", # drop the funding banner
+ "npm_config_audit": "false", # drop the audit summary (not a security scan here)
+ "npm_config_progress": "false", # drop the install progress bar
+}
+
+
+def _quiet_cli_enabled() -> bool:
+ """Quiet-CLI source defaults are on unless HEADROOM_WRAP_QUIET is falsy."""
+ return os.environ.get(_QUIET_CLI_ENV, "").strip().lower() not in _QUIET_CLI_FALSY
+
+
+def _configure_quiet_cli_env(env: dict[str, str]) -> list[str]:
+ """Inject SAFE quiet-CLI defaults into ``env`` in place; return names set.
+
+ No-op when ``HEADROOM_WRAP_QUIET`` is falsy. A value the user already set
+ always wins (defaults are only filled when absent). ``PYTEST_ADDOPTS`` is
+ *augmented* with ``-q`` rather than clobbered, so an existing value survives.
+ Nothing RISKY (anything that could suppress diffs/errors/summaries/search
+ output) is ever set here.
+ """
+ if not _quiet_cli_enabled():
+ return []
+ written: list[str] = []
+ for name, value in _QUIET_CLI_DEFAULTS.items():
+ if name not in env:
+ env[name] = value
+ written.append(name)
+ existing = env.get("PYTEST_ADDOPTS", "")
+ if "-q" not in existing.split():
+ env["PYTEST_ADDOPTS"] = f"{existing} -q".strip()
+ written.append("PYTEST_ADDOPTS")
+ return written
+
+
def _resolved_tool_search_mode(flag_value: str | None) -> str:
"""Predict the ``ENABLE_TOOL_SEARCH`` value the launched process will get.
@@ -4461,10 +4509,19 @@ def _launch_tool(
if configure_launch is not None:
args, env, env_vars_display = configure_launch(actual_port, args, env, env_vars_display)
+ # Reduce-at-source: fill in SAFE quiet-CLI env defaults for the launched
+ # agent (git/npm/pip/pytest emit less noise), unless the user opted out.
+ # Applies to every wrapped tool since they all launch through here.
+ _quiet_written = _configure_quiet_cli_env(env)
+
click.echo()
click.echo(f" Launching {tool_label} (API routed through Headroom)...")
for var in env_vars_display:
click.echo(f" {var}")
+ if _quiet_written:
+ click.echo(
+ f" Quiet CLI defaults: {', '.join(_quiet_written)} (opt out: {_QUIET_CLI_ENV}=0)"
+ )
if args:
click.echo(f" Extra args: {' '.join(args)}")
_print_telemetry_notice()
diff --git a/tests/test_wrap_quiet_cli.py b/tests/test_wrap_quiet_cli.py
new file mode 100644
index 000000000..0380916cb
--- /dev/null
+++ b/tests/test_wrap_quiet_cli.py
@@ -0,0 +1,60 @@
+"""`headroom wrap` reduce-at-source: SAFE quiet-CLI env defaults for the launched
+agent. They fill in only when the user hasn't set the value, augment (never
+clobber) PYTEST_ADDOPTS, and are fully opt-out via HEADROOM_WRAP_QUIET."""
+
+from __future__ import annotations
+
+from headroom.cli.wrap import _configure_quiet_cli_env, _quiet_cli_enabled
+
+
+def test_defaults_injected_into_empty_env(monkeypatch) -> None:
+ monkeypatch.delenv("HEADROOM_WRAP_QUIET", raising=False)
+ env: dict[str, str] = {}
+ written = _configure_quiet_cli_env(env)
+ assert env["GIT_PAGER"] == "cat"
+ assert env["PIP_QUIET"] == "1"
+ assert env["PIP_DISABLE_PIP_VERSION_CHECK"] == "1"
+ assert env["npm_config_fund"] == "false"
+ assert env["npm_config_audit"] == "false"
+ assert env["npm_config_progress"] == "false"
+ assert env["PYTEST_ADDOPTS"] == "-q"
+ assert "GIT_PAGER" in written and "PYTEST_ADDOPTS" in written
+
+
+def test_user_value_always_wins(monkeypatch) -> None:
+ monkeypatch.delenv("HEADROOM_WRAP_QUIET", raising=False)
+ env = {"GIT_PAGER": "less -R", "PIP_QUIET": "0"}
+ written = _configure_quiet_cli_env(env)
+ assert env["GIT_PAGER"] == "less -R" # untouched
+ assert env["PIP_QUIET"] == "0" # untouched
+ assert "GIT_PAGER" not in written and "PIP_QUIET" not in written
+ # ...but absent ones are still filled.
+ assert env["npm_config_fund"] == "false"
+
+
+def test_pytest_addopts_augmented_not_clobbered(monkeypatch) -> None:
+ monkeypatch.delenv("HEADROOM_WRAP_QUIET", raising=False)
+ env = {"PYTEST_ADDOPTS": "-p no:cacheprovider"}
+ _configure_quiet_cli_env(env)
+ assert env["PYTEST_ADDOPTS"] == "-p no:cacheprovider -q" # preserved + augmented
+ # already-quiet stays as-is (no duplicate -q)
+ env2 = {"PYTEST_ADDOPTS": "-q --tb=short"}
+ written = _configure_quiet_cli_env(env2)
+ assert env2["PYTEST_ADDOPTS"] == "-q --tb=short"
+ assert "PYTEST_ADDOPTS" not in written
+
+
+def test_opt_out_disables_injection(monkeypatch) -> None:
+ for off in ("0", "false", "no", "OFF"):
+ monkeypatch.setenv("HEADROOM_WRAP_QUIET", off)
+ assert _quiet_cli_enabled() is False
+ env: dict[str, str] = {}
+ assert _configure_quiet_cli_env(env) == []
+ assert env == {} # nothing injected
+
+
+def test_enabled_by_default_and_on_truthy(monkeypatch) -> None:
+ monkeypatch.delenv("HEADROOM_WRAP_QUIET", raising=False)
+ assert _quiet_cli_enabled() is True
+ monkeypatch.setenv("HEADROOM_WRAP_QUIET", "1")
+ assert _quiet_cli_enabled() is True