Agent Relay

Installation

Agent Relay ships as a Python package on PyPI as agent-relay-tool and requires Python 3.11 or newer. Pick the path that matches your setup below — each one is a complete walkthrough from a fresh shell to working relay and agent-relay commands.

macOS

Tested on macOS 12 Monterey and newer, both Intel and Apple Silicon.

  1. Check your Python version

    macOS ships with an older system Python. Confirm you have 3.11+ available (install via brew install python@3.12 if not).

    terminal
    python3 --version

    You should see Python 3.11.x or higher. If the system Python is older, install a newer one with Homebrew before continuing.

  2. Run the installer

    The installer bootstraps uv if it's missing, then installs Agent Relay into its own isolated environment and drops relay and agent-relay on your PATH.

    terminal
    curl -fsSL https://agent-relay.dev/install.sh | sh

    No sudo is required — everything lands under ~/.local/.

  3. Reload your shell

    The installer appends ~/.local/bin to your PATH in ~/.zshrc. Either start a new terminal tab or source it manually:

    terminal
    source ~/.zshrc

  4. Verify the install

    terminal
    agent-relay --version

    Expected output: a version line like agent-relay 0.7.0.

    If `agent-relay: command not found`

    The installer couldn't write to your shell config, or you're using a non-default shell (fish, nu, etc). Add the install directory to your PATH manually:

    terminal
    echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

Post-install setup

After any install method, run this once from a repo where you use coding agents:

terminal
relay install

This wires supported local hooks, registers or starts the daemon, and tries to infer the automatic fallback order used after rate limits. Then start the interactive layer:

terminal
relay

If Relay cannot infer your preferred fallback chain, set it explicitly:

terminal
relay install --handoff-order claude codex gemini

Upgrading

Each install path has its own upgrade command. Run whichever matches the path you used above.

terminal
# macOS / Linux
curl -fsSL https://agent-relay.dev/install.sh | sh
terminal
# Windows
irm https://agent-relay.dev/install.ps1 | iex

The installer is idempotent — re-running it upgrades in place.

Uninstalling

Remove the binary and (optionally) the install directory:

terminal
# macOS / Linux
rm ~/.local/bin/agent-relay
terminal
# Windows
Remove-Item "$env:USERPROFILE\.local\bin\agent-relay.exe"

What's next

Quickstart

Run your first agent handoff in five steps.

Sessions

Understand what gets captured under .agent-relay/.