<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 prompts. Subsequent runs are one
command: `npx quadwork start`.

## ─ How it Works

QuadWork runs a team of 4 AI agents on your local machine and enforces a
GitHub-native workflow on them:

| Agent | Role | What it does |
|-------|------|-------------|
| **Head** | Coordinator | Creates issues, assigns tasks, merges approved PRs |
| **Dev** | Builder | Writes code, opens PRs, addresses review feedback |
| **Reviewer1** | Reviewer | Independent code review with veto authority |
| **Reviewer2** | Reviewer | Independent code review with veto authority |

Every task follows the same cycle: **Issue → Branch → PR → 2 Reviews → Merge**.
Branch protection ensures no agent can skip the process.

### The full autonomous loop

```
You: "@head start a batch for feature X"
     │
     ▼
Head: creates issues + queue, asks you to kick off the batch
     │
     ▼ (you click "Start Trigger" in the Operator panel)
Head: assigns the first issue to Dev
     │
     ▼
Dev: opens a PR with code
     │
     ▼
Reviewer1 + Reviewer2: independent reviews
     │
     ▼ (both approve)
Head: merges, picks the next issue
     │
     └──── repeat overnight ────┐
                                │
                                ▼
                       You wake up to merged PRs
```

### A concrete example

1. You drop a batch of 5 related tickets into chat: `@head start 5 sub-tickets under #123`.
2. Head files the 5 issues on GitHub, writes them to `OVERNIGHT-QUEUE.md`, and asks you to click **Start Trigger**.
3. You click it, close the laptop, and sleep.
4. The Scheduled Trigger pulses the agents every 15 minutes. Each pulse, Head assigns the next queued issue to Dev.
5. Dev opens a PR. Reviewer1 + Reviewer2 each review independently — approve, request changes, or veto. Dev iterates until both approve.
6. Head merges and picks the next ticket. Loop until the queue is empty or the duration expires.
7. You wake up to 5 merged PRs, a clean queue, and a chat transcript you can scroll.

## ─ Features

### Dashboard

- 📺 **4-quadrant project view** — chat, agent terminals (HEAD / DEV / RE1 / RE2), GitHub board, operator panel
- ⏰ **Scheduled Trigger** — recurring "queue check" pulses for autonomous overnight runs
- 📲 **Telegram bridge** — mirror the chat to your phone for remote monitoring
- 💬 **Discord bridge** — forward agent chat to a Discord channel for team visibility
- 💾 **Project history export/import** — JSON snapshots of the full chat transcript
- 🧯 **Loop Guard control** — raise the hop limit and auto-resume stuck chains
- 🔔 **Notification sounds** — Web Audio chime on new agent messages with a background-only mode
- 🎞️ **Current Batch Progress panel** — per-issue progress bars computed from live GitHub state
- 🗂️ **Recently closed / merged feed** — so finished work doesn't disappear from the GitHub panel
- 💤 **Keep Mac Awake** — `caffeinate` wrapper so your laptop survives the night

### Workflow

- 🧭 **Multi-project support** — each project has its own chat instance + isolated worktrees
- 📝 **Per-project `OVERNIGHT-QUEUE.md`** with auto-incrementing batch numbers
- 💬 **Slash commands** — `/continue`, `/clear`, `/summary`, `/poetry`, `/roastreview`
- 🏷️ **Chat polish** — threaded replies, colored `@mentions`, short reviewer labels (RE1/RE2)
- 🧰 **Operator identity** — set your chat display name in Settings

### Safety

- 🚧 **GitHub branch protection** enforced on `main`
- ✅ **2-of-2 reviewer approval** required before merge
- 🛑 **Sender lockdown** — chat POSTs can't impersonate an agent (`head`, `dev`, …) from the UI
- 🗄️ **Auto-snapshot** of chat history to `~/.quadwork/{project}/history-snapshots/` with an in-dashboard **Restore** button

## ─ Operator MCP

