RelayForge

Safe multi-agent coding loops — plan → implement → review → verify,
each step in an isolated git worktree with real OS containment.

# from this repo (npm package is not published yet)
npm ci && npm run build && npm link

cd /path/to/your-git-project   # must be a clean git repo for --execute
relayforge init --provider claude   # or: codex | gemini
relayforge doctor
relayforge run "Ship a small verified change"            # dry-run (default)
relayforge run "Ship a small verified change" --execute  # actually launch agents

---

Why RelayForge

Most “agent team” tools are shell scripts around chat CLIs. RelayForge is a parent-owned control plane:

Guarantee	What it means
Dry-run by default	Nothing spends tokens until you pass --execute
Isolated worktrees	Each attempt gets its own git worktree; review is a separate boundary
Containment	Linux Bubblewrap + cgroup scopes; fail closed if the host can’t prove them
Durable state	Run facts live in SQLite under .loop/ — restartable, auditable
Independent review	Reviewer role is not the same process as the implementer
Deterministic verify	Your verify: commands (e.g. npm test) gate acceptance

---

Setup (from source)

npm is not on the registry yet. Install from GitHub:

1. Prerequisites

• Node.js 20.x or ≥22
• Git
• At least one agent CLI you use day-to-day: claude, codex, or gemini
• Linux recommended for full safety (Bubblewrap + user cgroup). macOS works with weaker containment: dry-run plans, doctor, serve (dashboard) and the CLI all work on macOS — only --execute still fails closed there, because the money ledger needs /proc/self/fd and agent processes need a cgroup-v2 strong scope (Linux provides both). Plan on macOS, execute on a Linux box (see docs/linux-runner-runbook.md).

node -v && git --version
command -v claude || command -v codex || command -v gemini

2. Install RelayForge on your PATH

git clone https://github.com/arbazkhan971/relayforge.git
cd relayforge
npm ci
npm run build
npm link          # exposes: relayforge, loop, loop-orchestrator
relayforge --version

3. Init a project

cd /path/to/your-app
git status         # should be clean before --execute

relayforge init --provider claude   # writes relayforge.config.yaml + starters
relayforge validate
relayforge doctor                   # host, sandbox, providers — fix anything red

doctor should report Node/Git OK, a valid config, and at least one ready provider. On Linux you also want sandbox: bwrap and a strong process-scope when available.

4. First run

# Optional: project memory for agents
relayforge learn

# Plan only — no agents launched
relayforge run "Add a /health endpoint and a unit test"

# When the plan looks right, spend tokens
relayforge run "Add a /health endpoint and a unit test" --execute

5. Watch the run

Every --execute run opens its own detached tmux viewport by default (disable with defaults.viewport: false or RELAYFORGE_TMUX=off); the commands below just attach to or show it.

# Local dashboard + read-only API (loopback only)
relayforge serve

# tmux panes for agent sessions (on by default for execute runs)
relayforge monitor            # single-screen mission control (latest run)
relayforge attach             # attach to the latest run's viewport
relayforge tmux new           # open the viewport explicitly

---

Daily commands

relayforge doctor              # is this machine / project ready?
relayforge validate            # config schema + semantics
relayforge run "<goal>"        # dry-run plan
relayforge run "<goal>" --execute
relayforge serve               # dashboard on 127.0.0.1
relayforge status              # owned sessions
relayforge stop <run-id>       # cancel a run
relayforge --help

---

Providers that work today

Type	CLI on PATH	Notes
claude	claude	Best default for most people
codex	codex	ChatGPT / Codex login
gemini	gemini	Gemini CLI auth
custom	your binary	You own the contract
opencode / pi / grok	exact pins	Personal subscription (CLI login) or linked API key required; execute refuses only when nothing is linked

OpenCode / Pi / Grok run on their own contained routes once you link a credential: install + log into the CLI (personal subscription) or set the matching API key. Release receipts for npm publication are a separate operator gate.

---

What you get after init

• relayforge.config.yaml — strict team / loop / verify config
• brief.md — project brief for agents
• .loop/ — durable runs, prompts, locks (do not rename)

Compatibility: existing loop.config.yaml and .loop/ still work. Binary aliases loop and loop-orchestrator call the same program as relayforge.

---

Screenshots (live product)

Captured from a running relayforge serve after a real dry-run (connected control plane, task board, activity), and from the shipped example app.

Control dashboard — connected after dry-run

Shows: green connected state, KPI strip (progress 100%, run succeeded), task board with the planned task in DONE, and a live activity timeline.

Example app — examples/todo-app

cd examples/todo-app && npm start   # http://localhost:3000

---

Docs

Doc	For
Configuration	Full config reference
Safety	Containment and fail-closed rules
Session steering	Future-boundary steering (not terminal injection)
Architecture	How the control plane works
Implementation status	What’s green vs release-blocked
Publishing	RC / npm gates (operators)

---

Current boundaries (honest)

• Single-repo loops with Claude/Codex/Gemini are the supported product path.
• Multi-repo is integrated but needs explicit config.
• OpenCode / Pi / Grok characterization exists; ordinary execute is credential-gated (linked subscription or API key), and release receipts still gate npm publish.
• Not on npm yet — install from this GitHub repo until 1.0.0-rc.1 is published.
• No auto-merge to main, no invented remote PRs without explicit SCM config.

---

License

MIT — see LICENSE.

_{github.com/arbazkhan971/relayforge}