fix(cli): document that code-aware compression is enabled by default (#4616)

## Description

`headroom proxy --help` says code-aware (AST) compression is off by
default, but the proxy turns it on when no flag is passed. With no
`--code-aware`/`--no-code-aware` flag and `HEADROOM_CODE_AWARE_ENABLED`
unset, `headroom/cli/proxy.py` resolves
`os.environ.get("HEADROOM_CODE_AWARE_ENABLED", "1")` to enabled. That
default came in on purpose with the coding-profile posture (#1893).
`test_code_aware_enabled_defaults_true`, the argparse server path
(`_get_env_bool(..., True)`) and the code-compression docs all treat it
as on. So the behavior is correct and the help text is wrong. The wrong
text matters because it makes `--code-aware` look like the only way to
turn AST compression on, so users don't notice it is already rewriting
code until they read the startup banner.

`headroom install apply --help` repeats the same claim ("Default:
disabled, matching `headroom proxy`"). When the flag is omitted, the
planner adds no argument, so the persistent runtime gets the proxy
default, which is enabled.

This PR changes only the descriptions. The runtime default stays as it
is.

Closes #4604

## Type of Change

- [x] Bug fix (non-breaking change that fixes an issue)

## Changes Made

- `headroom/cli/proxy.py`: the `--code-aware/--no-code-aware` help now
reads `Default: enabled. Disable with --no-code-aware or
HEADROOM_CODE_AWARE_ENABLED=0.` The resolution comment said both
"default off" and "Default ON"; it now gives step 3 as default ON.
- `headroom/cli/install.py`: the `install apply
--code-aware/--no-code-aware` help now reads `Default: enabled, matching
headroom proxy`.
- `tests/test_cli_proxy_env.py`: new parametrized regression test that
checks the `--code-aware` option help on `proxy` and `install apply`
documents the enabled default. Both cases fail on `main` and pass with
this change.
- Out of scope: `docs/content/docs/proxy.mdx` has the same stale
"disabled"/"off" wording in two table rows. I left it out to keep this
PR to the CLI help and can follow up separately.

## Testing

- [x] Unit tests pass (`pytest`)
- [x] Linting passes (`ruff check .`)
- [x] Type checking passes (`mypy headroom`)
- [x] New tests added for new functionality
- [x] Manual testing performed

Lint and type checks ran on the changed files only. Commands are below.

### Test Output

```text
$ .venv/bin/python -m pytest tests/test_cli_proxy_env.py -q -p no:cacheprovider -o addopts=
87 passed, 1 skipped in 11.89s

# same new test against the unmodified headroom/ sources
$ .venv/bin/python -m pytest tests/test_cli_proxy_env.py -q -p no:cacheprovider -o addopts= -k help_documents
FAILED tests/test_cli_proxy_env.py::TestCLIProxyEnvVars::test_code_aware_help_documents_enabled_default[path0]
FAILED tests/test_cli_proxy_env.py::TestCLIProxyEnvVars::test_code_aware_help_documents_enabled_default[path1]
2 failed, 86 deselected in 0.76s

$ .venv/bin/ruff check headroom/cli/proxy.py headroom/cli/install.py tests/test_cli_proxy_env.py
All checks passed!
$ .venv/bin/ruff format --check headroom/cli/proxy.py headroom/cli/install.py tests/test_cli_proxy_env.py
3 files already formatted
$ .venv/bin/mypy headroom/cli/proxy.py headroom/cli/install.py --ignore-missing-imports
Success: no issues found in 2 source files
```

## Real Behavior Proof

- Environment: Ubuntu 26.04 x86_64, Python 3.12, offline, no provider
- Exact command / steps: `headroom proxy --help | grep -A4 --
--code-aware` and `headroom install apply --help | grep -A4 --
--code-aware`, run once on unmodified `main` and once with this change.
On both trees I also resolved the default with
`HEADROOM_CODE_AWARE_ENABLED` unset: `env -u HEADROOM_CODE_AWARE_ENABLED
python -c ...` invokes `headroom proxy` through Click's `CliRunner` with
`run_server` and the proxy-extras check patched out, then prints
`config.code_aware_enabled`.
- Observed result: Before, on `main`:
  ```text
--code-aware / --no-code-aware Enable/disable AST-based code
compression.
                                  Requires the optional tree-sitter
dependency: pip install headroom-ai[code].
                                  Default: disabled. Env:
HEADROOM_CODE_AWARE_ENABLED=1 to enable.
--code-aware / --no-code-aware Enable/disable AST-based code compression
in
                                  the persistent runtime. Requires the
optional tree-sitter dependency: pip install
                                  headroom-ai[code]. Default: disabled,
                                  matching `headroom proxy`.
  exit 0 code_aware_enabled = True
  ```
  After, with this change:
  ```text
--code-aware / --no-code-aware Enable/disable AST-based code
compression.
                                  Requires the optional tree-sitter
dependency: pip install headroom-ai[code].
Default: enabled. Disable with --no-code-
aware or HEADROOM_CODE_AWARE_ENABLED=0.
--code-aware / --no-code-aware Enable/disable AST-based code compression
in
                                  the persistent runtime. Requires the
optional tree-sitter dependency: pip install
                                  headroom-ai[code]. Default: enabled,
                                  matching `headroom proxy`.
  exit 0 code_aware_enabled = True
  ```
The resolved default is `True` on both trees. Only the help text
changed, and it now matches the behavior.
- Not tested: starting a real `headroom proxy` and reading its
`Code-Aware:` startup banner, because this environment lacks the full
`[proxy]` extra (`mcp`). Also not tested: live provider traffic and an
actual `headroom install apply` deployment.

## Runtime Rollout Safety

- Rollout-managed feature(s): none; this changes help text and a code
comment only
- Minimum rollout channel: none needed; no runtime code path changes
- Stable/default behavior changed: no; code-aware still defaults to
enabled, exactly as before
- Kill switch / disable path: unchanged; `--no-code-aware` or
`HEADROOM_CODE_AWARE_ENABLED=0`
- Unsafe override required: no
- Qualification impact: none; no compression, routing or config
resolution logic touched
- Rollback path: revert this commit

## Review Readiness

- [x] I have performed a self-review
- [x] This PR is ready for human review

🤖 Generated with [Claude Code](https://claude.com/claude-code)

<!-- devin-review-badge-begin -->

---

<a href="https://app.devin.ai/review/headroomlabs-ai/headroom/pull/4616"
target="_blank"><picture><source media="(prefers-color-scheme: dark)"
srcset="https://static.devin.ai/assets/gh-devin-review-dark.svg?v=4"><img
src="https://static.devin.ai/assets/gh-devin-review-light.svg?v=4"
alt="Devin Review"></picture></a>
<!-- devin-review-badge-end -->
This commit is contained in:
Ryrenz
2026-11-03 16:59:19 -06:00
committed by GitHub
parent 038af599e1
commit affd17c5fd
3 changed files with 17 additions and 6 deletions
+1 -1
View File
@@ -908,7 +908,7 @@ def _echo_installed(manifest: DeploymentManifest, *, prefix: str = "Installed pe
help=(
"Enable/disable AST-based code compression in the persistent runtime. "
"Requires the optional tree-sitter dependency: pip install headroom-ai[code]. "
"Default: disabled, matching `headroom proxy`."
"Default: enabled, matching `headroom proxy`."
),
)
@click.option(
+5 -5
View File
@@ -800,7 +800,8 @@ def dashboard(port: int, no_open: bool) -> None:
help=(
"Enable/disable AST-based code compression. Requires the optional "
"tree-sitter dependency: pip install headroom-ai[code]. "
"Default: disabled. Env: HEADROOM_CODE_AWARE_ENABLED=1 to enable."
"Default: enabled. Disable with --no-code-aware or "
"HEADROOM_CODE_AWARE_ENABLED=0."
),
)
@click.option(
@@ -1569,10 +1570,9 @@ def proxy(
# Code-aware compression resolution:
# 1. Explicit --code-aware / --no-code-aware always wins.
# 2. Otherwise read HEADROOM_CODE_AWARE_ENABLED (truthy = on).
# 3. Otherwise default off — matches the prior cli/proxy.py behavior so
# existing users see no change unless they opt in.
# Default ON (coding posture; consistent with the argparse server path).
# Degrades gracefully to a no-op when tree-sitter isn't installed.
# 3. Otherwise default ON (coding posture; consistent with the argparse
# server path). Degrades gracefully to a no-op when tree-sitter
# isn't installed.
code_aware_enabled=(
bool(code_aware_flag)
if code_aware_flag is not None
+11
View File
@@ -564,6 +564,17 @@ class TestCLIProxyEnvVars:
assert result.exit_code == 0, result.output
assert captured_config["config"].code_aware_enabled is True
@pytest.mark.parametrize("path", [["proxy"], ["install", "apply"]])
def test_code_aware_help_documents_enabled_default(self, path):
"""--code-aware help must describe the default it resolves to (ON)."""
cmd = main
for name in path:
cmd = cmd.commands[name]
option = next(p for p in cmd.params if "--code-aware" in p.opts)
assert "Default: enabled" in option.help
assert "Default: disabled" not in option.help
def test_code_aware_enabled_from_cli_flag(self, runner):
"""--code-aware should enable code-aware compression in the wrapper."""
captured_config = {}