@@ -56,3 +56,22 @@ Search results can flood context. Use `ctx_execute(language: "shell", code: "gre
5656| ` ctx stats ` | Call the ` stats ` MCP tool and display the full output verbatim |
5757| ` ctx doctor ` | Call the ` doctor ` MCP tool, run the returned shell command, display as checklist |
5858| ` ctx upgrade ` | Call the ` upgrade ` MCP tool, run the returned shell command, display as checklist |
59+
60+ ## Windows notes
61+
62+ ** PowerShell cmdlets in shell scripts** — The sandbox executes scripts via bash. PowerShell
63+ cmdlets (` Format-List ` , ` Format-Table ` , ` Get-Culture ` , etc.) do not exist in bash and will fail
64+ with ` command not found ` . Wrap them with ` pwsh -NoProfile -Command "..." ` instead.
65+
66+ ** Relative paths** — The sandbox CWD is a temp directory, not your project root. Always convert
67+ any user-supplied path to an absolute path before passing it to ` rg ` , ` grep ` , or ` find ` .
68+ Ask the user to confirm the absolute path if it is not already known.
69+
70+ ** Windows drive letter paths** — The sandbox runs Git Bash / MSYS2, not WSL. Drive letters must
71+ use the MSYS2 convention, NOT the WSL convention:
72+ ` X:\path ` → ` /x/path ` (lowercase letter, no ` /mnt/ ` prefix).
73+ Never emit ` /mnt/<letter>/ ` prefixes regardless of which drive the project is on.
74+
75+ ** Always quote paths** — If a path contains spaces, bash splits it into separate arguments.
76+ Always wrap every path in double quotes: ` rg "symbol" "$REPO_ROOT/some dir/Source" ` .
77+ This applies to all tools: ` rg ` , ` grep ` , ` find ` , ` ls ` , etc.
0 commit comments