relay

<!-- Relay: vendor-neutral AI coding agent orchestrator README. Source of truth lives in docs/. Keep them in sync. --> <div align="center">

 ██████╗ ███████╗██╗      █████╗ ██╗   ██╗
 ██╔══██╗██╔════╝██║     ██╔══██╗╚██╗ ██╔╝
 ██████╔╝█████╗  ██║     ███████║ ╚████╔╝
 ██╔══██╗██╔══╝  ██║     ██╔══██║  ╚██╔╝
 ██║  ██║███████╗███████╗██║  ██║   ██║
 ╚═╝  ╚═╝╚══════╝╚══════╝╚═╝  ╚═╝   ╚═╝

Your AI coding agents are about to hit their limits. Relay keeps them going.

The handoff protocol for AI coding agents: a signed, portable contract that carries intent, plan, and in-flight code from one agent to the next.

Relay detects the Claude Code / Codex / Copilot / Cursor / Cline / Antigravity sessions already running on your machine, reads what each one is doing, and hands the work to a fresh agent, account, or provider before any of them runs out of quota. One subscription dies, the task lives on another.

Vendor-neutral. Works across Claude, Codex, Antigravity, OpenCode, Ollama, Copilot, Continue, Cline, Cursor.

Docs · Architecture · Providers · Contributing

</div>

---

Download

The desktop app is the recommended way to run Relay: the daemon ships inside, so nothing else is needed. These always point at the latest release.

| Platform | Download | |---|---| | Windows | Relay-Windows-Setup.exe | | macOS (Apple silicon) | Relay-macOS.dmg | | Linux | Relay-Linux.AppImage |

Installers are unsigned for now (see Code signing policy below), so first launch trips SmartScreen on Windows or Gatekeeper on macOS. Click through it, or verify the download against the release's SHA256SUMS first if you want extra assurance.

Prefer the CLI/TUI instead? Grab the matching archive from the latest release, or install straight from the terminal:

60-second quickstart

Prerequisites: git, plus at least one AI agent CLI installed and authenticated (for example npm i -g @anthropic-ai/claude-code then claude login).

macOS / Linux

curl -fsSL https://raw.githubusercontent.com/dbisina/relay/main/scripts/install.sh | bash

Windows (PowerShell)

irm https://raw.githubusercontent.com/dbisina/relay/main/scripts/install.ps1 | iex

Run a task

cd my-project
relay init
relay run "add a refund flow to the orders service"

Opening the desktop app starts the daemon for you and leaves it running after you close the window, so the CLI keeps working against the same orchestrator.

Desktop app

Two desktop clients ship in this repo, both rendering the same daemon API:

| | Stack | Status | Build | |---|---|---|---| | packages/desktop | Electron, React, TypeScript | Recommended | cd packages/desktop && npm install && npm run dev | | packages/ui | Rust, egui | Legacy | cargo run -p relay-ui |

The egui app still builds and is still published in the release archives so existing setups keep working, but new design work happens in the Electron one.

The Electron client is the one under active design work. It opens on a chat-style home screen: describe a task in the composer, arrange the provider rotation from the chips above it, and pick up any agent session already running on your machine. Clicking a session opens a manifest of exactly what a handoff would carry (model, messages, files touched, skills, MCP servers) with a pinned control to continue it on another provider or account.

Package installers with npm run package (NSIS on Windows, dmg on macOS, AppImage on Linux). It expects the relay binary on your PATH or beside the app, and starts the daemon itself if one is not already running.

Recommended path: the installers above pull a prebuilt binary from the latest GitHub Release, which is fast but depends on that release's cross-platform build having gone cleanly for your OS. Cloning and building from source is the most reliable route, always matches the current code, and is what the maintainers actually run day to day:

git clone https://github.com/dbisina/relay && cd relay
./scripts/setup.sh        # macOS/Linux, self-healing: installs missing Go/Rust/git
./scripts/setup.ps1       # Windows

See Contributing for the full dev-loop setup.

---

The problem: context fragmentation

As coding agents get more specialized, the bottleneck stops being any single model and becomes the handoff between them. An agent hits a usage limit, or you want a different model for the next step, and the intent, the plan, the half-finished edits, and the "do not redo this" knowledge evaporate. You paste context by hand and hope.

Relay treats the handoff as a first-class, signed protocol. When an agent hits a wall, Relay pauses it at a safe point, serializes what it was doing into a signed continuation contract, and resumes a fresh agent, account, or provider from that contract, with no lost state.

sequenceDiagram
    participant A as Agent A (Claude)
    participant R as Relay
    participant C as Continuation Contract (signed)
    participant B as Agent B (Codex)
    A->>R: stream events (intent, plan, files, tokens)
    Note over A: hits usage limit / overload
    R->>A: request safe pause (at a git commit)
    R->>C: serialize + HMAC-sign<br/>(prompt, plan, tasks left, in-flight code)
    R->>B: dispatch contract as system context
    B-->>R: heartbeat (resumed)
    Note over B: continues the same task, no lost context

Why Relay?

