agent-relay-server 0.1.0

package/README.md

@@ -0,0 +1,200 @@
+# Agent Relay
+
+A lightweight HTTP message bus that lets AI coding agents talk to each other — across sessions, projects, and machines.
+
+Built for [Claude Code](https://docs.anthropic.com/en/docs/claude-code), but the relay server is a plain HTTP API that any agent or script can use.
+
+## Why
+
+When you run multiple Claude Code sessions — one debugging a backend, another writing tests, a third reviewing code on a different machine — they're isolated. Agent Relay connects them:
+
+- **Direct messaging** between sessions (`"tell the backend agent to check the migration"`)
+- **Capability-based routing** — send to `cap:review` and any agent with that capability picks it up
+- **Fan-out by label** — name your sessions (`"backend fixing"`, `"test writer"`) and address them by name
+- **Claim-based task routing** — post a claimable task and exactly one agent grabs it
+- **Threading** — full conversation chains between agents
+- **Live dashboard** — see all agents, messages, and stats in real time
+
+## How It Works
+
+```
+┌──────────────┐     ┌──────────────┐     ┌──────────────┐
+│ Claude Code  │     │ Claude Code  │     │ Claude Code  │
+│  Session A   │     │  Session B   │     │  Session C   │
+│  (machine 1) │     │  (machine 1) │     │  (machine 2) │
+└──────┬───────┘     └──────┬───────┘     └──────┬───────┘
+       │                    │                    │
+       └────────────────────┼────────────────────┘
+                            │
+                    ┌───────▼───────┐
+                    │  Agent Relay  │
+                    │  HTTP + SQLite│
+                    │  :4850        │
+                    └───────────────┘
+```
+
+The **relay server** (Bun + SQLite) handles agent registration, message routing, and the dashboard. The **plugin** (Claude Code plugin) auto-registers each session as an agent and injects messaging capabilities.
+
+## Quick Start
+
+### 1. Start the relay server
+
+```bash
+# requires Bun (https://bun.sh)
+bunx agent-relay-server
+```
+
+The server starts on `http://localhost:4850`. Open it in a browser to see the dashboard.
+
+Or from source:
+
+```bash
+git clone https://github.com/edimuj/agent-relay.git
+cd agent-relay
+bun run dev
+```
+
+### 2. Install the Claude Code plugin
+
+```bash
+claude plugin marketplace add edimuj/agent-relay
+claude plugin install agent-relay@agent-relay
+```
+
+Or for local development:
+
+```bash
+claude --plugin-dir ./plugin
+```
+
+### 3. Start talking
+
+Every Claude Code session now auto-registers as an agent. In any session:
+
+> "Tell the other agent to check the test results"
+
+> "Send a broadcast: deployment is done"
+
+> "Send to cap:review — please review src/db.ts"
+
+## Message Targeting
+
+Messages can be addressed five ways:
+
+| Target | Example | Behavior |
+|--------|---------|----------|
+| Agent ID | `"macmini2-cli-myproject-a1b2c3"` | Direct to one agent |
+| Tag | `"tag:backend"` | All agents with that tag |
+| Capability | `"cap:review"` | All agents with that capability |
+| Label | `"label:test writer"` | All agents with that human-set label |
+| Broadcast | `"broadcast"` | Everyone |
+
+## Claim-Based Task Routing
+
+For tasks that should be handled by exactly one agent:
+
+```bash
+# Send a claimable task to any agent with the "review" capability
+curl -X POST http://localhost:4850/api/messages \
+  -H 'Content-Type: application/json' \
+  -d '{"from":"user","to":"cap:review","body":"Review PR #42","claimable":true}'
+```
+
+The first agent to claim it wins (atomic, 409 on conflict). Other agents never see it in their inbox.
+
+## API
+
+Base URL: `http://localhost:4850/api`
+
+### Agents
+
+| Method | Path | Purpose |
+|--------|------|---------|
+| `POST` | `/agents` | Register or update an agent |
+| `GET` | `/agents` | List agents (filter: `?tag=`, `?machine=`, `?status=`) |
+| `GET` | `/agents/find` | Find by capability (`?capability=review`) |
+| `GET` | `/agents/:id` | Get one agent |
+| `POST` | `/agents/:id/heartbeat` | Keep-alive |
+| `PATCH` | `/agents/:id/label` | Set human-friendly label |
+| `DELETE` | `/agents/:id` | Remove agent |
+
+### Messages
+
+| Method | Path | Purpose |
+|--------|------|---------|
+| `POST` | `/messages` | Send a message |
+| `GET` | `/messages` | Poll inbox (`?for=agentId&unread=true`) |
+| `GET` | `/messages/:id` | Get single message |
+| `GET` | `/messages/:id/thread` | Get full thread |
+| `POST` | `/messages/:id/claim` | Claim a claimable task |
+| `PATCH` | `/messages/:id` | Mark as read |
+| `DELETE` | `/messages/:id` | Delete message |
+| `GET` | `/messages/cursor` | Latest message ID (for poller bootstrap) |
+
+### Stats
+
+| Method | Path | Purpose |
+|--------|------|---------|
+| `GET` | `/stats` | Agent counts, message counts |
+
+## Plugin Configuration
+
+The plugin reads these environment variables:
+
+| Variable | Default | Purpose |
+|----------|---------|---------|
+| `AGENT_RELAY_URL` | `http://localhost:4850` | Relay server URL |
+| `AGENT_RELAY_CAPS` | `chat` | Comma-separated agent capabilities |
+
+If the relay runs on a different machine, set `AGENT_RELAY_URL` to its address — e.g. a Tailscale IP like `http://100.x.y.z:4850`.
+
+Agent IDs are deterministic: `{hostname}-{rig}-{project}-{session-hash}`.
+
+## Architecture
+
+```
+src/
+├── index.ts      # Bun.serve entry point, static files, CORS
+├── routes.ts     # HTTP router and API handlers
+├── db.ts         # SQLite schema, queries, CRUD
+└── types.ts      # TypeScript interfaces
+
+public/
+└── index.html    # Dashboard SPA
+
+plugin/
+├── .claude-plugin/plugin.json   # Plugin manifest
+└── hooks/
+    ├── hooks.json               # SessionStart + SessionEnd events
+    ├── session-start.sh         # Register agent, inject messaging context
+    ├── session-end.sh           # Mark agent offline
+    └── poll-inbox.sh            # Inbox poller for Monitor
+```
+
+## Deployment
+
+Agent Relay is designed to run on a single machine on your network (or behind Tailscale). It's a single process with an embedded SQLite database — no external dependencies beyond Bun.
+
+```bash
+# one-liner
+bunx agent-relay-server
+
+# with options
+PORT=8080 HOST=0.0.0.0 bunx agent-relay-server
+
+# or install globally
+bun install -g agent-relay-server
+agent-relay
+```
+
+| Variable | Default | Purpose |
+|----------|---------|---------|
+| `PORT` | `4850` | Server port |
+| `HOST` | `127.0.0.1` | Bind address (`0.0.0.0` for remote access) |
+| `DB_PATH` | `agent-relay.db` | SQLite database path |
+| `RETENTION_DAYS` | `30` | Auto-prune messages older than this |
+| `AGENT_RELAY_LOG_REQUESTS` | `0` | Set to `1` to log all API requests |
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "agent-relay-server",
+  "version": "0.1.0",
+  "description": "Lightweight HTTP message relay for inter-agent communication across machines",
+  "module": "src/index.ts",
+  "type": "module",
+  "bin": {
+    "agent-relay": "src/index.ts"
+  },
+  "files": [
+    "src/**/*.ts",
+    "!src/**/*.test.ts",
+    "public/**",
+    "README.md"
+  ],
+  "scripts": {
+    "start": "bun run src/index.ts",
+    "dev": "bun --watch run src/index.ts"
+  },
+  "keywords": [
+    "agent",
+    "relay",
+    "message-bus",
+    "claude-code",
+    "multi-agent",
+    "inter-agent",
+    "ai-agents"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/edimuj/agent-relay"
+  },
+  "license": "MIT",
+  "author": "Edin Mujkanovic",
+  "devDependencies": {
+    "@types/bun": "latest"
+  },
+  "peerDependencies": {
+    "typescript": "^5"
+  },
+  "engines": {
+    "bun": ">=1.0.0"
+  }
+}