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.

docs(troubleshooting): document Windows Defender ast-grep-cli false positive + workarounds (#2200) (#2237)

Shubham Srivastava17d60dce1f3f
diff --git a/docs/content/docs/troubleshooting.mdx b/docs/content/docs/troubleshooting.mdx
index 04cf769b7..8136b609a 100644
--- a/docs/content/docs/troubleshooting.mdx
+++ b/docs/content/docs/troubleshooting.mdx
@@ -340,6 +340,41 @@ pip install "headroom-ai[code]"
pip install "headroom-ai[all]"
```
+### Windows: Defender blocks ast-grep-cli (sg.exe) during install
+
+**Symptom**: On Windows, `uv tool install "headroom-ai[all]"` (or `pip install`) fails while installing the `ast-grep-cli` wheel, and Windows Defender flags `sg.exe`:
+
+```text
+error: Failed to install: ast_grep_cli-0.44.1-py3-none-win_amd64.whl (ast-grep-cli==0.44.1)
+Caused by: failed to open file ...\ast_grep_cli-0.44.1.data\scripts\sg.exe:
+The operation did not complete successfully because the file contains a virus
+or potentially unwanted software. (os error 225)
+
+Threat: Trojan:Win64/Lazy!MTB
+```
+
+**Cause**: A known **false positive** in the upstream `ast-grep-cli` wheel's bundled `sg.exe` ([ast-grep/ast-grep#2799](https://github.com/ast-grep/ast-grep/issues/2799)), not a Headroom issue. `ast-grep` is a base dependency, so the block also affects the `[proxy]` extra. Headroom uses `ast-grep` only for optional AST-based Read-output outlining and **runs normally without it** — the only impact is the install-time quarantine.
+
+**Workarounds** (safest first):
+
+1. **Run the proxy in Docker** — no local wheel is installed, so Defender is never triggered. See [Docker install](/docs/docker-install); the image is `ghcr.io/headroomlabs-ai/headroom`.
+
+2. **Restore the file from quarantine and retry** — open **Windows Security → Virus & threat protection → Protection history**, select the `sg.exe` detection, choose **Restore**, then re-run the install command. This changes no persistent settings.
+
+3. **Add a temporary, scoped Defender exclusion during install** (last resort; requires an elevated PowerShell). Only do this if you accept excluding a *known false positive*, and remove the exclusion afterward:
+
+ ```powershell
+ # Scope the exclusion to uv's tools directory, install, then remove it
+ $uvTools = (uv tool dir)
+ Add-MpPreference -ExclusionPath $uvTools
+ uv tool install "headroom-ai[all]"
+ Remove-MpPreference -ExclusionPath $uvTools
+ ```
+
+ Do **not** disable Defender wholesale — keep the exclusion narrow and temporary.
+
+4. **Report the false positive to Microsoft** so a corrected signature ships for everyone: submit `sg.exe` at the [Microsoft Security Intelligence sample submission](https://www.microsoft.com/en-us/wdsi/filesubmission) page.
+
## Provider-Specific Issues
### OpenAI: Invalid API key