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

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

---

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

Loading

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]

Loading

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 Gatekeeper.
• Desktop builds for Intel macOS and Linux ARM64 (the release currently covers Apple silicon and Linux amd64).

Documentation

• Getting started
• Architecture
• Providers
• Profiles and routing
• Vision fallback
• Security and privacy
• API reference
• CLI reference
• Terminal UI guide
• MCP server
• Code signing policy

Repo map for contributing agents: CODEMAP.md. Agent rules: CLAUDE.md / AGENTS.md.

Code signing policy

Release binaries and installers are not code signed yet. Windows SmartScreen and some antivirus tools will warn on first run as a result; click "More info" then "Run anyway", or verify the download against SHA256SUMS first if you want assurance beyond that.

Relay applied to SignPath.io's free open source signing program (certificates from SignPath Foundation) and was told the project needs more public usage history to qualify. The team-roles structure below is the precondition SignPath requires before reapplying.

• Committers and reviewers: repository maintainers. Changes from outside the maintainers arrive as pull requests and are reviewed before merge.
• Approvers: repository owner. Once signing is active, every release will be approved manually before it is signed.

Relay runs locally and will not transfer any information to other networked systems unless specifically requested by the user or the person installing or operating it. It orchestrates AI coding agents you have already installed and signed into, and those agents talk to their own providers under their own privacy policies. Full detail, including how to verify a download against SHA256SUMS, is in the code signing policy.

Contributing

Contributions are welcome. See the Contributing Guide and Code of Conduct. The setup script is self-healing: it installs any missing toolchain (Go, Rust, git) before building.

git clone https://github.com/dbisina/relay
cd relay

# One-shot setup (installs missing tools automatically)
./scripts/setup.sh        # macOS/Linux
./scripts/setup.ps1       # Windows

# Dev loop
./scripts/dev.sh          # daemon + UI in parallel

License

Apache-2.0. See LICENSE. Built on top of work from Anthropic Claude Code, OpenAI Codex CLI, Ollama, egui, Electron, React, and Bubble Tea. Provider marks in the desktop app come from simple-icons and remain the trademarks of their owners. Full credits in OPEN_SOURCE.md.