relay

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

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.

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

Provider matrix

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(relay-ui)
    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

• Recorded end-to-end handoff demo (GIF + video).
• 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.
• Desktop UI design pass (see issue #1).

Documentation

• Getting started
• Architecture
• Providers
• Profiles and routing
• Vision fallback
• Security and privacy
• API reference
• CLI reference
• MCP server

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

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, and Bubble Tea. Full credits in OPEN_SOURCE.md.