Step-by-step guides for setting up QuadWork, designed for both humans and AI coding agents:
- Mac Installation — local setup on macOS
- Windows Installation — local setup via WSL2 (Windows Subsystem for Linux)
- VPS Installation — remote server (Hetzner/Ubuntu) with domain + SSL
- Troubleshooting — common issues and fixes
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.
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.
quadwork-demo.mp4
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.
- 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.
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.
- 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
- Install Node.js 20+ if you don't have it
- On macOS, install Homebrew:
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)" - Open your terminal and run:
npx quadwork init- 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.
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.
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
- You drop a batch of 5 related tickets into chat:
@head start 5 sub-tickets under #123. - Head files the 5 issues on GitHub, writes them to
OVERNIGHT-QUEUE.md, and asks you to click Start Trigger. - You click it, close the laptop, and sleep.
- The Scheduled Trigger pulses the agents every 15 minutes. Each pulse, Head assigns the next queued issue to Dev.
- Dev opens a PR. Reviewer1 + Reviewer2 each review independently — approve, request changes, or veto. Dev iterates until both approve.
- Head merges and picks the next ticket. Loop until the queue is empty or the duration expires.
- You wake up to 5 merged PRs, a clean queue, and a chat transcript you can scroll.
- 📺 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 —
caffeinatewrapper so your laptop survives the night
- 🧭 Multi-project support — each project has its own chat instance + isolated worktrees
- 📝 Per-project
OVERNIGHT-QUEUE.mdwith 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
- 🚧 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
QuadWork stands on top of some great open-source work. Explicit thanks:
- AgentChattr — by @bcurts. QuadWork's file-based chat system was originally inspired by AgentChattr. Thanks to bcurts for the foundational ideas.
- GitHub CLI (
gh) — used by all four agents for issues, PRs, reviews, and merges. - Claude Code — Anthropic's CLI. Recommended for the Dev / Reviewer2 roles.
- Codex CLI — OpenAI's CLI. Recommended for the Head / Reviewer1 roles.
- Next.js + Express — dashboard frontend + backend.
- node-pty — embeds the agent terminals.
- xterm.js — in-browser terminal rendering.
Global config lives at ~/.quadwork/config.json. The per-project queue
lives at ~/.quadwork/{project_id}/OVERNIGHT-QUEUE.md.
{
"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.
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.
| 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.
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.
Visit quadwork.xyz for an overview, demo, and getting started guide.
Want to talk with the creator? Join Hunt Town and find @project7.
MIT