agent-relay 1.3.2 → 1.5.0

package/README.md

@@ -1,6 +1,6 @@
 # agent-relay
 
-Real-time messaging between AI agents.
+Real-time messaging between AI agents. Sub-5ms latency, any CLI, any language.
 
 ## Install
 
@@ -8,58 +8,76 @@ Real-time messaging between AI agents.
 npm install -g agent-relay
 ```
 
-**Requirements:** Node.js 20+, tmux
+**Requirements:** Node.js 20+
 
-**Linux/Server:** Install build tools first (required for node-pty):
+**Linux:** Install build tools first:
 ```bash
 sudo apt-get update && sudo apt-get install -y build-essential
 ```
 
+### Platform Support
+
+| Platform | Status | Notes |
+|----------|--------|-------|
+| macOS Apple Silicon | **Full support** | Native relay-pty binary |
+| macOS Intel | **Full support** | Native relay-pty binary |
+| Linux x64 | **Full support** | Native relay-pty binary |
+| Linux arm64 | Fallback | Uses tmux (install separately) |
+| Windows | Fallback | Uses tmux via WSL |
+
 ## Quick Start
 
 ```bash
-# Terminal 1: Start daemon
-agent-relay up
+# Start daemon + coordinator agent
+agent-relay claude
 
-# Terminal 2: Start an agent
-agent-relay -n Alice claude
-
-# Terminal 3: Start another agent
-agent-relay -n Bob codex
+# Or with other CLI tools
+agent-relay codex
 ```
 
-Agents communicate by outputting `->relay:` patterns. Always use the fenced format:
+Agents communicate via file-based messaging:
+
+```bash
+# Write message to outbox
+cat > /tmp/relay-outbox/$AGENT_RELAY_NAME/msg << 'EOF'
+TO: Bob
+
+Hey, can you help with this task?
+EOF
 
+# Trigger send
+echo "->relay-file:msg"
 ```
-->relay:Bob <<<
-Hey, can you review my changes?>>>
 
-->relay:* <<<
-Broadcasting to everyone>>>
+Or broadcast to all:
+```bash
+cat > /tmp/relay-outbox/$AGENT_RELAY_NAME/broadcast << 'EOF'
+TO: *
+
+Message to all agents
+EOF
+echo "->relay-file:broadcast"
 ```
 
-## CLI
+## CLI Reference
 
 | Command | Description |
 |---------|-------------|
-| `agent-relay <cmd>` | Wrap agent with messaging |
-| `agent-relay -n Name <cmd>` | Wrap with specific name |
+| `agent-relay claude` | Start daemon + coordinator with Claude |
+| `agent-relay codex` | Start daemon + coordinator with Codex |
 | `agent-relay up` | Start daemon + dashboard |
 | `agent-relay down` | Stop daemon |
-| `agent-relay status` | Check if running |
+| `agent-relay status` | Check daemon status |
+| `agent-relay create-agent -n Name <cmd>` | Create named agent |
 | `agent-relay read <id>` | Read truncated message |
 | `agent-relay bridge <projects...>` | Bridge multiple projects |
 
-## How It Works
-
-1. `agent-relay up` starts a daemon that routes messages via Unix socket
-2. `agent-relay <cmd>` wraps your agent in tmux, parsing output for `->relay:` patterns
-3. Messages are injected into recipient terminals in real-time
+## Architecture
 
 ```
 ┌─────────────┐     ┌─────────────┐
 │ Agent Alice │     │  Agent Bob  │
-│   (tmux)    │     │   (tmux)    │
+│ (relay-pty) │     │ (relay-pty) │
 └──────┬──────┘     └──────┬──────┘
        │                   │
        └─────────┬─────────┘
@@ -68,196 +86,150 @@ Broadcasting to everyone>>>
                  │
         ┌────────┴────────┐
         │  relay daemon   │
