Skip to content

[#1006] docs(install-windows): Bring the WSL2 guide to current setup parity #1014

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
realproject7 merged 1 commit into from
Jul 17, 2026
Merged

[#1006] docs(install-windows): Bring the WSL2 guide to current setup parity #1014

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
155 changes: 135 additions & 20 deletions docs/install-windows.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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)

---

Expand All @@ -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.

---

Expand All @@ -33,68 +36,176 @@ 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
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
echo 'deb [arch=amd64 signed-by=/usr/share/keyrings/githubcli-archive-keyring.gpg] https://cli.github.com/packages stable main' | sudo tee /etc/apt/sources.list.d/github-cli.list
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 <username>`).

---

## 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`.

---

## Known Differences from Mac/Linux

| 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/<user>/` instead of `/Users/<user>/` |
| VS Code | Install the "WSL" extension to edit files inside WSL2 |
| Localhost | Shared with Windows automatically (no port forwarding needed) |
Expand All @@ -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.
Loading