Fairmind Agent Relay

Local relay that connects Fairmind Studio to coding agents via ACP (Agent Communication Protocol).

Supported Agents

| Agent | Protocol | Auto-detected | |-------|----------|---------------| | Claude Code | SDK | claude in PATH | | Cursor | ACP stdio | agent in PATH | | GitHub Copilot | ACP stdio | copilot in PATH | | OpenAI Codex | ACP stdio | codex in PATH | | Gemini CLI | ACP stdio | gemini in PATH |

The relay auto-discovers installed agents and reports them to Studio.

Prerequisites

• Node.js v18+ — download (includes npx)
• At least one supported agent installed locally

Quick Start

npx @fairmind/agent-relay \
  --token <JWT> \
  --studio-url wss://studio.fairmind.ai/api/implementation/ws

Get your JWT token from the Studio UI (Implementation tab > "Copy Relay Token").

Options

| Flag | Description | Default | |------|-------------|---------| | --token <jwt> | JWT authentication token from Studio | required | | --studio-url <url> | WebSocket URL of Fairmind Studio | required | | --timeout <seconds> | Agent process timeout | 1800 (30 min) | | --log-level <level> | Log level (debug, info, warn, error) | info | | --plugin-path <path> | Path to fairmind-integration plugin | auto-cloned |

How It Works

1. The relay connects to Studio via WebSocket and reports available agents
2. When you launch a task in Studio, it sends a spawn command with task context
3. The relay spawns the appropriate agent locally:
   • Claude Code → via the Agent SDK (@anthropic-ai/claude-agent-sdk)
   • Cursor / Copilot / Codex / Gemini → via ACP JSON-RPC over stdio
4. Agent events (progress, tool use, results, costs) are translated to a common ACP format and streamed to Studio in real-time
5. Studio can send follow-up messages, respond to agent questions, or cancel tasks mid-execution

Key Features

• Multi-agent — run different agents on different tasks simultaneously
• Attachments — send images, files, and PDFs to agents alongside prompts
• Cost tracking — token usage and estimated USD cost per task
• Session recovery — sessions are persisted to ~/.fairmind/sessions/; the relay recovers stale sessions on reconnect
• Human-in-the-loop — agents can ask questions; Studio users respond in real-time
• MCP forwarding — user's MCP servers from ~/.claude.json are forwarded to SDK agents

Development

npm install
npm test
npm run build