How to Use Agent Relay: The Beginner's Guide (Hand Off Work Between Coding Agents Without Losing Context)

CodexFuse Team · 2026-11-03T10:32:57.218Z · 14 min read min read

Agent Relay is a local-first CLI that hands work from one coding agent to another without losing context, decisions, or validation state. This beginner's guide covers install, first handoff, chat mode, race mode, and resume packets.

You are coding with Claude Code at 11 p.m. when the rate limit hits mid-refactor. The session is long, the context is rich, and the usual fix is the ugly one: copy the conversation summary into a new window and hope the next agent picks up where you left off. Learning how to use Agent Relay replaces that copy-paste ritual with a proper handoff. Agent Relay is a local-first CLI that hands work from one coding agent to another without losing context, decisions, or validation state. Run relay, type /use codex, and the new agent starts from a resume packet built from the old session — not from your best attempt at summarizing it.

This agent relay tutorial walks you from a fresh shell to your first handoff, then through chat mode, race mode, resume packets, and the rate-limit automation that makes the tool worth installing. If you have never run a coding agent in a terminal before, the Claude Code beginner guide is the right warm-up; everything here assumes you can launch at least one supported agent.

What Is Agent Relay, Exactly?

Agent Relay is an open-source toolkit that gives engineering teams infrastructure for running coding agents together, without replacing the agents and tools they already use. That is the project's own description from its GitHub repository, and it captures the design philosophy: Agent Relay does not ask you to adopt a new agent. It sits between the agents you already run — Claude Code, Codex, Gemini, Kimi Code, and OpenCode — and moves work between them.

There are two flavors of the product, and beginners mix them up constantly, so get this straight first. The Python CLI (PyPI package agent-relay-tool, docs at agent-relay.dev, current 0.7.x line) is the durable open-source core this guide covers: install it, run relay, hand work between agents on your own machine. The newer team product (npm package, Node.js 22+, launched around October 27, 2026) lets agents DM each other across machines with hosted workspaces, plus a paid desktop app that adds shared sessions and cross-agent communication. Same company — Agent Workforce Incorporated, San Francisco — different stacks. This guide leads with the Python CLI and adds a section on the team product so you can tell them apart.

How Do You Install Agent Relay?

The install takes about two minutes if Python 3.11 or newer is already on your machine. Agent Relay ships as the PyPI package agent-relay-tool, and every install route in this section is straight from the vendor's own installation walkthrough, which promises each path goes from a fresh shell to working relay and agent-relay commands.

1. Check your Python. Run python3 --version and confirm 3.11 or newer. The PyPI page states it plainly: Python 3.11 or newer is required. Install a newer Python first if you are short.
2. Install the package. On macOS or Linux, the fastest route is the installer script: curl -fsSL https://agent-relay.dev/install.sh | sh. Homebrew users run brew tap bethvourc/tap, then brew install agent-relay. On Windows it is irm https://agent-relay.dev/install.ps1 | iex. Python-native users can go pipx install agent-relay-tool or uv tool install agent-relay-tool instead.
3. Wire the hooks. Run relay install. This wires supported local hooks, registers or starts the daemon, and tries to infer the automatic fallback order your agents will use after rate limits. The installer is idempotent — re-running it later upgrades in place instead of breaking anything.
4. Verify the commands. Run relay to enter the REPL, and agent-relay discover to list every agent the tool can see on your machine, along with the one-letter aliases: c for Claude, x for Codex, g for Gemini, k for Kimi, o for OpenCode.
5. Set your fallback chain (optional but recommended). If you already know which agent should catch work when your main one stalls, declare it up front: relay install --handoff-order claude codex gemini. Inside the REPL the same thing is /handoff-order claude codex gemini kimi opencode.

What Does Your First Handoff Look Like?

The beginner path runs inside the REPL. Open a terminal in your repo, run relay, and you are in. Type /use claude and give it work: "Fix the failing tests." Claude starts working as usual — except Relay is now watching the session. Midway through, the rate limit warning appears. Instead of copying anything, type /use codex and continue: "Continue the release prep from the current Relay session." The default agent relay claude code to codex arc is the pairing most beginners run first: work in Claude until the limit, then hand to Codex with full context.

