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: implementation, review fixes, branch-CI repair, and repair of separate integration candidates.
review-quill	pnpm add -g review-quill	Substantive feature review on PR heads plus narrow preservation review after an agent changes an integration candidate.
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 as the exact tested future main. The queue freezes the approved feature head, validates a cumulative integration candidate, and lands that same SHA. Moving main rebuilds integration evidence without reopening the feature review.
• 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.
• Integration failures do not rewrite approved features. PatchRelay resolves conflicts and candidate-test failures on self-describing Merge Steward refs. Review Quill checks only whether that repair preserved the approved feature.
• 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, branch-CI repair, and integration-candidate 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 wake reconcilers; each service derives work from current PR, review, candidate-ref, ancestry, and check truth.
5. Any effective GitHub approval on the exact green feature head lets merge-steward freeze it and build a speculative train. PatchRelay may then repair only its integration candidate without pushing the feature branch, even when the PR has no Linear issue or prior PatchRelay delegation.
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 with two scopes: full feature review on PR heads and narrow integration-preservation review on agent-repaired candidate SHAs. A moving main does not by itself trigger another feature review.

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 frozen approved PR heads into cumulative future-main candidates, validates several in parallel, and fast-forwards through the green sequence. Conflicts and candidate-test failures remain in the integration track and are repaired on candidate refs.

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: two tracks, frozen feature approval, integration workspaces, and exact-SHA landing. 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 — state-derived protocol over PRs, candidate refs, ancestry, and checks
• 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
• Circuit City — interactive web factory, local demo, and service connections
• 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.