convoy github

◆ open-source · built on opencode · bun + typescript

You write the PRD. A convoy ships the feature.

Convoy takes a PRD and turns it into a structured, reviewable implementation — a pipeline of specialized agents, each running on the model best suited to its job, leaving one commit per phase.

$ git clone https://github.com/Inakitajes/convoy && cd convoy && bun install && make install
~/your-repo — convoy --prompt-file prd.md
◆ convoy 21:31:39 · 7:08 · $5.31
pipeline
6/6
  • ✓ implementer 1:47 $1.92
    gpt-5.6-terra#xhigh
  • ✓ patterns 0:58 $0.71
    gpt-5.6-terra#xhigh
  • ✓ security 1:12 $0.83
    gpt-5.6-terra#xhigh
  • ✓ design 0:44 $0.31
    z-ai/glm-5.2
  • ✓ tests 1:21 $0.96
    gpt-5.6-terra#xhigh
  • ✓ adversarial 1:06 $0.58
    z-ai/glm-5.2
logs
21:24:31 ▸ attempt 1/2 · openai/gpt-5.6-terra#xhigh
21:24:31 ◆ session ses_9f2…kzn
21:24:34 · reads prd.md + repo map
21:24:52 ▦ todos updated (1/5)
21:25:21 · edits 6 files under src/features/onboarding
21:25:48 ▦ todos updated (4/5)
21:26:11 ◆ report saved — reports/implementer.md
21:26:18 ✓ committed convoy(implementer): add onboarding flow
21:26:19 ▸ attempt 1/2 · openai/gpt-5.6-terra#xhigh
21:26:19 ◆ session ses_3hL…wWG
21:26:24 · refactor without behavior change
21:26:39 ▦ todos updated (2/3)
21:27:02 ◆ report saved — reports/patterns.md
21:27:17 ✓ committed convoy(patterns): align with repo patterns
21:27:18 ▸ attempt 1/2 · openai/gpt-5.6-terra#xhigh
21:27:18 ◆ session ses_7k1…Rdo
21:27:26 · audit: storage, injection, secret handling
21:27:41 ↻ finding: unsanitized payload persisted
21:27:58 ▦ todos updated (2/2)
21:28:24 ◆ report saved — reports/security.md
21:28:30 ✓ committed convoy(security): sanitize progress payload
21:28:31 ▸ attempt 1/1 · openrouter/z-ai/glm-5.2
21:28:31 ◆ session ses_m42…7fX
21:28:38 · polish ui to the repo design system
21:28:57 ▦ todos updated (3/3)
21:29:09 ◆ report saved — reports/design.md
21:29:15 ✓ committed convoy(design): polish onboarding ui
21:29:16 ▸ attempt 1/2 · openai/gpt-5.6-terra#xhigh
21:29:16 ◆ session ses_0a2…kzn
21:29:22 · unit + e2e coverage for onboarding
21:29:47 ▦ todos updated (2/4)
21:30:15 · 14 tests passing · 0 failing
21:30:31 ◆ report saved — reports/tests.md
21:30:37 ✓ committed convoy(tests): cover onboarding flow
21:30:38 ▸ attempt 1/1 · openrouter/z-ai/glm-5.2
21:30:38 ◆ session ses_x71…pQ2
21:30:45 · adversarial review of the full diff
21:31:02 · challenge: resume edge case — dismissed
21:31:21 ◆ report saved — reports/adversarial.md
21:31:44 ✓ no blocking findings — run complete
[↑↓] node · [enter] read · [←→] tab · shift+tab smart auto-accept

↑ a simulated implement run, replayed live — this is what the dashboard looks like while convoy works

01 · $ convoy explain the-problem

A first draft is not shippable code.

The quality of agent-written code comes from what happens after the first pass. Convoy automates that follow-through as a pipeline — so it happens every time, not when someone remembers.

01

Single session, single blind spot

One agent in one session reviews its own work. What ships is a first draft — blind spots, shortcuts and all.

02

The follow-through is the work

Pattern alignment, security audits, tests, adversarial review. The steps that make code shippable are exactly the ones that get skipped.

03

Orchestrating by hand doesn't scale

Re-prompting, re-reviewing and re-committing across phases by hand is a full-time job. Convoy makes it repeatable.

02 · $ convoy run implement

PRD in. Six commits out.

convoy --prompt-file prd.md runs the default implement pipeline. What lands has already been pattern-aligned, security-audited, design-polished, tested and adversarially reviewed.

  1. implementer

    gpt-5.6-terra#xhigh

    Implements the feature following the repo's existing patterns.

  2. patterns

    gpt-5.6-terra#xhigh

    Refactors without changing behavior; aligns with the rest of the code.

  3. security

    gpt-5.6-terra#xhigh

    Audits and fixes security issues before they ship.

  4. design

    z-ai/glm-5.2

    Polishes the UI following the repo's design system.

  5. tests

    gpt-5.6-terra#xhigh

    Automated tests plus relevant E2E and integration coverage.

  6. adversarial

    z-ai/glm-5.2

    Final adversarial review before the PR even exists.

