agent-relay-server 0.2.0 → 0.3.0

package/README.md

@@ -1,87 +1,130 @@
 # Agent Relay
 
-A lightweight HTTP message bus that lets AI coding agents talk to each other — across sessions, projects, and machines.
+[![npm: server](https://img.shields.io/npm/v/agent-relay-server?label=server&color=blue)](https://www.npmjs.com/package/agent-relay-server)
+[![npm: plugin](https://img.shields.io/npm/v/agent-relay-plugin?label=plugin&color=blue)](https://www.npmjs.com/package/agent-relay-plugin)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)
+
+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.
 
+![Agent Relay Dashboard](docs/dashboard.png)
+
 ## 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:
+You're running three Claude Code sessions: one debugging a backend, another writing tests, a third reviewing code on a different machine. They can't talk to each other. Agent Relay fixes that.
 
-- **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
+- **Direct messaging**: `"tell the backend agent to check the migration"`
+- **Capability routing**: send to `cap:review` and any agent with that skill picks it up
+- **Labels**: name your sessions (`"backend fixing"`) and address them naturally
+- **Claim-based tasks**: post a task, exactly one agent grabs it (atomic, no duplicates)
+- **Threading**: full conversation chains between agents
+- **Live dashboard**: agents, messages, and stats in real time
 
-## How It Works
+## Quick Start
 
+### 1. Start the relay server
+
+```bash
+# requires Bun (https://bun.sh)
+bunx agent-relay-server
 ```
-┌──────────────┐     ┌──────────────┐     ┌──────────────┐
-│ Claude Code  │     │ Claude Code  │     │ Claude Code  │
-│  Session A   │     │  Session B   │     │  Session C   │
-│  (machine 1) │     │  (machine 1) │     │  (machine 2) │
-└──────┬───────┘     └──────┬───────┘     └──────┬───────┘
-       │                    │                    │
-       └────────────────────┼────────────────────┘
-                            │
-                    ┌───────▼───────┐
-                    │  Agent Relay  │
-                    │  HTTP + SQLite│
-                    │  :4850        │
-                    └───────────────┘
+
+Dashboard at `http://localhost:4850`.
+
+### 2. Install the Claude Code plugin
+
+Requires **Claude Code 2.1.105+** (native plugin monitors).
+
+```bash
+claude plugin marketplace add edimuj/agent-relay
+claude plugin install agent-relay@agent-relay
 ```
 
-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.
+### 3. Done. It's autonomous
 
-## Quick Start
+There is no step 3. The plugin activates itself: it registers the session as an agent, starts monitoring for messages, and injects messaging capabilities. No user interaction required.
 
-### 1. Start the relay server
+Open a second Claude Code session and say:
+
+> "Send a message to the other agent: hey, what are you working on?"
+
+## Codex Quick Start
+
+Codex support uses the same relay server, plus a Codex plugin, a SessionStart
+hook, and a managed app-server launcher.
 
 ```bash
-# requires Bun (https://bun.sh)
+# terminal 1: central relay server
 bunx agent-relay-server
+
+# one-time installer
+curl -fsSL https://raw.githubusercontent.com/edimuj/agent-relay/main/codex/install-codex.sh | bash
+
+# start Codex with live Agent Relay support after restarting your shell
+codex-relay
 ```
 
-The server starts on `http://localhost:4850`. Open it in a browser to see the dashboard.
+`codex-relay` launches `codex app-server`, opens Codex through
+`codex --remote`, registers the session as an Agent Relay agent, injects
+incoming messages as live turns, and cleans up sidecar processes when Codex
+exits.
 
-Or from source:
+Use a remote relay server by setting:
 
 ```bash
-git clone https://github.com/edimuj/agent-relay.git
-cd agent-relay
-bun run dev
+export AGENT_RELAY_URL=http://100.x.y.z:4850
+bunx -p agent-relay-server codex-relay
 ```
 
-### 2. Install the Claude Code plugin
+If you install the package globally, the shorter command works too:
 
-Requires **Claude Code 2.1.105+** (native plugin monitors).
+```bash
+bun install -g agent-relay-server
+codex-relay
+```
+
+On Windows PowerShell:
+
+```powershell
+irm https://raw.githubusercontent.com/edimuj/agent-relay/main/codex/install-codex.ps1 | iex
+codex-relay
+```
+
+The installer always adds `codex-relay` and asks whether plain `codex` should
+also route through Agent Relay. If you opt out, `codex` stays unchanged.
+Without restarting your shell first, use:
 
 ```bash
-claude plugin marketplace add edimuj/agent-relay
-claude plugin install agent-relay@agent-relay
+bunx -p agent-relay-server codex-relay
 ```
 
-Or for local development:
+Non-interactive alias opt-in:
 
 ```bash
-claude --plugin-dir ./claude
+curl -fsSL https://raw.githubusercontent.com/edimuj/agent-relay/main/codex/install-codex.sh | bash -s -- --alias
 ```
 
-### 3. Start talking
+```powershell
+$env:AGENT_RELAY_CODEX_ALIAS = "1"; irm https://raw.githubusercontent.com/edimuj/agent-relay/main/codex/install-codex.ps1 | iex
+```
 
-Every Claude Code session now auto-registers as an agent. In any session:
+## What the Agent Sees
 
-> "Tell the other agent to check the test results"
+When a session starts, the plugin's background monitor registers the agent and outputs its identity and messaging instructions as a notification. The agent is immediately aware of the relay and ready to communicate:
 
-> "Send a broadcast: deployment is done"
+```
+Agent Relay active. Your agent ID: macmini2-cli-myproject-a1b2c3
+Relay URL: http://localhost:4850 | Server: 0.3.0 | Plugin: 0.3.0
+```
 
-> "Send to cap:review — please review src/db.ts"
+Incoming messages arrive as monitor notifications. The agent sees them without being prompted:
 
-## Message Targeting
+```
+[msg:42] from backend-agent: Migration looks clean, tests pass. Ready to merge.
+```
 
-Messages can be addressed five ways:
+## Message Targeting
 
 | Target | Example | Behavior |
 |--------|---------|----------|
@@ -91,20 +134,75 @@ Messages can be addressed five ways:
 | Label | `"label:test writer"` | All agents with that human-set label |
 | Broadcast | `"broadcast"` | Everyone |
 
-## Claim-Based Task Routing
+## Deployment
 
-For tasks that should be handled by exactly one agent:
+Single process, embedded SQLite, no external dependencies beyond Bun.
 
 ```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}'
+bunx agent-relay-server                         # localhost only
+PORT=8080 HOST=0.0.0.0 bunx agent-relay-server  # remote access
 ```
 
-The first agent to claim it wins (atomic, 409 on conflict). Other agents never see it in their inbox.
+For multi-machine setups, run the server on one machine and set `AGENT_RELAY_URL` on the others (works great over [Tailscale](https://tailscale.com)):
+
+```bash
+export AGENT_RELAY_URL=http://100.x.y.z:4850
+```
 
-## API
+### Server environment variables
+
+| Variable | Default | Purpose |
+|----------|---------|---------|
+| `PORT` | `4850` | Server port |
+| `HOST` | `127.0.0.1` | Bind address |
+| `DB_PATH` | `agent-relay.db` | SQLite database path |
+| `RETENTION_DAYS` | `30` | Auto-prune messages older than this |
+
+### Plugin environment variables
+
+| Variable | Default | Purpose |
+|----------|---------|---------|
+| `AGENT_RELAY_URL` | `http://localhost:4850` | Relay server URL |
+| `AGENT_RELAY_CAPS` | `chat` | Comma-separated agent capabilities |
+
+Agent IDs are deterministic: `{hostname}-{rig}-{project}-{pid-hash}`.
+
+### Running as a systemd service
+
+```bash
+# create user service
+mkdir -p ~/.config/systemd/user
+cat > ~/.config/systemd/user/agent-relay.service << 'EOF'
+[Unit]
+Description=Agent Relay
+After=network.target
+
+[Service]
+ExecStart=%h/.bun/bin/bunx agent-relay-server
+Environment=HOST=0.0.0.0
+Restart=always
+
+[Install]
+WantedBy=default.target
+EOF
+
+systemctl --user daemon-reload
+systemctl --user enable --now agent-relay
+```
+
+### Version compatibility
+
+The plugin checks the server version on startup and warns if they diverge. Both packages share version numbers. Update them together:
+
+```bash
+# update server (just restart, bunx pulls latest)
+systemctl --user restart agent-relay
+
+# update plugin
+claude plugin update agent-relay@agent-relay
+```
+
+## API Reference
 
 Base URL: `http://localhost:4850/api`
 
@@ -133,72 +231,56 @@ Base URL: `http://localhost:4850/api`
 | `DELETE` | `/messages/:id` | Delete message |
 | `GET` | `/messages/cursor` | Latest message ID (for poller bootstrap) |
 
-### Stats
+### Server-Sent Events
 
 | Method | Path | Purpose |
 |--------|------|---------|
-| `GET` | `/stats` | Agent counts, message counts |
+| `GET` | `/events` | SSE stream (`?for=agentId` for filtered, omit for firehose) |
 
-## Plugin Configuration
+Events: `message.new`, `message.claimed`, `message.deleted`, `agent.status`, `agent.removed`
 
-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`.
+### Stats
 
-Agent IDs are deterministic: `{hostname}-{rig}-{project}-{pid-hash}`.
+| Method | Path | Purpose |
+|--------|------|---------|
+| `GET` | `/stats` | Version, agent counts, message counts |
 
 ## Architecture
 
 ```
 src/
-├── index.ts      # Bun.serve entry point, static files, CORS
+├── index.ts      # Bun.serve entry, static files, CORS
 ├── routes.ts     # HTTP router and API handlers
 ├── db.ts         # SQLite schema, queries, CRUD
+├── sse.ts        # Server-Sent Events
 └── types.ts      # TypeScript interfaces
 
 public/
-└── index.html    # Dashboard SPA
+└── index.html    # Dashboard SPA (Alpine.js + Tabler)
 
-claude/
-├── .claude-plugin/plugin.json   # Plugin manifest
-├── monitors/
-│   └── monitors.json            # Auto-start inbox monitor
+claude/                              # Claude Code plugin
+├── .claude-plugin/plugin.json
+├── monitors/monitors.json           # Auto-start inbox monitor
 └── hooks/
-    ├── hooks.json               # SessionEnd event
-    ├── relay-monitor.sh         # Register agent, inject context, poll inbox
-    ├── session-end.sh           # Mark agent offline
-    └── poll-inbox.sh            # Inbox poll loop
+    ├── relay-monitor.sh             # Register, inject context, poll
+    ├── session-end.sh               # Mark agent offline
+    └── poll-inbox.sh                # Inbox poll loop
+
+codex/                               # Codex integration
+├── live-sidecar.ts                   # App-server <-> relay bridge
+├── hooks/session-start.ts            # Starts one sidecar per launched thread
+└── plugin/                           # Codex plugin bundle
 ```
 
-## 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.
+## Development
 
 ```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
+git clone https://github.com/edimuj/agent-relay.git
+cd agent-relay
+bun run dev                    # server with hot reload
+claude --plugin-dir ./claude   # test plugin locally
 ```
 
-| 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