agent-relay-plugin 0.1.0

package/.claude-plugin/plugin.json

@@ -0,0 +1,5 @@
+{
+  "name": "agent-relay",
+  "description": "Client connector for Agent Relay — auto-registers Claude Code sessions as agents and enables inter-agent messaging via a lightweight HTTP message bus",
+  "version": "0.1.0"
+}

package/hooks/hooks.json

@@ -0,0 +1,26 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash \"${CLAUDE_PLUGIN_ROOT}/hooks/session-start.sh\"",
+            "timeout": 15
+          }
+        ]
+      }
+    ],
+    "SessionEnd": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash \"${CLAUDE_PLUGIN_ROOT}/hooks/session-end.sh\"",
+            "timeout": 5
+          }
+        ]
+      }
+    ]
+  }
+}

package/hooks/poll-inbox.sh

@@ -0,0 +1,54 @@
+#!/usr/bin/env bash
+# Agent Relay plugin — inbox poller
+# Each new message prints one stdout line (consumed by Monitor as a notification).
+# Usage: poll-inbox.sh <relay-url> <agent-id> [interval-seconds]
+
+RELAY_URL="$1"
+AGENT_ID="$2"
+INTERVAL="${3:-10}"
+
+if [ -z "$RELAY_URL" ] || [ -z "$AGENT_ID" ]; then
+  echo "Usage: poll-inbox.sh <relay-url> <agent-id> [interval]" >&2
+  exit 1
+fi
+
+# Bootstrap cursor at current max so we only see messages arriving after session start.
+since_id=$(curl -s "${RELAY_URL}/api/messages/cursor" 2>/dev/null | jq -r '.latestId // 0' 2>/dev/null || echo 0)
+
+fail_streak=0
+while true; do
+  hb_code=$(curl -s -o /dev/null -w '%{http_code}' -X POST \
+    "${RELAY_URL}/api/agents/${AGENT_ID}/heartbeat" 2>/dev/null)
+
+  msgs=$(curl -s --fail "${RELAY_URL}/api/messages?for=${AGENT_ID}&sinceId=${since_id}&unread=true" 2>/dev/null)
+  poll_rc=$?
+
+  if [ "$hb_code" != "200" ] || [ $poll_rc -ne 0 ]; then
+    fail_streak=$((fail_streak + 1))
+    case "$fail_streak" in
+      1) delay=2 ;;
+      2) delay=10 ;;
+      3) delay=30 ;;
+      *) delay=60 ;;
+    esac
+    if [ "$fail_streak" = "1" ]; then
+      echo "warn: agent-relay unreachable (${RELAY_URL}) — backing off" >&2
+    fi
+    sleep "$delay"
+    continue
+  fi
+  fail_streak=0
+
+  count=$(echo "$msgs" | jq 'length' 2>/dev/null || echo 0)
+  if [ "$count" -gt 0 ] 2>/dev/null && [ "$count" != "0" ]; then
+    echo "$msgs" | jq -r '.[] | "\(.from) → \(.to) | \(.subject // "(no subject)"): \(.body)"'
+    since_id=$(echo "$msgs" | jq '[.[].id] | max')
+    echo "$msgs" | jq -r '.[].id' | while read -r mid; do
+      curl -s -X PATCH "${RELAY_URL}/api/messages/${mid}" \
+        -H 'Content-Type: application/json' \
+        -d "{\"readBy\":\"${AGENT_ID}\"}" > /dev/null 2>&1 || true
+    done
+  fi
+
+  sleep "$INTERVAL"
+done

package/hooks/session-end.sh

