PatchRelay

Self-hosted toolkit for shipping code with agents: a Linear-driven harness that runs Codex sessions inside your real repos, plus two GitHub-native services that review PRs and deliver them through a merge queue. Each component works on its own, and they communicate only through GitHub.

Background reading: patchrelay: a Linear-driven harness for Codex, review-quill: a strict reviewer for your coding agent, and merge-steward: speculative integration, parallel validation, fast-forward landing.

The stack

This repository ships three independent services. Install one, two, or all three.

Service	Package	Role
patchrelay	pnpm add -g patchrelay	Linear-driven harness that runs Codex sessions inside your real repos. Fully autonomous on webhooks: implementation, review fix, CI repair, queue repair.
review-quill	pnpm add -g review-quill	Review gate that pairs with coding agents. Runs narrow and wide review passes, catches system misalignments the first pass missed, and sends fixes back through normal GitHub reviews.
merge-steward	pnpm add -g merge-steward	Turns reviewed PRs into a tested landing train: CI on exact future main SHAs, parallel validation for several PRs, and fast-forward landing through the green sequence.

Common setups:

• Full autonomy — all three. PatchRelay implements from a Linear issue, review-quill reviews, merge-steward delivers. No human in the room.
• Supervised delivery — review-quill + merge-steward without PatchRelay, driven by your own agent (Claude Code, Cursor, Codex CLI, …). See Use with your own agent.
• Queue only or review only — run either downstream service on its own if you already have the other half of the story.

What this buys you

• PRs ship tested against the latest main. The queue re-validates on the integrated SHA at admission time, and retries if main moves during validation. No more "green yesterday, broken today."
• Review catches real misalignments before merge. The reviewer checks both the changed lines and the surrounding system contract, so conflicts between code, docs, tests, callers, and shared abstractions get sent back while the PR is still cheap for the agent to fix.
• Many PR failures have mechanical fixes an agent can handle. Requested changes like a rename, a missing null check, a new test, refreshing against main, resolving a conflict surfaced by speculation, or rerunning a flaky job. Both services publish structured failure reasons (inline review comments, failing check names, queue incidents) an agent can act on directly.
• No prerequisites beyond GitHub. A GitHub App, a webhook, and pnpm add -g per service.

Use with your own agent

For supervised delivery — an agent you drive from Claude Code / Cursor / Codex iterating on PRs in real time — install the ship-pr skill from the companion marketplace:

/plugin marketplace add krasnoperov/patchrelay-agents
/plugin install ship-pr@patchrelay

ship-pr teaches the agent to block on review-quill pr status --wait and merge-steward pr status --wait, read structured failure reasons on exit 2, fix the code, push, and re-enter the wait. No polling loop, no LLM-judged "is it done yet?". See patchrelay-agents for more.

Quick start (PatchRelay harness)

Prerequisites:

• Linux with shell access, Node.js 24+
• git and codex (authenticated for the same user that will run PatchRelay)
• a Linear OAuth app and webhook secret
• a public HTTPS entrypoint (Caddy, nginx, tunnel) so Linear and GitHub can reach your webhooks

pnpm add -g patchrelay
patchrelay init https://patchrelay.example.com

init writes the local config, env files, and systemd unit. Edit ~/.config/patchrelay/service.env to fill in the Linear OAuth client id and secret (the webhook secret and token-encryption key are generated for you). Then:

patchrelay linear connect                              # one-time Linear OAuth
patchrelay linear sync                                 # cache teams/projects
patchrelay repo link krasnoperov/usertold \
    --workspace usertold --team USE                    # link a GitHub repo
patchrelay doctor                                      # validate
patchrelay status
patchrelay dashboard

When one Linear team owns issues for multiple repositories, include --project <Linear project> on each repo link. PatchRelay routes Linear webhooks by project first, so separate projects inside the same USE team can map to separate GitHub repos.

Each repo needs two workflow files for repo-specific run behavior:

• IMPLEMENTATION_WORKFLOW.md — implementation, CI repair, queue repair runs
• REVIEW_WORKFLOW.md — review fix runs

Keep them short, action-oriented, human-authored. Durable machine-level policy belongs in Codex developer_instructions; workflow files are for repo-local behavior and validation. See prompting.md for how the built-in scaffold composes them.

Full install, ingress, and GitHub/Linear app setup: self-hosting.md. Daily ops and CLI cheatsheet: operator-guide.md.

How it works

1. A human delegates an issue to the PatchRelay Linear app.
2. PatchRelay verifies the webhook, routes the issue to the right local repo, prepares a durable worktree, and launches an implementation run through codex app-server.
3. PatchRelay persists thread ids, run state, and observations so work stays inspectable and restartable.
4. GitHub webhooks drive reactive repair loops — CI repair on check failures, review fix on requested changes, queue repair on merge-steward evictions.
5. review-quill reviews ready PRs; merge-steward admits approved, green PRs and delivers them by speculative integration.
6. An operator can take over inside the same worktree at any time.

PR ownership in Linear

Use one visible rule: a same-repository GitHub PR attached to a delegated Linear issue is the PR PatchRelay owns. Attach a broken external PR when you want PatchRelay to adopt and repair it. PatchRelay also attaches every PR it creates.

PRs mentioned only as history, regression evidence, or related context belong in the issue description or comments as ordinary links; do not add them as issue attachments. If a delegated issue has more than one PR attachment, PatchRelay stops for clarification instead of guessing.

Architecture and failure taxonomy: architecture.md. Downstream delivery: merge-queue.md.

Downstream services

Two separate services handle review and delivery. Both are independent, GitHub-native, and usable without PatchRelay.

review-quill

Review gate that pairs with coding agents. It checks both the narrow diff and wider system context for misalignments, sends fixes back through ordinary GitHub reviews, and carries approval forward when a rebase leaves the patch unchanged. By default it reviews as soon as the head updates; it can optionally wait for configured checks to go green first.

review-quill init https://review.example.com
review-quill repo attach owner/repo
review-quill doctor --repo repo

See the review-quill package README for the pitch and quick start, or docs/review-quill.md for the full operator reference.

merge-steward

Merge queue with speculative integration. It turns reviewed PRs into a tested landing train: CI runs on the exact future main SHAs, several PRs validate in parallel, and main fast-forwards through the green sequence as soon as it is safe. Evictions produce a durable incident and a GitHub check run — the signal an agent uses to trigger a repair.

merge-steward init https://queue.example.com
merge-steward repo attach owner/repo --base-branch main
merge-steward doctor --repo repo
merge-steward service status

See the merge-steward package README for the pitch and quick start, docs/merge-steward.md for the full operator reference, or docs/merge-queue.md for the two-service overview.

Docs

• Concepts — the shared mental model (three roles, four primitives, four states, carry-forward, eviction). Start here.
• Blog: patchrelay · review-quill · merge-steward · the gates, not the autonomy
• Self-hosting and deployment — install, ingress, OAuth and GitHub App setup
• Architecture — components, ownership, state machine, failure taxonomy
• Operator guide — daily loop, CLI cheatsheet, troubleshooting
• Merge queue — the three-service delivery story
• GitHub queue contract — bus artifacts, identity algorithms, configurable names
• Prompting — how workflow files and the built-in scaffold compose
• Secrets — systemd credentials, resolution order
• review-quill reference · merge-steward reference
• Dashboard guidance · Design docs
• Contributing · Security policy

Status

PatchRelay is usable now, but still early and opinionated. The focus is a strong self-hosted harness for Linear + Codex work, not a generalized SaaS control plane.