QuadWork

<div align="center">

<img src="public/icon.png" alt="QuadWork" width="80" />

# QuadWork

### Your AI dev team while you sleep.

<p>
  <a href="https://quadwork.xyz"><strong>Website</strong></a> ·
  <a href="#-quick-start"><strong>Quick Start</strong></a> ·
  <a href="#-how-it-works"><strong>How it Works</strong></a> ·
  <a href="#-features"><strong>Features</strong></a> ·
  <a href="#-external-tools"><strong>Credits</strong></a>
</p>

<p>
  <a href="https://www.npmjs.com/package/quadwork"><img src="https://img.shields.io/npm/v/quadwork" alt="npm version" /></a>
  <a href="https://www.npmjs.com/package/quadwork"><img src="https://img.shields.io/npm/dm/quadwork" alt="npm downloads" /></a>
  <img src="https://img.shields.io/badge/platform-macOS%20%7C%20Linux-lightgrey" alt="platform" />
  <img src="https://img.shields.io/badge/runs-locally-00d4aa" alt="runs locally" />
  <img src="https://img.shields.io/badge/team-Head%20%C2%B7%20Dev%20%C2%B7%20RE1%20%C2%B7%20RE2-orange" alt="team: Head · Dev · RE1 · RE2" />
  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue" alt="MIT License" /></a>
</p>

</div>

---

## Installation Guides

Step-by-step guides for setting up QuadWork, designed for both humans and AI coding agents:

- **[Mac Installation](docs/install-mac.md)** — local setup on macOS
- **[Windows Installation](docs/install-windows.md)** — local setup via WSL2 (Windows Subsystem for Linux)
- **[VPS Installation](docs/install-vps.md)** — remote server (Hetzner/Ubuntu) with domain + SSL
- **[Troubleshooting](docs/troubleshooting.md)** — common issues and fixes
- **[Operator MCP](docs/operator-mcp.md)** — drive QuadWork from a Claude agent (`claude mcp add quadwork -- quadwork-mcp-operator --port 8400`)

> **For AI agents:** These guides contain complete step-by-step instructions. When your operator asks you to install or troubleshoot QuadWork, read the relevant guide and follow it.

## What is QuadWork?

**QuadWork** is a local-first, open-source automation framework that
orchestrates a collaborative team of four autonomous AI agents — **Head, Dev,
and two Reviewers** — to manage a complete, production-grade GitHub workflow.
By enforcing strict safety rails such as mandatory two-person independent code
reviews and branch protection, it allows solo founders and engineers to ship
code 24/7 through a reliable "Issue → Branch → PR → Merge" loop while
maintaining high code quality without manual oversight.

<video src="https://github.com/user-attachments/assets/d1f6f3d6-27de-4afb-9b58-9fe1f87cddb8" width="720" controls></video>

[▶ View Live Demo on YouTube](https://www.youtube.com/watch?v=Q0814uXjYoQ)

[🌐 Visit quadwork.xyz](https://quadwork.xyz)

### How QuadWork Orchestrates Your Workflow

```
Issue → Branch → PR → Review × 2 → Merge
  ↑                                    │
  └──────── next ticket ───────────────┘
```

Head creates issues and assigns them to Dev. Dev opens a PR. Reviewer 1
and Reviewer 2 each review independently — approve, request changes, or
veto. Dev iterates until both approve. Head merges and picks the next
ticket. The cycle repeats autonomously until the batch is complete.

### Core Value Proposition

- **Autonomous Reliability:** Runs overnight batches using a scheduled trigger, so you can wake up to a queue of successfully merged pull requests.
- **Multi-Agent Governance:** Unlike single-agent tools, QuadWork uses a system of checks and balances where agents must convince each other through code review before merging to `main`.
- **Privacy & Control:** Operates as a local Express server on your machine, managing your configured LLMs (Claude, OpenAI, Gemini) and GitHub CLI sessions without third-party proxying.
- **Complete Visibility:** Features a comprehensive 4-quadrant dashboard with real-time agent terminals, chat history, and progress tracking.

## Why QuadWork?

Manually reviewing every AI-generated PR is exhausting. Letting one AI agent
push straight to `main` is how you end up rolling back broken migrations at
2am. QuadWork solves this — you describe the work, kick off a batch, and come
back to merged PRs that were each reviewed twice before touching `main`.

## Who is QuadWork for?

- **Solo founders / indie hackers** who want to ship faster than they can review
- **Open-source maintainers** who get more PRs than they have hours to look at
- **Engineers** who want a team workflow without the overhead of hiring
- **Tinkerers** who've tried Claude Code / Codex and wished they had reviewers who pushed back

## ─ Quick Start

1. Install [Node.js 20+](https://nodejs.org) if you don't have it
2. On macOS, install [Homebrew](https://brew.sh):
   `/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"`
3. Open your terminal and run:

```bash
npx quadwork init
```

4. The wizard installs everything else and opens your dashboard.

That's it. The wizard handles GitHub CLI, AI tools, and
authentication — you just follow the 

... (truncated)