Here is what happened between those two commands. Agent Relay captured a structured checkpoint, rendered an immutable resume packet, and recorded the launch-and-resume flow in a repo-local session journal. The Codex session did not start from your summary of the Claude session — it started from Relay's own record of it. The vendor's rule of thumb is worth memorizing: switch agents with /use claude, /use codex, or /use gemini, and if there is live context, Relay routes the switch through the handoff machinery so the target starts with a resume packet.

You do not have to live in the REPL. The one-command relay hands off from outside it: agent-relay codex --task "Continue the release prep". And a single agent can be driven scriptably with agent-relay run c "Fix the failing tests". If Codex is not part of your workflow yet, the Codex beginner guide will get you oriented on the agent itself before you start handing it work.

What Do Resume Packets Actually Carry?

A resume packet is the reason handoffs feel like continuation instead of restart. When Relay managed the session, the packet carries everything the next agent would have needed to sit in the room the whole time.

On disk, Relay keeps all of this under .agent-relay/sessions/<session-id>/: a session.json immutable manifest, an append-only journal/ event log, objects/checkpoints/, objects/handoffs/<handoff-id>/ (the resume packet, its hash, and the launch specification), objects/launches/, and turns/. Two rules follow from that layout. First, the vendor's honest caveat: if Relay was there while the work was happening, handoffs are much stronger — if Relay joins later, it can only hand off what it can still see. Always start the session from relay, not from the raw agent. Second, do not commit .agent-relay/ to git. Add it to .gitignore; the directory can hold local paths, notes, and full agent output you do not want in version control.

Chat Mode vs Race Mode: Which Do You Need?

One-command relays and /use switches move work from one agent to the next. Chat mode and race mode put multiple agents on the same work at once — for different shapes of problems.

Chat mode runs agents in alternating turns, and each agent sees the full conversation history — what every other agent said, decided, and proposed. The canonical example from the docs is one agent investigating and another implementing. The run caps at ten turns by default; agent-relay chat c x c "Review and fix" -n 6 trims it to six.

Race mode is a phased concurrent workflow, not two agents launched side by side. It enforces a structured process in four phases: planning (every agent must claim a concrete slice before implementation), implementation (each agent works inside its own isolated git worktree), merge and review, and conflict handling (Relay saves conflict artifacts, can run an automatic resolver or reviewer pass, and hands off to resolve). Agents claim roles — owner, shared, reviewer — and the default time cap is 600 seconds. When conflicts land, agent-relay resolve --latest picks up the newest session and agent-relay inspect-conflicts <session-id> shows you exactly what collided. Because race mode leans on git worktrees, a working grasp of branching helps; the Git beginner guide covers the mental model in plain language.

How Does Agent Relay Handle Rate Limits?

Rate limits are the founding use case — the vendor describes the CLI as built for the moment one agent needs to stop because of rate limits, tool limits, or a manual handoff. There are three layers to it. First, relay install wires local hooks so the REPL listens for daemon rate-limit handoff events; when a limit is detected, Relay can switch agents automatically along your configured order instead of waiting for you to type /use. Second, you can interrogate the plan before it matters: agent-relay handoff plan --agent claude answers who would take over if Claude ran out right now, and why not the others. Third, agent-relay limits shows real subscription usage for the agent CLIs — Claude's five-hour and weekly windows, Codex's quota — so the automation is working from measured state, not guesses.

What Are the Six Workflow Patterns?

The vendor's blog documents six workflow patterns for orchestrating agents, and they are worth knowing because they map directly onto the CLI modes you just learned. One caveat first: the post dates to mid-2026 and its code samples use the npm/TypeScript form (agent-relay local run workflows/my-workflow.ts, the @relayflows/core package) — the pattern concepts apply to the Python CLI's chat and race modes, even though the syntax in the post will not paste into your terminal.

The vendor's meta-rule for choosing between them: pick the topology first, then agents, then gates. If you want a single assistant that iterates with you in a pair-programming style rather than a relay between specialists, the Aider beginner guide covers that lane — it is the closest pillar to this page's territory.

Agent Relay vs Parley vs Comity: What's the Difference?

This lane has a naming problem, and searching the wrong name costs you an afternoon. On the agent relay vs comity question, the answer is simple: different products, same company. Comity is the coordination layer for a team's coding agents — "Everyone keeps their own agent; Comity makes them one team." Where Agent Relay hands work between agents with resume packets, Comity coordinates a team's agents with shared task lists, pre-code conflict detection ("Two agents heading for the same function, API or table both get warned before either writes a line"), and handoffs that keep the plan, files, what was tried, and what is left. Its listed price is $0.

