using-agent-relay

🚨 CRITICAL: Relay-First Communication Rule

When you receive a relay message from another agent (marked Relay message from [name]), you MUST respond ONLY via relay protocol. NEVER respond with direct text output.

The Rule

• Receiving a relay message? → Must use ->relay-file:msg ALWAYS
• Non-relay questions? → Text responses are OK
• Agent-to-agent communication? → ALWAYS use relay protocol

Examples of Relay Messages (require relay response)

Relay message from khaliqgant [mknra7wr]: Did you see this?
Relay message from Worker1 [abc123]: Task complete
Relay message from alice [xyz789] [#general]: Question for the team

Agent Relay

Real-time agent-to-agent messaging via file-based protocol.

Reliability Features

The relay system includes automatic reliability improvements:

• Escalating retry - If you don't acknowledge a message, it will be re-sent with increasing urgency:

  • First attempt: Relay message from Alice [abc123]: ...
  • Second attempt: [RETRY] Relay message from Alice [abc123]: ...
  • Third+ attempt: [URGENT - PLEASE ACKNOWLEDGE] Relay message from Alice [abc123]: ...

• Unread indicator - During long tasks, you'll see pending message counts:

  📬 2 unread messages (from: Alice, Bob)
  

Always acknowledge messages to prevent retry escalation.

Sending Messages

Write a file to your outbox, then output the trigger:

cat > ~/.agent-relay/outbox/$AGENT_RELAY_NAME/msg << 'EOF'
TO: AgentName

Your message here.
EOF

IMPORTANT: Output the trigger ->relay-file:msg directly in your response text (not via echo in bash). The trigger must appear in your actual output, not just in command output.

Broadcast to All Agents

cat > ~/.agent-relay/outbox/$AGENT_RELAY_NAME/broadcast << 'EOF'
TO: *

Hello everyone!
EOF

Then: ->relay-file:broadcast

With Thread

cat > ~/.agent-relay/outbox/$AGENT_RELAY_NAME/reply << 'EOF'
TO: AgentName
THREAD: issue-123

Response in thread context.
EOF

Then: ->relay-file:reply

Message Format

TO: Target
THREAD: optional-thread

Message body (everything after blank line)

Communication Protocol

ACK immediately - When you receive a task, acknowledge it before starting work:

cat > ~/.agent-relay/outbox/$AGENT_RELAY_NAME/ack << 'EOF'
TO: Sender

ACK: Brief description of task received
EOF

Then: ->relay-file:ack

Report completion - When done, send a completion message:

cat > ~/.agent-relay/outbox/$AGENT_RELAY_NAME/done << 'EOF'
TO: Sender

DONE: Brief summary of what was completed
EOF

Then: ->relay-file:done

Priority handling - If you see [RETRY] or [URGENT] tags, respond immediately.

Receiving Messages

Messages appear as:

Relay message from Alice [abc123]: Content here

Messages with retry escalation:

[RETRY] Relay message from Alice [abc123]: Did you receive my message?
[URGENT - PLEASE ACKNOWLEDGE] Relay message from Alice [abc123]: Please respond!

Channel Routing (Important!)

Messages from #general (broadcast channel) include a [#general] indicator:

Relay message from Alice [abc123] [#general]: Hello everyone!

When you see [#general]: Reply to * (broadcast), NOT to the sender directly.

Spawning & Releasing Agents

IMPORTANT: The filename is always spawn (not spawn-agentname) and the trigger is always ->relay-file:spawn. Spawn agents one at a time sequentially.

Spawn a Worker

cat > ~/.agent-relay/outbox/$AGENT_RELAY_NAME/spawn << 'EOF'
KIND: spawn
NAME: WorkerName
CLI: claude

Task description here.
EOF

Then: ->relay-file:spawn

Release a Worker

cat > ~/.agent-relay/outbox/$AGENT_RELAY_NAME/release << 'EOF'
KIND: release
NAME: WorkerName
EOF

Then: ->relay-file:release

Headers Reference

Status Updates

Send status updates to your lead, NOT broadcast:

# Correct - status to lead only
cat > ~/.agent-relay/outbox/$AGENT_RELAY_NAME/status << 'EOF'
TO: Lead

STATUS: Working on auth module
EOF

Then: ->relay-file:status

CLI Commands

agent-relay status              # Check daemon status
agent-relay agents              # List active agents
agent-relay agents:logs <name>  # View agent output
agent-relay agents:kill <name>  # Kill a spawned agent
agent-relay read <id>           # Read truncated message

Synchronous Messaging

By default, messages are fire-and-forget. Add [await] to block until the recipient ACKs:

->relay:AgentB [await] Please confirm

Custom timeout (seconds or minutes):

->relay:AgentB [await:30s] Please confirm
->relay:AgentB [await:5m] Please confirm

Recipients auto-ACK after processing when a correlation ID is present.

Troubleshooting

agent-relay status                    # Check daemon
agent-relay agents                    # List connected agents
ls -la /tmp/agent-relay.sock          # Verify socket
ls -la ~/.agent-relay/outbox/             # Check outbox directories

Common Mistakes