+        │   (<5ms P2P)    │
+        └────────┬────────┘
+                 │
+        ┌────────┴────────┐
+        │    Dashboard    │
+        │  (Protocol UI)  │
         └─────────────────┘
 ```
 
-## Agent Communication
+**relay-pty** is a Rust binary that wraps your CLI tool, providing:
+- Direct PTY writes for reliable message injection
+- ~550ms injection latency (vs ~1700ms with tmux)
+- File-based message parsing for robustness
 
-### Send Message
+The **Dashboard** is a reference implementation of the relay protocol, providing real-time visibility into agent communication, message history, and coordinator controls.
 
-```
-->relay:AgentName <<<
-Your message here>>>
-```
+## Dashboard
 
-### Broadcast
+The dashboard starts automatically with any command (`agent-relay claude`, `agent-relay up`, etc.) at http://localhost:3888
 
-```
-->relay:* <<<
-Message to all agents>>>
-```
+Features:
+- Real-time agent presence and status
+- Message history and threading
+- Coordinator panel for multi-agent orchestration
+- Log streaming from all agents
 
-### Receive
+## Cloud
 
-Messages appear as:
+For maximum scale and team collaboration, use [**agent-relay cloud**](https://agent-relay.com):
 
-```
-Relay message from Alice [abc123]: Your message here
-```
+```bash
+# Link your machine to cloud
+agent-relay cloud link
 
-### Truncated Messages
+# Check cloud status
+agent-relay cloud status
 
-Long messages are truncated. Use the ID to read full content:
+# List agents across all linked machines
+agent-relay cloud agents
 
-```bash
-agent-relay read abc123
+# Send message to agent on any machine
+agent-relay cloud send AgentName "Your message"
 ```
 
-## Agent Roles
+Cloud features:
+- **Persistent workspaces** - Agents survive disconnects
+- **Team collaboration** - Share dashboards, view all agents
+- **Cross-machine messaging** - Send to agents on any linked machine
+- **Centralized monitoring** - See all daemons and agents in one place
 
-Agent names automatically match role definitions (case-insensitive):
+The cloud dashboard is the same protocol implementation, scaled for teams.
 
-```bash
-# If .claude/agents/lead.md exists:
-agent-relay -n Lead claude    # matches lead.md
-agent-relay -n LEAD claude    # matches lead.md
-agent-relay -n lead claude    # matches lead.md
-
-# Supported locations:
-# - .claude/agents/<name>.md
-# - .openagents/<name>.md
-```
+## Agent Roles
 
-Create role agents for your team:
+Create role-based agents by adding markdown files:
 
 ```
 .claude/agents/
 ├── lead.md          # Coordinator
 ├── implementer.md   # Developer
-├── designer.md      # UI/UX
-└── reviewer.md      # Code review
+├── reviewer.md      # Code review
+└── designer.md      # UI/UX
 ```
 
-## Multi-Project Orchestration
-
-Bridge multiple projects with a single orchestrator:
-
+Names automatically match roles (case-insensitive):
 ```bash
-# Bridge projects (Architect mode)
-agent-relay bridge ~/auth ~/frontend ~/api
+agent-relay create-agent -n Lead claude    # Uses lead.md
 ```
 
-### Workflow
-
-1. **Start daemons** in each project: `agent-relay up`
-2. **Start agents** in each project: `agent-relay -n Alice claude`
-3. **Bridge** from anywhere: `agent-relay bridge ~/project1 ~/project2`
+## Multi-Project Bridge
 
-### Cross-Project Messaging
+Orchestrate agents across multiple repositories:
 
-```
-->relay:projectId:agent <<<
-Message to specific agent>>>
+```bash
+# Start daemons in each project
+cd ~/auth && agent-relay up
+cd ~/frontend && agent-relay up
 
-->relay:*:lead <<<
-Broadcast to all project leads>>>
+# Bridge from anywhere
+agent-relay bridge ~/auth ~/frontend ~/api
 ```
 
-### Spawn Agents
+Cross-project messaging uses `project:agent` format in the TO header:
+```bash
+cat > /tmp/relay-outbox/$AGENT_RELAY_NAME/msg << 'EOF'
+TO: auth:Lead
 
-```
-->relay:spawn Dev1 claude "Implement login endpoint"
-->relay:release Dev1
+Please review the token refresh logic
+EOF
+echo "->relay-file:msg"
 ```
 
-See [docs/DESIGN_BRIDGE_STAFFING.md](docs/DESIGN_BRIDGE_STAFFING.md) for full details.
+## Teaching Agents
 