Drive QuadWork from an **external Claude agent** — Claude Code or Claude
Desktop — instead of clicking the dashboard. QuadWork ships a stdio
[Model Context Protocol](https://modelcontextprotocol.io) server that exposes
the same operator surface as tools: read team chat and batch progress, define
and run overnight batches, and control individual agents.

Register it with the bundled bin (one line):

```bash
claude mcp add quadwork -- quadwork-mcp-operator --port 8400
```

The tools come in two tiers:

- **Read / observe** — `list_projects`, `read_chat`, `batch_status`, `read_queue`, `list_agents` (no state change).
- **Act** — `send_message`, `set_batch` / `append_batch` / `ensure_batch`, `start_batch` / `trigger_now` / `stop_batch`, `agent_control`, `interrupt_all`.

A typical flow: `set_batch` to define the work → `start_batch` for a scheduled
cadence → `batch_status` to watch progress.

> **Security boundary:** the server is **localhost-only with no auth by design**
> — it talks to `127.0.0.1:8400` and the MCP client must run on the same machine
> as QuadWork. Don't expose the backend port over a network without adding
> authentication.

Full tool reference, Claude Desktop config, and remote/VPS registration:
**[docs/operator-mcp.md](docs/operator-mcp.md)**. For an agent-facing operating
playbook (registration + workflow recipes as a Claude skill), see
**[skills/quadwork-operator/SKILL.md](skills/quadwork-operator/SKILL.md)**.

## ─ Review batches

The same Head → Dev → RE1/RE2 → Head loop, but in **review-only** mode — the
team reviews work instead of building it. **No code, no PRs, no merges.** There
are two batch types, selected by a `**Batch type:**` marker in
`OVERNIGHT-QUEUE.md`:

- **`ticket-review`** — review issue specs before they're built.
- **`pr-review`** — review already-merged PRs and capture findings as follow-up tickets.

**How to use** — ask Head in chat, just like a code batch:

```
@head review tickets #12 #15 #18
@head review merged PRs #40 #41
```

Reviewers assess each item against a rubric; Dev edits issue bodies and files
follow-up fix tickets via REST; Head marks items approved in the queue. The
**Current Batch Progress** panel shows review states (*queued · in review · 1 of
2 approvals · approved*) rather than merge language.

> **GraphQL budget:** review discovery reads the server-authored `GITHUB.md` and
> the GitHub **REST** API — never the GraphQL-backed `gh pr list` / `gh … view
> --json` — so a review batch barely touches your hourly API budget.

Queue contract and full state vocabulary: **[docs/review-batches.md](docs/review-batches.md)**.

## ─ External Tools

QuadWork stands on top of some great open-source work. Explicit thanks:

- **[AgentChattr](https://github.com/bcurts/agentchattr)** — by [@bcurts](https://github.com/bcurts).
  QuadWork's file-based chat system was originally inspired by AgentChattr.
  Thanks to bcurts for the foundational ideas.
- **[GitHub CLI (`gh`)](https://cli.github.com)** — used by all four agents
  for issues, PRs, reviews, and merges.
- **[Claude Code](https://github.com/anthropics/claude-code)** — Anthropic's
  CLI. Recommended for the Dev / Reviewer2 roles.
- **[Codex CLI](https://github.com/openai/codex)** — OpenAI's CLI.
  Recommended for the Head / Reviewer1 roles.
- **[Next.js](https://nextjs.org)** + **[Express](https://expressjs.com)** —
  dashboard frontend + backend.
- **[node-pty](https://github.com/microsoft/node-pty)** — embeds the agent
  terminals.
- **[xterm.js](https://xtermjs.org)** — in-browser terminal rendering.

## ─ Configuration

Global config lives at `~/.quadwork/config.json`. The per-project queue
lives at `~/.quadwork/{project_id}/OVERNIGHT-QUEUE.md`.

```json
{
  "port": 8400,
  "operator_name": "user",
  "projects": [
    {
      "id": "my-project",
      "name": "My Project",
      "repo": "owner/repo",
      "working_dir": "/path/to/project",
      "mcp_http_port": 8200,
      "mcp_sse_port": 8201,
      "auto_continue_loop_guard": false,
      "auto_continue_delay_sec": 30,
      "auto_restore_after_restart": false,
      "agents": {
        "head":      { "cwd": "/path/to/project-head",      "command": "codex"  },
        "dev":       { "cwd": "/path/to/project-dev",       "command": "claude" },
        "re1":       { "cwd": "/path/to/project-re1",       "command": "codex"  },
        "re2":       { "cwd": "/path/to/project-re2",       "command": "claude" }
      }
    }
  ]
}
```

Each project gets its own chat instance, MCP ports, and git worktrees.

## ─ Architecture

QuadWork runs as a single Express server on `127.0.0.1:8400`:

- **Static frontend** — pre-built Next.js export (the `out/` directory)
- **REST API** — agent lifecycle, config, GitHub proxy, chat proxy, triggers, loop guard, batch progress, project history
- **WebSocket** — xterm.js terminal PTY sessions + chat event fan-out

Per-project chat data lives at `~/.quadwork/{project}/chat/`.
Per-project git worktrees sit next to the repo:
`{repo}-head`, `{repo}-dev`, `{repo}-re1`, `{repo}-re2`. The
dashboard's xterm.js tiles attach to node-pty sessions over a WebSocket;
nothing about the agent state is held client-side.

## ─ Commands

| Command | Description |
|---------|-------------|
| `npx quadwork init` | One-time setup — installs prerequisites, opens the dashboard |
| `npx quadwork start` | Start the dashboard server |
| `npx quadwork stop` | Stop all processes |
| `npx quadwork cleanup --project <id>` | Remove a project's data and config entry |
| `npx quadwork cleanup --legacy` | Remove legacy pre-v2 files |

After `init`, create projects from the web UI at `http://127.0.0.1:8400/setup`.

### Disk usage

Each project stores its chat data at `~/.quadwork/{project_id}/chat/`.
Disk usage is minimal — chat logs are plain JSON files.

Existing v1 users can remove legacy files via `npx quadwork cleanup --legacy`.

## ─ Website

Visit [quadwork.xyz](https://quadwork.xyz) for an overview, demo, and getting started guide.

## ─ Community

Want to talk with the creator? [Join Hunt Town](https://discord.gg/syhbYPk3Wq) and find @project7.

## ─ License

MIT
