agent-relay
vinnyusestrict/agent-relay
Inter-agent messaging relay for Claude Code sessions
Instalação
npx convez-ai vinnyusestrict/agent-relay1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
README
A tradução para o português deste README ainda está na fila.
Agent Relay
Lightweight inter-agent messaging for AI coding agents. Enables multiple agents to send messages to each other across separate terminal sessions, VMs, containers, or any environment where agents run.
Works with any AI agent that can execute shell commands — Claude Code, Cursor, Windsurf, Cline, Aider, custom agents, or plain scripts.
Quick Start
1. Install
git submodule add https://github.com/vinnyusestrict/agent-relay.git lib/relay
Or clone directly:
git clone https://github.com/vinnyusestrict/agent-relay.git
2. Configure the database
Two backends supported. Pick one:
Option A — SQLite (zero deps, single file — good for solo setups):
# .relay-env
RELAY_DB_DRIVER=sqlite
RELAY_DB_PATH=~/.agent-relay.sqlite3
No server install needed. The file is auto-created on first use.
Option B — MySQL / MariaDB (default; good for multi-host / networked setups):
mysql -u root -proot -e "CREATE DATABASE IF NOT EXISTS agent_relay"
# .relay-env
RELAY_DB_USER=root
RELAY_DB_PASS=root
RELAY_DB_NAME=agent_relay
Either way: .relay-env lives in the relay directory (or your project root), is gitignored, and tables are auto-created on first use.
3. Register agents
Every agent registers itself with a unique name:
python3 lib/relay/relay-msg register alice \
--cwd /path/to/alice-workspace \
--group backend \
--transport local
| Flag | Description |
|---|---|
--group <name> | Join a broadcast group (repeatable) |
--cwd <pattern> | Substring matched against working directory for auto-detection |
--transport local|remote | local = direct MySQL, remote = proxied (see below) |
--alias <name> | Alternate name this agent also receives messages for (repeatable) |
4. Send and receive
# Send to a specific agent
./relay-msg send alice "PR #37 is ready to merge"
# Send to a group
./relay-msg send backend "Deploy complete"
# Broadcast to all
./relay-msg send all "Going offline for maintenance"
# Check for unread messages (marks as read)
./relay-msg check
# Peek without marking as read
./relay-msg check --peek
# View full history
./relay-msg check --history
5. Set up auto-check (optional)
For agents that support hooks or startup scripts, auto-check on every prompt so incoming messages appear automatically.
Claude Code — add to .claude/settings.json:
{
"hooks": {
"UserPromptSubmit": [
{
"matcher": "",
"hooks": [
{
"type": "command",
"command": "python3 lib/relay/relay-msg check 2>/dev/null || true"
}
]
}
]
}
}
Cron / polling — check every N seconds:
# In a crontab or background loop
* * * * * python3 /path/to/relay-msg check 2>/dev/null
Custom agents — call from your agent's message loop:
import subprocess
result = subprocess.run(
["python3", "lib/relay/relay-msg", "check"],
capture_output=True, text=True
)
if result.stdout.strip():
# Feed messages into the agent's context
print(result.stdout)
Commands
| Command | Description |
|---|---|
relay-msg send <target> <message> | Send to an agent, group, or all |
relay-msg check | Read unread messages (marks as read) |
relay-msg check --peek | Read without marking as read |
relay-msg check --history | Show all messages including read |
relay-msg register <name> [opts] | Register or update an agent |
relay-msg unregister <name> | Remove an agent |
relay-msg list | List all agents, groups, and aliases |
Identity Detection
When an agent runs a command, identity is resolved in order:
RELAY_IDENTITYenv var — always wins- CWD pattern matching against registered agents'
cwd_pattern - Falls back to
"default"
Remote Transport
For agents in VMs or containers without direct MySQL access, register with --transport remote and configure a proxy:
# In .relay-env
RELAY_TRANSPORT=remote
RELAY_PROXY_CMD=ssh myhost mysql
The proxy command receives the full mysql -u ... -e '...' invocation. If it contains {}, the MySQL command replaces the placeholder; otherwise it's appended.
Wake-up nudges (optional)
An agent waiting for a message has no way to know one arrived until something wakes its session (a user prompt, a scheduled poll). For faster turn-around, relay-msg send can drop a flag file as a post-INSERT side-effect, and a separate watcher process picks up the flag and wakes the receiver's terminal pane.
Enable by setting two env vars in .relay-env:
RELAY_NUDGE_DIR=/path/to/shared/nudge-dir
RELAY_NUDGE_AGENTS=alice,bob,carol # allowlist; unset = nudge everyone
When alice sends to bob, relay writes /path/to/shared/nudge-dir/.nudge-bob with the content check inbox\n. If RELAY_NUDGE_DIR is unset, the side-effect is skipped — no behavior change from the default.
Flag-file contract (for writing your own watcher):
- Filename:
.nudge-<agent-name>in$RELAY_NUDGE_DIR. - Contents: a single line of text (default:
check inbox). Your watcher sends this text to the agent's pane. - Watcher is expected to
rm -fthe flag after consuming. - Best-effort:
relay-msgsilently swallowsOSErroron write. Nudges are a wake-up optimization, not part of the delivery guarantee.
Reference watchers in watchers/:
cmux-nudge-watcher— injects keystrokes to cmux panes (only example; ships as template).tmux-nudge-watcher—tmux send-keysto a window/pane named after the agent.notify-nudge-watcher— macOS notification only (no keystroke injection). Useful for agents in GUI apps like Claude Desktop with no pane to type into.
Write your own watcher in any language — it's a plain directory-polling contract.
Environment Variables
All configurable via .relay-env file or environment variables (env vars take precedence).
| Variable | Default | Description |
|---|---|---|
RELAY_DB_DRIVER | mysql | mysql or sqlite |
RELAY_DB_USER | root | MySQL user (mysql only) |
RELAY_DB_PASS | root | MySQL password (mysql only) |
RELAY_DB_NAME | agent_relay | MySQL database name (mysql only) |
RELAY_DB_PATH | ~/.agent-relay.sqlite3 | SQLite file path (sqlite only) |
RELAY_IDENTITY | (auto-detect) | Force agent identity |
RELAY_TRANSPORT | local | local or remote (mysql only) |
RELAY_PROXY_CMD | (none) | Proxy command for remote transport (mysql only) |
RELAY_NUDGE_DIR | (unset) | Directory to drop .nudge-<agent> flag files (unset = nudges disabled) |
RELAY_NUDGE_AGENTS | (all) | Comma-separated allowlist of agents to nudge |
Database
Four tables, auto-created on first use:
| Table | Purpose |
|---|---|
relay_agents | Registered agents (name, transport, cwd_pattern) |
relay_agent_groups | Agent-to-group memberships |
relay_agent_aliases | Alternate names an agent responds to |
relay_messages | Message queue with read tracking |
Messages are never deleted — marked as read via read_at timestamp.
Requirements
- Python 3.8+
- One of:
sqlite3CLI client (for SQLite backend — usually preinstalled on macOS / Linux)mysqlCLI client + MySQL or MariaDB server (for MySQL backend)