Parley is not Agent Relay at all — it is at least four different products sharing a name, and one is a genuine lookalike. The closest is parley.weldra.dev, which connects a team's coding agents across people, machines, and vendors over MCP so they hand work to each other (free for two agents, Pro at $19 per workspace per month). The others are further away: a PyPI package called agent-parley that runs several coding agents in one repo, each in its own worktree, recording claims and handoffs; a small open-source Go tool that puts your Claude Code, Codex, and OpenCode sessions in one IRC channel on your own machine, with you in it; and a hosted "AI agent teams" site at agentparley.ai with nothing to install. None of these is Agent Relay, and the IRC-channel one is the most likely name-collision trap in search results.

The collisions go further, so here is the short disambiguation list. The PyPI package agent-relay-tool (this guide, Python CLI, agent-relay.dev) and the npm package agent-relay (Node.js 22+, team product, agentrelay.com) are the same company on different stacks. On PyPI you will also trip over agentrelay-cli (a drop-in OpenAI/Anthropic API server that routes through agent CLIs), agentrelay-protocol (a task-verification layer, not handoffs), and agent-session-relay (whose CLI is also named relay — a direct command-name collision, so check which relay is on your PATH). AffixIO's Agent Relay is a zero-trust authorization product for agents talking to other organizations' agents — different problem entirely. And github.com/saranyan/agent-relay is a separate small October-2026 prototype (ten stars, one session leads while the other follows), not the 1,089-star agentworkforce/relay repository this guide is about. The infrastructure noise — DHCP relay agents, Tenable Secure Relay, HCL agent relays — is unrelated to coding agents and only appears because "relay" is an overloaded word.

Agent Relay Pricing: Is It Free?

The Python CLI is free and open source under the Apache 2.0 license — the GitHub repository (agentworkforce/relay, 1,089 stars, 96 forks, active YC F2026 listing with two employees in San Francisco) verifies that, and self-hosting is the default posture. The company's YC listing phrases the hosted side as "use our hosted version free, or self-host the open-source version." The paid tier exists — an upgrade to the paid Agent Relay desktop app adds shared sessions and cross-agent communication — but no price is published on the pages checked for this guide, so treat any dollar figure you see elsewhere as unverified until the vendor posts it.

5 Beginner Mistakes That Break Your Handoffs

Sources

Every fact in this guide was verified against pages fetched on November 3, 2026: the PyPI page for agent-relay-tool (0.7.7, August 12, 2026); the Agent Relay installation walkthrough at agent-relay.dev; the team product getting-started docs at agentrelay.com; the vendor's six workflow patterns blog post (June 2026, Relayflows era); the agentworkforce/relay GitHub repository (1,089 stars, Apache 2.0); the Y Combinator directory listing for Agent Relay (F2026, active); comity.so for the Comity comparison; parley.weldra.dev for the closest Parley lookalike; and The Tool Nerd's October 27, 2026 AI tools roundup for launch-week context. The paid desktop app's price was not published on any page checked and is not stated here.

Frequently Asked Questions

Is Agent Relay free?

The Python CLI is free and open source under the Apache 2.0 license — install it from PyPI, self-host it, no account required. The company's hosted version is also described as free, and a paid desktop app with shared sessions exists, though its price is not published on the vendor's pages.

Which coding agents work with Agent Relay?

The built-in adapters cover Claude Code, Codex, Gemini, Kimi Code, and OpenCode, with one-letter aliases c, x, g, k, and o. Run agent-relay discover to see exactly which agents Relay can find on your machine right now.

What happens if Agent Relay was not running when the work started?

You get a weak handoff. Relay can only hand off what it can still see, so a session that began outside relay produces a thin resume packet. Start every session from relay if you plan to hand it off later.

Is Agent Relay the same as Parley?

No. Parley is several different products sharing a name — the closest lookalike is parley.weldra.dev, a team-agent connector over MCP — while Agent Relay is the Apache-2.0 open-source CLI and team product from Agent Workforce Incorporated. The LockerGnome-covered Go tool that puts agent sessions in one IRC channel is another unrelated Parley.

What is the difference between the PyPI CLI and the npm team product?

The PyPI package agent-relay-tool is the Python CLI for handing work between agents on your own machine. The npm package agent-relay (Node.js 22+, launched October 2026) is the newer team product where agents DM each other across machines with hosted workspaces. Same company, different stacks, different install commands.