Agent Relay
Keep your coding agent moving when one account hits its usage limit. Agent Relay supervises isolated Claude and Codex profiles, keeps exactly one owner per conversation, and moves the work to the next eligible profile in one priority order. Claude → Claude continues the same native Claude session; anything involving Codex continues from a Relay state bundle in a new session — never the same native conversation across the two CLIs.
Status: v0.4.1, macOS-first. The handoff, recovery, and usage-detection paths are validated live on macOS with Claude Code 2.1.276–2.1.278; Codex support was checked live against Codex CLI 0.155.0 (structured usage reads, thread verification, Codex → Claude handoff by hand, pre-launch fallback from an exhausted Codex profile). Automatic handoff from a real Codex exhaustion mid-session has now been observed live: detection and evaluation ran correctly against a genuine exhaustion, though that specific incident had no eligible fallback available to hand off to (every configured fallback was independently exhausted at the same time) — see docs/automatic-handoff.md for the diagnostics that case now produces. A full live handoff away from a real Codex exhaustion (to a healthy fallback) is still covered by fake-provider tests rather than observed live. Linux builds and passes the tests in CI but is not yet live-supported or validated (some process-scan code is macOS-specific). Relay runs entirely standalone — no separate tool required; an optional Herdr integration exists for people already using Herdr (see "Is Herdr required?"), also validated live.
Install
brew install RA1NM4KER/tap/agent-relayThis installs the latest tagged release. To run the bleeding-edge main branch instead, build it from source (see below), or see docs/maintainer-dogfood.md for the maintainer's own dogfood-build workflow.
Use
relay setup # once: profiles for the providers you use, one priority order
cd ~/repos/my-project
relay claude # start a new managed conversation with Claude ...
relay codex # ... or with Codex (peer entry points — use whichever you want)
relay claude --resume # adopt an OLD Claude conversation (pick it in Claude's own picker)
relay resume # reopen a closed conversation of this project
relay switch # choose a profile from a list ...
relay switch <profile> # ... or name it: move a conversation to another profile
relay status # fast local snapshot: what is going on in this projectrelay profiles # your profiles, their order and login state
`relay setup` is a one-time wizard: it detects the coding-agent CLIs you have (Claude Code and/or
the Codex CLI — either one is enough), walks you through logging in to one or more **isolated**
profiles (Relay opens each provider's own official login — it never sees your password or token),
and asks for **one global priority order**: which profile is primary and which are fallbacks.
(If you already use [Herdr](https://herdr.dev), setup also offers to wire in that optional
integration — see ["Is Herdr required?"](#is-herdr-required); most people don't need it.)
Any provider can be primary; a Codex primary with a Claude
fallback is as natural as the reverse.
The mental model is simple:
relay claude = Claude + Relay supervision (new managed conversation) relay codex = Codex + Relay supervision (new managed conversation) relay claude --resume = bring an existing Claude conversation under Relay (same session, in place) relay resume = reopen a closed (dormant) conversation of this project relay switch [<profile] = explicitly move a conversation (bare: pick from a list)
**Start through Relay, or bring an existing conversation under Relay later.** Switch accounts and
providers without leaving your coding workflow:
- `relay claude` / `relay codex` start through Relay.
- `relay claude --resume` adopts an **old** Claude conversation: Relay opens Claude's own resume
picker (or resumes the id you give it), then manages exactly the conversation you chose — no fork,
no second conversation. It is not the same as `relay resume`, which continues a conversation Relay
*already* manages.
- Inside a running Claude session, `/relay status`, `/relay switch [profile]` and `/relay adopt`
are answered by Relay itself (no model turn, nothing typed into the conversation).
`/relay adopt` brings a **live** unmanaged Claude conversation under Relay without restarting it;- Inside a Relay-managed Codex session, use $relay status, $relay doctor,
$relay why, $relay history, or $relay switch <profile. Relay installs a profile-local skill when attaching Codex; Codex executes the CLI through a model/tool turn. /relay and /relay:doctor are not Codex slash commands. The skill scopes queries to the supervisor's project and session; $relay switch <profile asks the supervising Relay process itself, over the same control channel Claude's in-agent switch uses, to safely stop Codex and continue the conversation on the new profile — no copy-pasting a command into another terminal. It falls back to printing that manual command only when no verified Relay supervisor can be reached. Live Codex adoption is not offered — use relay codex to start through Relay.
relay history is a fast, local read-only timeline for the most recent Relay Session in the current project (or use --session for a dormant session). It shows durable operational evidence such as handoff phases and selected profiles; it is provider-neutral and not conversation or transcript history. It never starts a provider or contacts the network.
- Relay supervises conversations, not repositories. A project can hold many Relay sessions
— each one a conversation with its own stable id, running on one profile at a time. Two sessions may run on the same profile; one may be Claude and another Codex; some may be closed. Each live session has exactly one owner; a closed one has none (it is remembered, not owned). Relay does not serialize edits to your files: two agents in one working tree can touch the same files, so it is your call when running several at once makes sense.
- relay claude always starts a new Relay session under your highest-priority Claude profile,