@@ -0,0 +1,27 @@
+#!/usr/bin/env bash
+# Agent Relay plugin — SessionEnd hook
+# Marks this session's agent as offline.
+
+RELAY_URL="${AGENT_RELAY_URL:-http://localhost:4850}"
+
+input=$(cat)
+cwd=$(echo "$input" | jq -r '.cwd // empty')
+session_id=$(echo "$input" | jq -r '.session_id // empty')
+
+machine=$(hostname)
+project=$(basename "${cwd:-unknown}")
+rig="${CLAUDE_RIG_NAME:-default}"
+
+if command -v shasum >/dev/null 2>&1; then
+  short_sid=$(printf '%s' "$session_id" | shasum -a 1 | head -c 6)
+else
+  short_sid=$(printf '%s' "$session_id" | md5sum | head -c 6)
+fi
+agent_id="${machine}-${rig}-${project}-${short_sid}"
+
+curl -s -X PATCH "${RELAY_URL}/api/agents/${agent_id}/status" \
+  -H 'Content-Type: application/json' \
+  -d '{"status":"offline"}' \
+  > /dev/null 2>&1 &
+
+exit 0

package/hooks/session-start.sh

@@ -0,0 +1,102 @@
+#!/usr/bin/env bash
+# Agent Relay plugin — SessionStart hook
+# Registers this Claude Code session as an agent and injects messaging context.
+
+RELAY_URL="${AGENT_RELAY_URL:-http://localhost:4850}"
+PLUGIN_ROOT="${CLAUDE_PLUGIN_ROOT:-$(dirname "$(dirname "$0")")}"
+
+input=$(cat)
+
+session_id=$(echo "$input" | jq -r '.session_id // empty')
+cwd=$(echo "$input" | jq -r '.cwd // empty')
+model=$(echo "$input" | jq -r '.model // empty')
+source=$(echo "$input" | jq -r '.source // empty')
+
+machine=$(hostname)
+project=$(basename "${cwd:-unknown}")
+rig="${CLAUDE_RIG_NAME:-default}"
+
+if command -v shasum >/dev/null 2>&1; then
+  short_sid=$(printf '%s' "$session_id" | shasum -a 1 | head -c 6)
+else
+  short_sid=$(printf '%s' "$session_id" | md5sum | head -c 6)
+fi
+agent_id="${machine}-${rig}-${project}-${short_sid}"
+
+# Capabilities: AGENT_RELAY_CAPS="chat,review,edit" (comma-separated) → JSON array
+caps_csv="${AGENT_RELAY_CAPS:-chat}"
+caps_json=$(echo "$caps_csv" | jq -R 'split(",") | map(gsub("^\\s+|\\s+$"; ""))')
+
+# Register agent card
+reg_code=$(curl -s -o /dev/null -w '%{http_code}' -X POST "${RELAY_URL}/api/agents" \
+  -H 'Content-Type: application/json' \
+  -d "$(jq -n \
+    --arg id "$agent_id" \
+    --arg name "$project ($rig @ $machine)" \
+    --arg machine "$machine" \
+    --arg rig "$rig" \
+    --argjson tags "$(jq -n --arg r "$rig" --arg p "$project" '[$r, $p]')" \
+    --argjson caps "$caps_json" \
+    --argjson meta "$(jq -n --arg sid "$session_id" --arg model "$model" --arg src "$source" --arg cwd "$cwd" '{sessionId: $sid, model: $model, source: $src, cwd: $cwd}')" \
+    '{id: $id, name: $name, machine: $machine, rig: $rig, tags: $tags, capabilities: $caps, status: "online", meta: $meta}'
+  )" 2>/dev/null)
+if [ "$reg_code" != "201" ] && [ "$reg_code" != "200" ]; then
+  echo "warn: agent-relay register failed (HTTP ${reg_code:-none}) — ${RELAY_URL}" >&2
+fi
+
+# Check for unread messages
+unread=$(curl -s "${RELAY_URL}/api/messages?for=${agent_id}&unread=true" 2>/dev/null)
+unread_count=$(echo "$unread" | jq 'length' 2>/dev/null || echo "0")
+
+# Build context output
+cat <<CONTEXT
+Agent Relay active. Your agent ID: ${agent_id}
+Relay URL: ${RELAY_URL}
+
+To send a message:
+  curl -s -X POST ${RELAY_URL}/api/messages -H 'Content-Type: application/json' -d '{"from":"${agent_id}","to":"TARGET","body":"MESSAGE"}'
+  TARGET: agent-id (direct), tag:NAME (by tag), cap:NAME (by capability), label:NAME (by human-set label, fan-out), broadcast (all)
+
+To rename yourself (set a short, human-friendly label so the user can refer to you easily):
+  curl -s -X PATCH ${RELAY_URL}/api/agents/${agent_id}/label -H 'Content-Type: application/json' -d '{"label":"backend fixing"}'
+  When the user tells you to rename yourself ("call yourself X", "rename to X"), call this endpoint.
+  Labels are NOT unique — if multiple sessions share a label, \`to: "label:X"\` fans out to all of them.
+  Use \`to: "label:backend fixing"\` when the user says "tell 'backend fixing' to do Y".
+
+To reply to a message (threading):
+  curl -s -X POST ${RELAY_URL}/api/messages -H 'Content-Type: application/json' -d '{"from":"${agent_id}","to":"TARGET","body":"MESSAGE","replyTo":MSG_ID}'
+  Always use replyTo when responding to a specific message — it creates a thread.
+
+To send a claimable task (only one agent can claim it):
+  curl -s -X POST ${RELAY_URL}/api/messages -H 'Content-Type: application/json' -d '{"from":"${agent_id}","to":"cap:review","body":"TASK","claimable":true}'
+
+To claim a task:
+  curl -s -X POST ${RELAY_URL}/api/messages/MSG_ID/claim -H 'Content-Type: application/json' -d '{"agentId":"${agent_id}"}'
+  When you see a claimable message, claim it BEFORE starting work. If claim fails, someone else got it — move on.
+
+To view a thread:
+  curl -s '${RELAY_URL}/api/messages/MSG_ID/thread'
+
+To check messages:
+  curl -s '${RELAY_URL}/api/messages?for=${agent_id}&unread=true'
+
+To mark read:
+  curl -s -X PATCH ${RELAY_URL}/api/messages/ID -H 'Content-Type: application/json' -d '{"readBy":"${agent_id}"}'
+
+To find agents by capability:
+  curl -s '${RELAY_URL}/api/agents/find?capability=review'
+
+To list online agents:
+  curl -s '${RELAY_URL}/api/agents?status=online'
+
+IMPORTANT: Start a persistent Monitor NOW to listen for incoming messages:
+  Monitor({ command: "${PLUGIN_ROOT}/hooks/poll-inbox.sh ${RELAY_URL} ${agent_id} 10", description: "Agent Relay inbox for ${agent_id}", persistent: true })
+You MUST start this Monitor immediately at session start. Do not wait for the user to ask.
+CONTEXT
+
+# Append unread messages if any
+if [ "$unread_count" -gt 0 ] 2>/dev/null && [ "$unread_count" != "0" ]; then
+  echo ""
+  echo "${unread_count} unread message(s):"
+  echo "$unread" | jq -r '.[] | "  [\(.from)] \(.subject // "(no subject)"): \(.body | if length > 120 then .[:120] + "..." else . end)"'
+fi

package/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "agent-relay-plugin",
+  "version": "0.1.0",
+  "description": "Claude Code plugin for Agent Relay — auto-registers sessions as agents and enables inter-agent messaging",
+  "type": "module",
+  "license": "MIT",
+  "author": "Edin Mujkanovic <edin@exelerus.com>",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/edimuj/agent-relay.git",
+    "directory": "plugin"
+  },
+  "files": [
+    ".claude-plugin/",
+    "hooks/"
+  ],
+  "keywords": [
+    "claude-code",
+    "claude-code-plugin",
+    "agent-relay",
+    "multi-agent",
+    "inter-agent-communication"
+  ]
+}