From 9cf4033fdf98ebec8e7a66c399170acd495d0a62 Mon Sep 17 00:00:00 2001 From: YeonGyu-Kim Date: Fri, 10 Apr 2026 01:42:43 +0900 Subject: [PATCH] =?UTF-8?q?docs:=20add=20Windows=20setup=20section=20(Git?= =?UTF-8?q?=20Bash/WSL=20prereqs)=20=E2=80=94=20ROADMAP=20#51?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Users were hitting: - bash: cargo: command not found (Rust not installed or not on PATH) - C:\... vs /c/... path confusion in Git Bash - MINGW64 prompt misread as broken install New '### Windows setup' section in README covers: 1. Install Rust via rustup.rs 2. Open Git Bash (MINGW64 is normal) 3. Verify cargo --version / run . ~/.cargo/env if missing 4. Use /c/Users/... paths 5. Clone + build + run steps WSL2 tip added for lower-friction alternative. ROADMAP #51 filed. --- README.md | 29 +++++++++++++++++++++++++++++ ROADMAP.md | 2 ++ 2 files changed, 31 insertions(+) diff --git a/README.md b/README.md index f64498c..7e261ac 100644 --- a/README.md +++ b/README.md @@ -67,6 +67,35 @@ export ANTHROPIC_API_KEY="sk-ant-..." > [!NOTE] > **Windows (PowerShell):** the binary is `claw.exe`, not `claw`. Use `.\target\debug\claw.exe` or run `cargo run -- prompt "say hello"` to skip the path lookup. +### Windows setup (Git Bash / WSL) + +If you are on Windows, the recommended shell is **Git Bash** (ships with Git for Windows) or **WSL**. Full sequence: + +1. **Install Rust** — download from and run the installer. Close and reopen the terminal when it finishes. +2. **Open Git Bash** — search for "Git Bash" in the Start menu (not PowerShell, not cmd). The prompt shows `MINGW64` — this is normal and expected, not a broken install. +3. **Verify Rust is on PATH:** + ```bash + cargo --version + ``` + If you see `bash: cargo: command not found`, run `. ~/.cargo/env` or restart Git Bash, then retry. +4. **Use bash-style paths** — in Git Bash, `C:\Users\you` becomes `/c/Users/you`: + ```bash + cd /c/Users/you/projects + ``` +5. **Clone and build:** + ```bash + git clone https://github.com/ultraworkers/claw-code + cd claw-code/rust + cargo build --workspace + ``` +6. **Run:** + ```bash + export ANTHROPIC_API_KEY="sk-ant-..." + ./target/debug/claw prompt "say hello" + ``` + +> **WSL tip:** WSL2 (`wsl --install` from an admin PowerShell) is the most friction-free Windows path — follow the Linux quick-start steps inside the WSL terminal. + > [!NOTE] > **Auth:** claw requires an **API key** (`ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, etc.) — Claude subscription login is not a supported auth path. diff --git a/ROADMAP.md b/ROADMAP.md index 3104fa8..9afc52c 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -526,3 +526,5 @@ Model name prefix now wins unconditionally over env-var presence. Regression tes 49. **Resumed slash command errors emitted as prose in `--output-format json` mode** — dogfooded 2026-04-09. `claw --output-format json --resume /commit` called `eprintln!()` and `exit(2)` directly, bypassing the JSON formatter. Both the slash-command parse-error path and the `run_resume_command` Err path now check `output_format` and emit `{"type":"error","error":"...","command":"..."}`. **Done at `da42421` 2026-04-09**. Source: gaebal-gajae ROADMAP #26 track; Jobdori dogfood. 50. **PowerShell tool is registered as `danger-full-access` — workspace-aware reads still require escalation** — dogfooded 2026-04-10. User running `workspace-write` session mode (tanishq_devil in #claw-code) had to use `danger-full-access` even for simple in-workspace reads via PowerShell (e.g. `Get-Content`). Root cause traced by gaebal-gajae: `PowerShell` tool spec is registered with `required_permission: PermissionMode::DangerFullAccess` (same as the `bash` tool in `mvp_tool_specs`), not with per-command workspace-awareness. Bash shell and PowerShell execute arbitrary commands, so blanket promotion to `danger-full-access` is conservative — but it over-escalates read-only in-workspace operations. Fix shape: (a) add command-level heuristic analysis to the PowerShell executor (read-only commands like `Get-Content`, `Get-ChildItem`, `Test-Path` that target paths inside CWD → `WorkspaceWrite` required; everything else → `DangerFullAccess`); (b) mirror the same workspace-path check that the bash executor uses; (c) add tests covering the permission boundary for PowerShell read vs write vs network commands. Note: the `bash` tool in `mvp_tool_specs` is also `DangerFullAccess` and has the same gap — both should be fixed together. Source: tanishq_devil in #claw-code 2026-04-10; root cause identified by gaebal-gajae. + +51. **Windows first-run onboarding missing: no explicit Rust + shell prerequisite branch** — dogfooded 2026-04-10 via #claw-code. User hit `bash: cargo: command not found`, `C:\...` vs `/c/...` path confusion in Git Bash, and misread `MINGW64` prompt as a broken MinGW install rather than normal Git Bash. Root cause: README/docs have no Windows-specific install path that says (1) install Rust first via rustup, (2) open Git Bash or WSL (not PowerShell or cmd), (3) use `/c/Users/...` style paths in bash, (4) then `cargo install claw-code`. Users can reach chat mode confusion before realizing claw was never installed. Fix shape: add a **Windows setup** section to README.md (or INSTALL.md) with explicit prerequisite steps, Git Bash vs WSL guidance, and a note that `MINGW64` in the prompt is expected and normal. Source: tanishq_devil in #claw-code 2026-04-10; traced by gaebal-gajae.