Most devs juggle several AI coding subscriptions because it's cheaper than burning API credits. The pain: when one agent hits its limit mid-task, the work stalls and the context is lost. Relay fixes that. It's built for subscription arbitrage, keeping the work flowing across every account and provider you own.

relay detect          # find every AI agent already running on this machine
relay detect --adopt <id> --target codex --start   # lift its work, continue on another agent

| Feature | Description | | :--- | :--- | | Detect running agents | Scans processes + on-disk transcripts. Surfaces each session's prompt, plan, tasks-left, files, skills, MCPs and token usage. Claude Code, Codex, Copilot (CLI + VS Code), Cursor, Cline, Continue, Antigravity. | | Adopt and port | One command lifts a detected session into a signed continuation contract and resumes it on another agent. From the desktop app or relay detect --adopt. | | Account auto-failover | Claude account A exhausted? Relay resumes on account B, same model, $0 of API credit, then crosses to another provider only when all your logins are spent. | | Quota wallet | Every provider + account's remaining quota, reset time, and burn-rate ETA in one panel. Route the next task to whoever has headroom. | | Predictive handoff | Forecasts time-to-exhaustion from live burn rate and hands off at a safe point before the wall, no work lost mid-edit. | | Time machine | Every handoff snapshots git + a signed contract. Diff what each agent did; non-destructively rewind to any step. | | Pipeline designer | Compose multi-agent DAGs in the UI: an agent per part, explicit ordering, fallback-on-snag routing. | | Continuation contract | HMAC-signed Markdown + JSON carrying goal, plan, decisions, constraints, file manifest, in-flight code. Survives provider boundaries. | | Knowledge + code graph | SQLite store of decisions/constraints/files + a one-shot symbol scan (Go, Rust, TS, Py, Java), searchable via FTS5 at /api/retrieval. | | Secret redactor | AWS / OpenAI / Anthropic / GitHub / JWT patterns scrubbed before anything crosses a boundary. | | MCP server | relay mcp exposes the whole API as tools, so any MCP client (Claude Desktop, Cursor, Cline) can drive Relay. |

Provider matrix

| Provider | Install | Auth | Local/Cloud | |---|:---:|:---:|:---:| | Claude | npm | claude login | Cloud | | Codex | npm | API Key | Cloud | | Antigravity | manual | manual | Cloud | | OpenCode | brew/npm | API Key | Cloud | | Ollama | brew/winget | - | Local | | GitHub Copilot | gh ext | gh auth login| Cloud | | Continue / Cline| VS Code | ext | Both |

Auto-detected on first probe via PATH, Extensions, npm, brew, or winget.

Architecture

graph TD
    User([You]) -->|relay run| CLI(CLI)
    User -->|Open App| UI(Desktop<br/>Electron or egui)
    CLI <--> Daemon(Relay Daemon<br/>HTTP :4748)
    UI <--> Daemon

    Daemon --> Orch(Orchestrator<br/>FSM, Handoff, Redactor)
    Orch <--> Graph[(Knowledge Graph<br/>SQLite)]
    Orch --> Audit[(Audit Log)]

    Orch --> Adapters(Adapter Registry)
    Adapters -->|Streams| Claude[Claude]
    Adapters -->|Chat| Codex[Codex]
    Adapters -->|API| Ollama[Ollama]
    Adapters -->|Ext| Copilot[Copilot]

See Architecture Docs for the full picture, including the handoff state machine.

Use with another LLM client (MCP)

Relay also runs as a Model Context Protocol server. Any MCP-aware client (Claude Desktop, Cursor, Cline, Continue) can call into Relay to hand off, query session state, retrieve code context, send replies.

// Claude Desktop config
{
  "mcpServers": {
    "relay": {
      "command": "relay",
      "args": ["mcp"]
    }
  }
}

The handoff contract (the protocol)

The unit Relay standardizes is the continuation contract: an HMAC-signed document (Markdown for humans + a JSON sidecar for machines) that any agent can be resumed from. Schema v2 carries:

• initialPrompt: the original ask, verbatim
• plan / tasksRemaining: the plan as the source agent tracked it, and what is left
• skillsLoaded / skillsInUse: capabilities the session had
• inFlightCode: files mid-edit with truncated snippets
• decisions / constraints / doNotRedo: hard-won context that must survive the boundary

It is signed with the project's .relay/.signing-key, so a receiving agent can verify the contract was produced by your Relay and not tampered with in transit. See docs/architecture.md for the full schema.

See the handoff

The handoff is runnable today from the CLI:

# Force a handoff early to watch the full cycle on one task
relay run "refactor the orders service" --force-handoff 0.5

# Or lift an agent that is ALREADY running and continue it on another provider
relay detect --adopt <id> --target codex --start

Watch the handoff events stream in the TUI (relay tui) or the desktop app.

Roadmap

• Contract schema v3: richer memory (embeddings-backed retrieval is scaffolded in internal/codegraph).
• More agent adapters and community-contributed detection for new session stores.
• A published, versioned spec for the continuation contract so third-party agents can emit and consume it directly.
• Persistence layer options for the knowledge graph beyond local SQLite.
• Code signing for the desktop installers, so first launch stops tripping SmartScreen and Gatekeep