Conveyor

A merge conveyor for teams whose PRs are written by AI agents.

Agents can open tens of PRs an hour. A traditional CI/CD pipeline tests one PR at a time against a main that has already moved, takes an hour to say yes, and leaves every other PR going stale in the queue. Conveyor replaces that with an optimistic-concurrency merge pipeline:

1. Fast signal — a cheap, impact-scoped check gates merging; the heavy suite moves post-merge.
2. Speculative merge trains — queued PRs are tested on top of each other's predicted merges, in parallel, so N PRs land per CI cycle instead of one.
3. Post-merge gate with auto-repair — the full suite runs continuously against main; failures are bisected to a culprit and handed back to an agent to fix forward (or auto-reverted).
4. Intents, not diffs — agent PRs carry a replayable task manifest. When a PR conflicts or is evicted, Conveyor doesn't rebase it — it re-runs the agent against fresh main. Write-set claims prevent most conflicts before work even starts.

No server. No database. State lives in git refs; the coordinator runs inside your existing GitHub Actions. Human PRs flow through the same train untouched.

Quick start

npm install -g conveyor-ci
cd your-repo
conveyor init          # writes conveyor.yml + workflows, creates labels

Edit conveyor.yml (two commands are mandatory):

version: 1
branch: main
fast_check:
  run: pnpm turbo run test --filter="...[origin/main]"   # target < 10 min
full_check:
  run: pnpm test && pnpm playwright test                 # runs post-merge

Commit, push, and protect main so the fast-check status is required — the landed SHA is the tested train commit, so it already carries that check. Enqueue any PR by adding the conveyor:queued label or running conveyor merge <pr>.

Full documentation:

| Doc | What it covers | | --- | --- | | How it works | Lifecycle, train mechanics, state model, failure handling | | Team setup | Step-by-step installation, permissions, secrets, branch protection | | Reference | conveyor.yml schema, intent manifest spec, CLI, labels & refs | | Agent integration | The agent protocol, drop-in AGENTS.md snippet, Claude Code example | | Operations | Monitoring, evictions, bypass, troubleshooting, FAQ | | Objections | Every objection teams raise, answered honestly |

Development

TypeScript scaffold of the CLI + coordinator lives in src/:

• src/cli.ts — all commands (init, status, run, merge, claim, release, claims, intent new|check, exec, agent-job, bypass, pause/resume)
• src/lib/plan.ts — the pure train planner (land / retry / evict / build), unit-tested in test/
• src/coordinator/tick.ts — stateless tick that applies the plan via the GitHub API (CAS state writes on refs/conveyor/state)
• src/lib/github.ts — refs-as-JSON storage, branch/merge/fast-forward, checks
• src/lib/intent.ts, src/lib/claims.ts — manifest parsing + write-set validation, claim overlap heuristics
• src/commands/init.ts — scaffolds conveyor.yml, the four workflows, labels

npm install
npm run build              # tsc
npm test                   # planner/claims/intent unit tests
node scripts/check-docs.mjs  # docs-consistency gate (also runs in fast/full checks)

scripts/check-docs.mjs asserts prose-vs-implementation consistency — every rule in it is a regression test for documentation drift found while dogfooding (phantom check names, retired paths, stale token claims, and the train.check ↔ workflow-name coupling).

Implemented through v0.2: the train (with head-drift invalidation and stack-aware ordering, holds, and eviction cascades), regeneration — including dependents regenerating against their stack parent's head — the fix-forward agent job, the post-merge repair loop (async bisection over landed commits, then notify / revert / fix-forward per full_check.on_failure), claims with stack families, intent validation, and status --watch.

Remaining (v0.3): npm Trusted Publishing for releases (bypass-2FA tokens stop working for direct publish in Jan 2027), per-position check timeout enforcement, a stacked-PR-aware diff base for intent check (today it diffs against main, so a child PR's diff includes its parent's), and GitLab.

The website lives in site/, deployed at https://conveyor-docs.vercel.app: / is the landing page, /docs/ the full handbook, /agents.md the machine-readable agent protocol, and /llms.txt the LLM index.

Dogfooding

This repository merges through its own Conveyor instance: main is protected with a required fast-check status, direct pushes are disabled, and every change — including the one that added this paragraph — lands via a speculative train position. The first change to ride the train was the PR that introduced this section.

Requirements

• GitHub repository with Actions enabled (GitHub-hosted or self-hosted runners)
• Node.js 20+ where the CLI runs
• A fast check that completes in minutes, or the willingness to carve one out — Conveyor's throughput is batch_size / fast_check_latency
• For agent regeneration and fix-forward: an agent CLI (e.g. Claude Code) and its API key in Actions secrets