Agent Relay Orchestrator#

Manage multiple Claude Code workers from a single control point. Spawn, route, suspend, and resume persistent AI sessions with full context preservation.

Important: This skill assumes the Agent Relay Orchestrator is running on http://localhost:3890. Start it with npm start in the repo directory before using these commands.

Prerequisites#

• Claude Code CLI installed and authenticated
• Node.js 20+
• The orchestrator repo cloned and configured (see README)

Setup#

bash

git clone https://github.com/TheAgentAcademy/agent-relay-orchestrator.git
cd agent-relay-orchestrator
npm install
cp .env.example .env
# Edit .env with your Notion credentials
npm start

API Endpoints#

The orchestrator exposes an HTTP API on port 3890 (configurable via RELAY_PORT).

Health Check#

bash

curl http://localhost:3890/health

Returns service status, active workers, and ticker state.

Spawn a Worker#

bash

curl -X POST http://localhost:3890/spawn \
  -H 'Content-Type: application/json' \
  -d '{"name": "ReviewWorker", "task": "You review pull requests and suggest improvements."}'

Optional: pass "continueFrom": "<sessionId>" to resume a previous session.

Send a Message#

bash

curl -X POST http://localhost:3890/send \
  -H 'Content-Type: application/json' \
  -d '{"to": "CodeWorker", "text": "refactor the auth module to use JWT"}'

If the target worker is suspended, it auto-resumes. If it doesn't exist but has a profile, it spawns.

List Active Workers#

bash

curl http://localhost:3890/workers

Returns name, status, label, project, and last message time for each active worker.

List All Projects#

bash

curl http://localhost:3890/projects

Shows all workers (active + suspended) with session IDs and profile info.

Suspend a Worker#

bash

curl -X DELETE http://localhost:3890/worker/ReviewWorker

Session is preserved for future resume. Add ?purge=true to clear session permanently.

Event Feed#

bash

# All events
curl http://localhost:3890/events

# Events since a timestamp
curl "http://localhost:3890/events?since=2026-01-01T00:00:00Z&limit=50"

# Events for a specific worker
curl http://localhost:3890/sessions/CodeWorker/events

Stats#

bash

curl http://localhost:3890/stats

Returns total events, total sessions, events in last 24h, and average latency.

Toggle Telegram Ticker#

bash

# Enable
curl -X POST http://localhost:3890/ticker \
  -H 'Content-Type: application/json' \
  -d '{"enabled": true}'

# Disable
curl -X POST http://localhost:3890/ticker \
  -d '{"enabled": false}'

Example Workflows#

Parallel Task Execution#

bash

# Spawn specialized workers
curl -X POST http://localhost:3890/spawn -d '{"name": "TestWorker", "task": "You run tests and report results."}'
curl -X POST http://localhost:3890/spawn -d '{"name": "DocWorker", "task": "You write documentation."}'

# Send tasks in parallel
curl -X POST http://localhost:3890/send -d '{"to": "TestWorker", "text": "run the full test suite"}'
curl -X POST http://localhost:3890/send -d '{"to": "DocWorker", "text": "update the API docs for the new auth endpoints"}'

# Check progress
curl http://localhost:3890/workers

Session Resume After Restart#

bash

# Worker state is persisted. After restarting the service:
npm start
# CodeWorker auto-resumes with full conversation context

Full Documentation#

See the GitHub repo for architecture docs, Notion setup guide, and worker lifecycle details.