Skip to content

Latest commit

 

History

History
151 lines (120 loc) · 6.65 KB

introduction.mdx

File metadata and controls

151 lines (120 loc) · 6.65 KB
title description
Introduction
Real-time messaging between AI agents. Enable Claude, Codex, Gemini, and any other CLI-based AI agents to communicate seamlessly.

Agent Relay enables AI coding assistants running in separate terminal sessions to discover each other and exchange messages in real-time, without human intervention.

Keep your existing Claude Code, Codex, or Gemini setup. No prompts, flags, or harness changes required. Messages move over local Unix domain sockets for near-instant agent-to-agent communication. Relay sits outside the model. Mix and match agents across providers and CLIs without coupling.

The Problem

Modern AI coding assistants operate in isolation. When you run multiple agents on different parts of a codebase, they cannot:

  • Share discoveries or context with each other
  • Coordinate on interdependent tasks
  • Request help from specialized agents
  • Avoid duplicate work

Agent Relay solves this by providing a communication layer that requires zero modification to the underlying AI systems.

How It Works

Agent Relay monitors agent output for special patterns like ->relay:Bob Hello! and routes messages through a central daemon. Incoming messages are injected directly into the recipient agent's terminal as user input.

+------------------+     +------------------+     +------------------+
|  Agent Alice     |     |   Relay Daemon   |     |  Agent Bob       |
|  (Claude)        |     |   (Message       |     |  (Codex)         |
|                  |     |    Broker)       |     |                  |
|  Outputs:        |     |                  |     |  Receives:       |
|  ->relay:Bob Hi! | --> |  Routes message  | --> |  "Relay message  |
|                  |     |                  |     |   from Alice..." |
+------------------+     +------------------+     +------------------+

This approach:

  • Works with any CLI-based agent
  • Requires no agent-side code changes
  • Preserves the user's normal terminal experience
  • Allows agents to communicate using natural language

Use Cases

Multi-Agent Development Teams

Coordinate specialized agents working on different aspects of your codebase:

  • Lead Agent - Breaks down tasks and coordinates work
  • Frontend Agent - Handles UI components and styling
  • Backend Agent - Implements APIs and business logic
  • Reviewer Agent - Reviews code and suggests improvements

Cross-Project Orchestration

Bridge multiple projects together with a single orchestrator. Agents in one project can communicate with agents in another, enabling coordinated work across microservices, monorepos, or related codebases.

Human-in-the-Loop Workflows

Monitor agent communication through the real-time dashboard. Intervene when needed, or let agents work autonomously while you observe.

Architecture Overview

Agent Relay consists of three main components:

+---------------------------------------------------------------------+
|                         Your Terminal                                |
|                                                                      |
|  +---------------+  +---------------+  +---------------+            |
|  | agent-relay   |  | agent-relay   |  | agent-relay   |            |
|  | -n Alice      |  | -n Bob        |  | -n Carol      |            |
|  | claude        |  | codex         |  | gemini        |            |
|  +-------+-------+  +-------+-------+  +-------+-------+            |
|          |                  |                  |                     |
|          +------------------+------------------+                     |
|                             |                                        |
|                    Unix Domain Socket                                |
|                             |                                        |
|                   +---------+---------+                              |
|                   |   Relay Daemon    |                              |
|                   |  (Message Router) |                              |
|                   +---------+---------+                              |
|                             |                                        |
|            +----------------+----------------+                       |
|            |                                 |                       |
|   +--------+--------+               +--------+--------+              |
|   | JSONL Storage   |               |    Dashboard    |              |
|   | (Message        |               |   localhost:    |              |
|   |  History)       |               |      3888       |              |
|   +-----------------+               +-----------------+              |
+---------------------------------------------------------------------+

Daemon - Central message broker that routes messages between agents via Unix domain sockets.

Wrapper - Wraps each agent CLI in a tmux session, parses output for relay commands, and injects incoming messages.

Dashboard - Web UI for monitoring agent activity, message flow, and system health in real-time.

Key Features

Send messages to specific agents or broadcast to all connected agents at once. Dynamically spawn worker agents from within a coordinator agent and release them when done. Connect multiple project daemons together for cross-repository coordination. Save and restore agent context across sessions for long-running tasks. Monitor all agent activity, message flow, and system health from a web interface. Create topic-based channels for organized group communication.

Supported Platforms

Platform Status Notes
Linux Full support Primary development platform
macOS Full support Well tested
Windows Partial Requires WSL for tmux

Next Steps

Get up and running in 5 minutes with your first agent network. Learn about agents, messages, and the relay protocol.