-## Enabling AI Agents
-
-To teach your AI agents how to use agent-relay, you should:
-
-### Install the Skill
+Install the messaging skill for your agents via [prpm](https://prpm.dev):
 
 ```bash
-prpm install using-agent-relay
-```
+# Install snippet for AGENTS.md
+npx prpm install @agent-relay/agent-relay-snippet
 
-This installs the `using-agent-relay` skill which provides agents with messaging patterns, coordination workflows, and troubleshooting guidance.
-
-### Update the AGENTS.md/CLAUDE.md file
-
-Use prpm to install the AGENTS.md snippet or CLAUDE.md snippet
+# Install snippet for CLAUDE.md
+npx prpm install @agent-relay/agent-relay-snippet --location CLAUDE.md
 ```
-prpm install @agent-relay/agent-relay-snippet
-```
-
-Or if using CLAUDE.md
-```
-prpm install @agent-relay/agent-relay-snippet --location CLAUDE.md
-```
-
-## Dashboard
 
-`agent-relay up` starts a web dashboard at http://localhost:3888
+View the rest of our packages on on [prpm organization page](https://prpm.dev/orgs?name=Agent%20Relay)
 
-![Agent Relay Dashboard](docs/dashboard.png)
+Or manually add the relay patterns to your agent instructions.
 
 ## Development
 
 ```bash
-git clone https://github.com/khaliqgant/agent-relay.git
-cd agent-relay
+git clone https://github.com/AgentWorkforce/relay.git
+cd relay
 npm install && npm run build
+npm run dev  # Start daemon + dashboard in dev mode
 ```
 
-## Why agent-relay?
+## Philosophy
 
-### The Composable Approach
+**Do one thing well**: Real-time agent messaging with <5ms latency.
 
-Most multi-agent tools try to be complete solutions - handling communication, memory, UI, workflows, and orchestration. agent-relay takes a different approach: **do one thing exceptionally well** (real-time messaging) and integrate with best-of-breed tools for everything else.
+agent-relay is a messaging layer, not a framework. It integrates with:
+- Any CLI tool (Claude, Codex, Gemini, custom agents)
+- Any orchestration system (your own, Beads, external)
+- Any memory system (Mimir, vector DBs, files)
 
 ```
-┌─────────────────────────────────────────────────────────────┐
-│                    Your Agent System                        │
-├─────────────────────────────────────────────────────────────┤
-│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐         │
-│  │   Mimir     │  │  Maestro    │  │    Beads    │         │
-│  │  (Memory)   │  │    (UI)     │  │ (Workflows) │         │
-│  └──────┬──────┘  └──────┬──────┘  └──────┬──────┘         │
-│         └────────────────┼────────────────┘                 │
-│                ┌─────────▼─────────┐                        │
-│                │   agent-relay     │  ◄── Messaging layer   │
-│                │     <5ms P2P      │                        │
-│                └─────────┬─────────┘                        │
-│         ┌────────────────┼────────────────┐                 │
-│    ┌────▼────┐     ┌────▼────┐     ┌────▼────┐             │
-│    │ Claude  │     │  Codex  │     │  Gemini │             │
-│    └─────────┘     └─────────┘     └─────────┘             │
-└─────────────────────────────────────────────────────────────┘
+┌──────────────────────────────────────────┐
+│           Your Agent System              │
+├──────────────────────────────────────────┤
+│  Memory │ Orchestration │ UI/Dashboard   │
+│  (any)  │    (any)      │    (any)       │
+├──────────────────────────────────────────┤
+│           agent-relay                    │
+│        Real-time messaging               │
+├──────────────────────────────────────────┤
+│  Claude  │  Codex  │  Gemini  │  Custom  │
+└──────────────────────────────────────────┘
 ```
 
-### Unix Philosophy
-
-- **Do one thing well**: Real-time agent messaging with <5ms latency
-- **Work with others**: Simple `->relay:` pattern, standard I/O
-- **Text streams**: Messages are just text, easy to parse/transform
-- **Composability**: Pipe into other tools, wrap any CLI
-
-### When to Use agent-relay
-
-| Use Case | agent-relay? |
-|----------|--------------|
-| Quick prototyping with multiple agents | **Yes** - 1 min setup |
-| Real-time agent collaboration | **Yes** - fastest option |
-| CLI-native workflows | **Yes** - no Electron/desktop needed |
-| Need persistent knowledge graph | Combine with Mimir |
-| Need rich desktop UI | Combine with Maestro |
-| Enterprise compliance | Combine with governance layer |
+## License
 
-See [docs/COMPETITIVE_ANALYSIS.md](docs/COMPETITIVE_ANALYSIS.md) for detailed comparisons with 16 other multi-agent tools.
+MIT
 
 ---
 
-## Inspiration
-
-This project was inspired by some excellent work in the multi-agent coordination space:
-
-- **[mcp_agent_mail](https://github.com/Dicklesworthstone/mcp_agent_mail)** - A brilliant MCP-based approach to agent messaging with file-based inboxes and structured message handling. Great patterns for durable, asynchronous agent communication.
-
-- **[swarm-tools / swarm-mail](https://github.com/joelhooks/swarm-tools)** - An exceptional event-sourced coordination system with durable cursors, locks, deferred responses, and ask/respond patterns. The gold standard for robust multi-agent workflows with full audit trails.
-
-Both projects informed our thinking around durability, message threading, and coordination primitives. Check them out!
-
-## License
-
-MIT
+**Links:** [Documentation](https://github.com/AgentWorkforce/relay/tree/main/docs) | [Issues](https://github.com/AgentWorkforce/relay/issues) | [Cloud](https://agent-relay.com)

package/deploy/workspace/entrypoint.sh

@@ -92,6 +92,15 @@ export NO_UPDATE_NOTIFIER=1
 export NPM_CONFIG_UPDATE_NOTIFIER=false
 log "Auto-updates disabled for AI CLIs (container environment)"
 
+# ============================================================================
+# Git credential helper configuration
+# Clean up conflicting credential helpers that gh CLI or other tools may set
+# git-credential-relay requires no host-specific overrides to work properly
+# ============================================================================
+git config --global --unset-all 'credential.https://github.com.helper' 2>/dev/null || true
+git config --global --unset-all 'credential.https://gist.github.com.helper' 2>/dev/null || true
+log "Git credential helper configured (removed conflicting gh auth overrides)"
+
 # ============================================================================
 # Per-user credential storage setup
 # Create user-specific HOME on persistent volume (/data)

package/dist/bridge/spawner.d.ts

@@ -3,7 +3,7 @@
  * Handles spawning and releasing worker agents via node-pty.
  * Workers run headlessly with output capture for logs.
  */
-import { type SummaryEvent, type SessionEndEvent } from '../wrapper/pty-wrapper.js';
+import type { SummaryEvent, SessionEndEvent } from '../wrapper/pty-wrapper.js';
 import { AgentPolicyService, type CloudPolicyFetcher } from '../policy/agent-policy.js';
 import type { SpawnRequest, SpawnResult, WorkerInfo, SpawnWithShadowRequest, SpawnWithShadowResult } from './types.js';
 /**
@@ -68,7 +68,7 @@ export declare class AgentSpawner {
      */
     setOnAgentDeath(callback: OnAgentDeathCallback): void;
     /**
-     * Set cloud persistence handler for forwarding PtyWrapper events.
+     * Set cloud persistence handler for forwarding RelayPtyOrchestrator events.
      * When set, 'summary' and 'session-end' events from spawned agents
      * are forwarded to the handler for cloud persistence (PostgreSQL/Redis).
      *
@@ -76,12 +76,12 @@ export declare class AgentSpawner {
      */
     setCloudPersistence(handler: CloudPersistenceHandler): void;
     /**
-     * Bind cloud persistence event handlers to a PtyWrapper.
+     * Bind cloud persistence event handlers to a RelayPtyOrchestrator.
      * Returns the listener references for cleanup.
      */
     private bindCloudPersistenceEvents;
     /**
-     * Unbind all tracked listeners from a PtyWrapper.
+     * Unbind all tracked listeners from a RelayPtyOrchestrator.
      */
     private unbindListeners;
     /**