From a4a35ee2526cd7362214ef06534009b0860a574e Mon Sep 17 00:00:00 2001 From: project7 Date: Sat, 18 Jul 2026 08:35:44 +0900 Subject: [PATCH] [#1006] docs(install-windows): Bring the WSL2 guide to current setup parity Make docs/install-windows.md independently usable instead of deferring to the Mac guide, and align every command with the current code / the corrected install-mac.md (#1005). - Inline the full flow inside WSL2: install agent CLIs (Claude Code / Codex / Gemini CLI), authenticate, install QuadWork (verify via `npm list -g quadwork`, example 2.7.0), `quadwork init` / `start` / `stop`. - Cover first-run per-role backend + model selection (Agent Models step), worktree creation (project-head/dev/re1/re2), auto-answered Claude trust prompt, dashboard at http://127.0.0.1:8400, and clean shutdown via ~/.quadwork/server.pid. - Add a self-contained optional Discord/Telegram bridge note. - Keep only accurate WSL-specific limitations (caffeinate n/a, paths, VS Code WSL extension, shared localhost); Node aligned to 20+ (24 recommended). - Remove all "identical to the Mac guide / follow the Mac guide" pointers. Docs-only; no runtime code, tests, package versions, legacy migration implementation, or other documents touched. Co-Authored-By: Claude Opus 4.8 (1M context) --- docs/install-windows.md | 155 ++++++++++++++++++++++++++++++++++------ 1 file changed, 135 insertions(+), 20 deletions(-) diff --git a/docs/install-windows.md b/docs/install-windows.md index 9ff437a1..07915f15 100644 --- a/docs/install-windows.md +++ b/docs/install-windows.md @@ -1,13 +1,16 @@ # QuadWork — Windows Installation Guide (WSL2) -QuadWork requires a Unix environment (node-pty, lsof, shell). On Windows, use WSL2 (Windows Subsystem for Linux) to get a full Ubuntu environment. Once inside WSL2, the setup is identical to the Mac guide. +QuadWork requires a Unix environment (node-pty, a POSIX shell, git worktrees). +On Windows, run it inside **WSL2** (Windows Subsystem for Linux), which gives +you a full Ubuntu environment. This guide is self-contained — every command +runs **inside the WSL2 Ubuntu shell** unless it explicitly says PowerShell. --- ## Prerequisites - **Windows 10** (build 19041 or later) or **Windows 11** -- Administrator access (for WSL2 installation) +- Administrator access (for the one-time WSL2 installation) --- @@ -21,7 +24,7 @@ Open **PowerShell as Administrator** and run: wsl --install -d Ubuntu ``` -Restart your computer when prompted. After restart, Ubuntu will open and ask you to create a username and password. +Restart your computer when prompted. After restart, Ubuntu opens and asks you to create a username and password. --- @@ -33,15 +36,14 @@ Open PowerShell (or Windows Terminal) and run: wsl ``` -You're now in Ubuntu. All following steps happen inside this shell. +You're now in Ubuntu. **All following steps happen inside this shell.** --- ## Step 3: Install Prerequisites (Ubuntu/WSL2) -These replace the macOS-specific steps (Homebrew, Xcode) in the Mac guide. - -**Node.js 24** (via nvm): +**Node.js 20+** (24 recommended) via nvm — nvm keeps the global npm prefix +under `~/.nvm/`, so the `npm install -g` steps below work without `sudo`: ```bash curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh | bash source ~/.bashrc @@ -49,13 +51,13 @@ nvm install 24 nvm use 24 ``` -**System packages:** +**Git:** ```bash sudo apt-get update sudo apt-get install -y git ``` -**GitHub CLI:** +**GitHub CLI (`gh`):** ```bash curl -fsSL https://cli.github.com/packages/githubcli-archive-keyring.gpg | sudo dd of=/usr/share/keyrings/githubcli-archive-keyring.gpg sudo chmod go+r /usr/share/keyrings/githubcli-archive-keyring.gpg @@ -63,30 +65,139 @@ echo 'deb [arch=amd64 signed-by=/usr/share/keyrings/githubcli-archive-keyring.gp sudo apt-get update && sudo apt-get install -y gh ``` +Verify the toolchain: +```bash +node --version # 20 or newer +git --version +gh --version +``` + **Authenticate GitHub CLI:** ```bash gh auth login ``` -> **This is interactive** — the operator must complete the browser-based auth flow. +> **This is interactive** — the operator must complete the login flow. In WSL2 +> the flow either opens your Windows browser or prints a one-time code and URL +> to paste into it. Verify with `gh auth status` (expect +> `Logged in to github.com account `). + +--- + +## Step 4: Install AI Coding Agent CLIs + +Install one or more of the supported agent CLIs (all as global npm packages): + +```bash +# Claude Code (Anthropic) +npm install -g @anthropic-ai/claude-code + +# Codex CLI (OpenAI) +npm install -g @openai/codex + +# Gemini CLI (Google) — if using Gemini agents +npm install -g @google/gemini-cli +``` + +Each CLI needs a one-time interactive login — run it and complete the prompt +(the same browser/one-time-code pattern as `gh` above): + +```bash +claude # follow the login prompt +codex # follow the login prompt +gemini # follow the login prompt (only if using Gemini) +``` + +> **These are interactive steps.** Ask the operator to run each command and complete the login. + +--- + +## Step 5: Install QuadWork + +```bash +npm install -g quadwork@latest +``` + +Verify the install: +```bash +npm list -g quadwork +# You should see the installed version, e.g. quadwork@2.7.0 +``` + +> If you see `EACCES: permission denied` on the global install, your Node isn't +> nvm-managed. Re-do the nvm step in Step 3 (recommended), or run QuadWork +> without a global install via `npx quadwork@latest init` / `npx quadwork@latest start`. --- -## Step 4: Follow the Mac Guide (from "Install AI Coding Agents") +## Step 6: Initialize & Start + +Run the interactive setup wizard, then start the dashboard: -From here, the setup is identical. Follow **[docs/install-mac.md](install-mac.md)** starting from the **"Install AI Coding Agents"** section. +```bash +quadwork init # prompts for your first project (name, repo, working dir, backends) +quadwork start # starts the dashboard + agents on http://127.0.0.1:8400 +``` -This includes: -- Claude Code + Codex CLI -- CLI authentication -- `npm install -g quadwork@latest` -- `npx quadwork init` +`quadwork start` binds loopback (`127.0.0.1`) and opens the dashboard in your +browser. Create your first project from the dashboard at +`http://127.0.0.1:8400` (**"+ New Project"** or `/setup`) if you didn't during +`init`: + +- **Name / Repo (`owner/repo`) / Working directory** (absolute path to your repo clone). +- **Agent backends & models** — in the **Agent Models** step, choose a CLI + backend (**Claude Code**, **Codex**, or **Gemini CLI**) for each of the four + roles (Head, Dev, RE1, RE2), and optionally pick a specific model per role + (e.g. `opus` / `sonnet` for Claude, `gpt-5.4` / `gpt-5.6-*` for Codex, + `gemini-2.5-pro` / `gemini-2.5-flash` for Gemini). Leave a role on + **(CLI default)** to use the backend's own default model. + +QuadWork then creates a git worktree for each agent next to your repo +(`project-head/`, `project-dev/`, `project-re1/`, `project-re2/`) and seeds +`AGENTS.md` and `CLAUDE.md` into each. Claude Code's "Do you trust this +directory?" prompt is auto-answered when each agent's terminal starts — no +manual pre-trust step is required. --- ## Accessing the Dashboard -QuadWork runs on `http://127.0.0.1:8400` by default. WSL2 shares localhost with Windows automatically — open that URL in your Windows browser (Chrome, Edge, etc.) and it will connect. +QuadWork runs on `http://127.0.0.1:8400` by default. WSL2 shares `localhost` +with Windows automatically, so open that URL in your **Windows** browser +(Chrome, Edge, etc.) — no port forwarding needed. + +--- + +## Stopping & Restarting + +```bash +# Foreground: press Ctrl+C in the `quadwork start` terminal. +# From another WSL2 terminal: +quadwork stop + +# Restart +quadwork start +``` + +Both `Ctrl+C` and `quadwork stop` shut down cleanly (agent terminals, watchdog +timers, and any running chat bridges). `quadwork start` records its PID in +`~/.quadwork/server.pid`, which is how `quadwork stop` finds a running server. + +For persistent background operation, pm2 works the same as on Linux: +```bash +npm install -g pm2 +pm2 start "quadwork start" --name quadwork +pm2 save +``` + +--- + +## Optional: Discord / Telegram Bridge + +Bridges are built in and configured per-project from the dashboard: open the +project page and use the **Discord** or **Telegram** widget to enter your bot +token and channel/chat ID, then **Start**. Config is stored per-project in +`~/.quadwork/config.json`. --- @@ -94,7 +205,7 @@ QuadWork runs on `http://127.0.0.1:8400` by default. WSL2 shares localhost with | Feature | Behavior on WSL2 | |---------|-----------------| -| Keep Mac Awake | Not available (`caffeinate` is macOS-only) | +| Keep Mac Awake | Not applicable (`caffeinate` is macOS-only; nothing to stop on WSL2) | | File paths | `/home//` instead of `/Users//` | | VS Code | Install the "WSL" extension to edit files inside WSL2 | | Localhost | Shared with Windows automatically (no port forwarding needed) | @@ -103,4 +214,8 @@ QuadWork runs on `http://127.0.0.1:8400` by default. WSL2 shares localhost with ## For AI Agents -After WSL2 is installed by the operator: follow Steps 3–4 in this guide for prerequisites, then continue with `docs/install-mac.md` starting from the **"Install AI Coding Agents"** section. Do not run the macOS-specific prerequisite steps (Homebrew, Xcode) — those are already handled by Step 3 above. +WSL2 itself must be installed by the operator (Step 1, PowerShell as +Administrator). Once inside the WSL2 shell, run Steps 3–6 in order. Do not run +any macOS-specific prerequisites (Homebrew, Xcode) — Step 3 covers everything +needed on Ubuntu/WSL2. Authentication steps (`gh auth login`, `claude`, +`codex`, `gemini`) are interactive and must be completed by the operator.