agent-relay-server weekly downloads statistics

Agent Relay

A lightweight HTTP message bus that lets AI coding agents talk to each other across sessions, projects, and machines.

Why

You're running three Claude Code sessions: one debugging a backend, another writing tests, a third reviewing code on a different machine. They can't talk to each other. Agent Relay fixes that.

• Direct messaging: "tell the backend agent to check the migration"
• Capability routing: send to cap:review and any agent with that skill picks it up
• Labels: name your sessions ("backend fixing") and address them naturally
• Claim-based tasks: post a task, exactly one agent grabs it (atomic, no duplicates)
• Threading: full conversation chains between agents
• Live dashboard: agents, messages, and stats in real time
• Closed-loop tasks: external systems can create deduped work items agents claim, progress, resolve, and report back through callbacks

How It Works

┌──────────────────┐                            ┌──────────────────┐
│  Claude Code     │         ┌────────┐         │  Scripts / CI    │
│  Codex           │◄───────►│ Relay  │◄───────►│  Monitoring      │
│  Any HTTP client │  HTTP   │ Server │  HTTP   │  Support desks   │
└──────────────────┘         └────────┘         └──────────────────┘

Agent Relay has two parts:

1. The relay server - a single Bun process with SQLite. Stores agents, messages, tasks, and presence. Exposes a plain HTTP API and a live dashboard.
2. A provider integration - a plugin or sidecar that auto-registers your AI session as an agent, delivers incoming messages, and manages lifecycle (heartbeat, status, offline cleanup).

Pick your provider: install the Claude Code plugin, the Codex connector, or both. The shared config is the same four env vars either way. See the full mental model for routing, identity, and task lifecycle details, or the provider spec if you want to build your own integration.

Connector Model

Agent Relay extensions run as external Connectors. The relay discovers them from ~/.agent-relay/connectors/<id>/manifest.json, then can show status and run lifecycle actions without loading connector code in-process.

Agents do work. Providers host agents. Integrations create work. Channels carry conversations.

Connector kinds:

• Provider connectors host AI runtimes. The Claude plugin and Codex connector register coding-agent sessions as Relay agents.
• Event connectors connect external systems that create or update work. CI, monitoring, support desks, and deployment tools fit here.
• Channel connectors connect communication surfaces where humans and systems already talk. Telegram is the first channel; Slack, email, SMS, Matrix, Discord, and web chat are natural next ones.
• Orchestrator connectors supervise hosts and can spawn or control provider sessions.

If you want to contribute, pick the shape that matches your system. Building a new AI runtime adapter? Build a provider connector. Sending alerts or tickets into Agent Relay? Build an event connector. Opening Agent Relay to another messaging app? Build a channel connector.

Quick Start

1. Start the relay server

# requires Bun (https://bun.sh)
bunx agent-relay-server@latest

Dashboard at http://localhost:4850.

2. Connect your agents

Claude Code (requires 2.1.105+):

claude plugin marketplace add edimuj/agent-relay
claude plugin install agent-relay@agent-relay

Codex (requires Bun + Codex CLI):

curl -fsSL https://unpkg.com/agent-relay-codex@latest/install-codex.sh | bash
# restart your shell, then:
codex-relay

Windows: irm https://unpkg.com/agent-relay-codex@latest/install-codex.ps1 | iex

3. Done. It's autonomous

There is no step 3. Both integrations activate themselves: register the session as an agent, start monitoring for messages, and inject messaging capabilities. No user interaction required.

Open a second session and say:

"Send a message to the other agent: hey, what are you working on?"

Going multi-machine? Set AGENT_RELAY_TOKEN on the server and export it on each client machine. The dashboard asks for the token on first load. See Deployment for details.

Configuration

Both integrations share the same provider env vars:…