relevo

relevo

The handoff between a MasterMind agent and its builders, drawn.

relevo automates the plan/report handoff between AI coding agents. You talk to the MasterMind; it hands work to builders — headless processes on this machine or on a server you enrolled — and relevo moves the files between them.

Install relevo

Two agent harnesses, and no terminal manager. relevo needs one harness for the MasterMind and one for a builder (opencode, claude, agy, codex). Nothing to arrange on screen: the builders run headless, on this machine or on a server you enrolled.

How one relevo round moves between the MasterMind, the builder and disk. The MasterMind calls the relevo CLI, which stages the round’s plan as NNN-prompt.md in the state directory at ~/.local/state/relevo/<name>/ and starts a fresh builder process. Those steps are drawn as solid arrows: each one happens while the MasterMind’s turn is still running. The builder writes NNN-report.md and then an empty NNN-done marker back into the same directory. The relevo daemon, a separate long-running process, sees that marker and queues the report; the background relevo wait wakes the MasterMind with it. Those steps are drawn as dashed arrows: they happen after the MasterMind’s turn has ended, which is the only reason a second process exists. The builder is a fresh headless process per round, or a process on a relevo serve host. MasterMind your session — Claude Code, opencode… relevo never types into it. relevo send relevo CLI the MasterMind calls it mid-turn; it returns at once. bind · send · status wait · done the plan state ~/.local/state/ relevo/<name>/ relevo.db NNN-prompt.md NNN-report.md NNN-done the round closes on the empty NNN-done marker. starts the runner builder a fresh headless process per round, or one on a relevo serve host. NNN-report.md then NNN-done relevo daemon the reconciler; it sees the marker and queues the report; the background wait wakes you. the marker delivered after the MasterMind’s turn has ended
  1. MasterMind Your session — Claude Code, opencode… relevo never types into it.

    relevo send --file plan.md — called mid-turn by the MasterMind, returns straight away

  2. relevo CLI Called by the MasterMind through Bash or the plugin’s MCP tools: bind, send, status, wait, done.

    stages NNN-prompt.md in the state directory

  3. state relevo.db under ~/.local/state/relevo/<name>/ — the open round’s NNN-prompt.md, NNN-report.md and empty NNN-done marker.

    the runner starts from NNN-prompt.md

  4. builder A fresh headless process per round — no tab, no memory across rounds — or one on a relevo serve host you enrolled.

    writes NNN-report.md, then an empty NNN-done, back to disk

  5. relevo daemon One reconciler, under systemd or launchd. It runs when no model does.

    sees the marker and queues the report; the background relevo wait wakes the MasterMind with it

outbound. The MasterMind calls relevo send and it returns inside the same turn.

inbound. The report lands after that turn has ended, when no model is running to notice it.

The outbound leg runs while the MasterMind is mid-turn. The inbound leg lands after the turn has ended, when no model is running to notice. Something has to be awake then: the daemon sees the marker, and the background wait wakes the MasterMind. That is the only reason the daemon exists.

First round

the round, in full →

The builder writes NNN-report.md when it has finished and then creates an empty NNN-done as its last action. relevo closes the round on that marker: the marker is the contract, not the report. relevo makes no judgement about what came back — run the project’s own check yourself before calling the round done. In Claude Code the wait runs as a background command, and the session wakes with the report.

relevo bind --name api --no-feature
  # start a builder
relevo send --name api --file plan.md
  # hand it the plan
relevo wait --name api --timeout 10m
  # 0 closed · 3 needs you
relevo done api
  # stop relaying

What relevo refuses to do

all six, with reasons →

relevo makes no judgements. It moves files, starts processes, and records what each round did. Whether a report is good, whether a question needs a human, whether the work is done — every one of those decisions stays with the MasterMind, or with you.

No judgements

It never summarises, rewrites or decides that work is done.

The check annotates; it never decides

The gate command leaves a gate=<result> note on the round.

The destructive verbs need a name

done and unbind take a name or --pick; a bare verb never guesses.

It refuses to guess a candidate

More than one candidate with no order set is would refuse, not a pick.

It deletes a branch in exactly two places

Its own pushed relevo/<name> on unbind --done/--sweep, and a seconds-old bind --server rollback. An adopted --branch is never deleted.

Nothing is typed into your session

A report arrives by the background wait, the channel, a harness deliverer, or a hand-run relevo wait.

Install

/plugin marketplace add fuad-daoud/relevo
  # in Claude Code
/plugin install relevo@relevo
relevo config init
  # candidates, policy, actors
relevo doctor
  # names what is missing, and the fix

The relevo binary is a release tarball for Linux or macOS, or go install github.com/fuad-daoud/relevo/cmd/relevo@latest; later, relevo update replaces it, checksum-verified.

Two harnesses for the MasterMind and a builder — opencode, claude, agy, codex · git optional · Linux or macOS · Go 1.25+ to build from source. Everything else — builders, remote builders, the daemon, the verbs between rounds — is in the docs.