git log — one commit per phase review a story, not a blob
✓ convoy( implementer ): add onboarding flow with progress persistence
✓ convoy( patterns ): align onboarding with repo patterns
✓ convoy( security ): sanitize stored progress payload
✓ convoy( design ): polish onboarding to the design system
✓ convoy( tests ): cover the onboarding flow e2e
✓ convoy( adversarial ): final review — no blocking findings

03 · $ convoy explain fan-out

Different models catch different things.

Audits fan out in parallel across two models — a GPT and a Claude reviewing the same diff find different issues. Findings are triaged adversarially before any fix lands.

∴ parallel group · 3 steps · 6 runs
the diff
──▶
bugs audit claude-opus-4.8
bugs audit gpt-5.6-terra#xhigh
──▶
adversarial triage
──▶
✓ accepted findings only

◆ Any provider you're authenticated with

Built on OpenCode, so every step can run on any model from any provider — within the same run. Step, agent and default models are all overridable.

◆ Subscription-friendly cross-vendor reviews

runner: claude-code executes audit steps with your local claude CLI — genuine model diversity without paying per token.

◆ Fan-out is a one-liner, always read-only

parallel: and models: run audits concurrently, one per model. Convoy forces them read-only and verifies the git baseline afterwards.

04 · $ convoy cat .convoy/config.yaml

Pipelines are YAML, not code.

Any number of steps, your own agents, your own models, human gates anywhere. Define a ship pipeline — refine the branch, sync with base, draft the PR — and run convoy -p ship.

# .convoy/config.yaml — your team's actual workflow
pipelines:
  audit:
    steps:
      - implementer
      - parallel:            # concurrent, forced read-only
          - patterns
          - security
          - agent: clean-code
            models:          # one run per model
              - anthropic/claude-opus-4-8
              - openai/gpt-5.6-terra#xhigh
      - type: human          # a named human gate, anywhere
        name: sign-off
      - agent: adversarial
        name: triage
        reports: all
built-in pipelines no config needed
  • implement writes code
  • implement-lite writes code
  • ultra-implement writes code
  • refine writes code
  • ultra-refine writes code
  • review report only
  • review-lite report only

05 · $ convoy explain guard-rails

Autonomy with a seatbelt.

Convoy owns the operational layer around the agents: guard rails, commit safety and a live permission gate — so a pipeline can run unattended without running wild.

┌ ┐ └ ┘

permission gate

Agents run with a restricted bash policy: an allowlist of safe commands, a hard denylist — git push, deploys, sudo, curl | sh — and everything else falls through to ask.

approve? [o]nce, [a]lways, [r]eject >
┌ ┐ └ ┘

smart auto-accept

--smart hands each request to an external AI judge with every tool disabled. Safe requests auto-approve; anything risky escalates to you. Fail-closed by design.

convoy --smart --smart-model anthropic/claude-haiku-4-5
┌ ┐ └ ┘

commit safety

Before each commit, staged files are scanned for common secret names. A match aborts the commit and resets the index — nothing leaks.

.env*  *.pem  id_rsa*  credentials*  *.keystore
┌ ┐ └ ┘

human gates

Drop a type: human step anywhere in a pipeline. The run pauses indefinitely until you continue, open the live session, or abort.

- type: human
  name: sign-off
Every run is recorded. reports/, diffs/, logs/ and metadata land under ~/.convoy/runs — convoy runs browses the history, and --resume replays a failed run from its frozen pipeline.

06 · $ convoy convoy --help

CLI and TUI, interchangeably.

Plain flags and prompt files — --no-tui gives you plain logs for pipes and CI — or drive everything from the TUI: live dashboard, cost, tokens and provider limits while the run is live.

$ convoy — the surface area
  • $ convoy # interactive launcher
  • $ convoy --prompt-file prd.md # run the default pipeline
  • $ convoy -p review "pre-merge check" # report-only second opinion
  • $ convoy runs # browse & attach to past runs
  • $ convoy config # edit global & project config in a TUI
  • $ convoy --resume 20260519-103045-x7q2 # pick up where a run failed
convoy — 146×42
The convoy TUI running a pipeline with parallel agents: pipeline panel on the left, live logs on the right, cost and token usage in the header
the real dashboard — a run mid-flight with a parallel audit group across two models

07 · $ convoy init --global

Ship your first pipeline in five minutes.

Convoy stores no provider credentials — it uses the providers you already authenticated in OpenCode.

requires bun ≥ 1.0 opencode auth login git
$ git clone https://github.com/Inakitajes/convoy && cd convoy && bun install && make install
view on github