relayBrain

The problem

You brief Cursor on Monday. Wednesday you switch to Claude Code — and start from zero. Every agent keeps its own little memory file (CLAUDE.md, .cursorrules, copilot-instructions.md, …), none of them talk to each other, and you become the human clipboard carrying context between tools.

The fix

Relay keeps one shared .relay/ brain that every agent reads and writes — and patches each agent's instruction file to point at it automatically.

- 5 agents · 5 memory files · 0 shared context
+ 5 agents · 1 project brain · always in sync

One install gives you the CLI, stop hooks, agent prompts, the relay-sync skill, .relay/ scaffolding, the Mission Control UI, and an optional MCP server.

Quick start

cd your-project
relay init          # .relay/, hooks, prompts, API key
relay serve         # Mission Control → :6374  ·  API → :3001
relay watch .       # background sync (keep running)

Work in any agent. Stop hooks (or /relay update) refresh the IR markdown. Switch agents → /relay context or just read .relay/relay_context.md.

Requires Node.js 18+. No database. First relay serve installs Mission Control deps automatically.

How it works

  Cursor ──┐
  Claude ──┤   stop hooks + watch     ┌─────────────┐
  Copilot ─┼──► sync ──► memory.json ─►│  .relay/    │──► relay_context.md
  Codex ───┤         compile_brief     │  IR .md     │         │
  Antigravity ┘      (agent updates)   └─────────────┘         ▼
                                                          next agent reads handoff

relay watch = sync + compile only · relay refresh = sync + compile + context

What relay init creates

your-project/
├── .relay/
│   ├── AGENT_BOOTSTRAP.md       ← read every session
│   ├── relay_context.md         ← handoff file
│   ├── compile_brief.md         ← agent reads to update IR
│   ├── project.md · current_task.md · decisions.md · failures.md
│   ├── memory.json              ← unified timeline
│   ├── project.json             ← API key + dashboard URL
│   └── hooks/
├── RELAY.md
├── CLAUDE.md · AGENTS.md · .github/copilot-instructions.md · .cursorrules
├── .cursor/hooks.json + .cursor/skills/relay-sync/
├── .claude/settings.json · .codex/hooks.json · .agents/hooks.json

Registry (all projects): ~/.relay-os/projects.json

Commands

Pseudo-commands — patched into agent instructions, not native slash commands:

Terminal shortcut: relay refresh . ≈ /relay update

Mission Control

Started by relay serve — runs locally, no login.

Activity timeline across all agents · live IR markdown · per-project API keys.

MCP (optional)

Give agents direct tool access to .relay/ — list files, read/write IR markdown, sync, fetch handoff.

Tools exposed: relay_list_files · relay_read_file · relay_write_file · relay_get_context · relay_sync

Hooks + pseudo-commands are enough for most workflows. MCP is for agents where you want structured file tools on top.

After relay init, note:

• Project path — absolute path to your repo
• API key — printed at init (also in .relay/project.json) — only needed for remote mode

Always set RELAY_WORKSPACE_PATH to your project root (required — MCP may not inherit the right cwd):

"env": {
  "RELAY_WORKSPACE_PATH": "/absolute/path/to/your-project"
}

Local mode (reads/writes .relay/ on disk — default):

{
  "command": "npx",
  "args": ["-y", "relay-os", "mcp"],
  "env": {
    "RELAY_WORKSPACE_PATH": "/absolute/path/to/your-project"
  }
}

If relay is on your PATH (npm link / global install):

{
  "command": "relay",
  "args": ["mcp"],
  "env": {
    "RELAY_WORKSPACE_PATH": "/absolute/path/to/your-project"
  }
}

Remote mode (via relay serve API — useful when UI/API is already running):

{
  "command": "npx",
  "args": ["-y", "relay-os", "mcp"],
  "env": {
    "RELAY_WORKSPACE_PATH": "/absolute/path/to/your-project",
    "RELAY_API_URL": "http://localhost:3001",
    "RELAY_API_KEY": "relay_your_key_from_init"
  }
}

Cursor — .cursor/mcp.json (project) or user MCP settings

{
  "mcpServers": {
    "relay": {
      "command": "npx",
      "args": ["-y", "relay-os", "mcp"],
      "env": {
        "RELAY_WORKSPACE_PATH": "/absolute/path/to/your-project"
      }
    }
  }
}

Restart Cursor or reload MCP. Relay tools appear in Agent mode.

Claude Code — .mcp.json (project) or ~/.claude.json

{
  "mcpServers": {
    "relay": {
      "command": "npx",
      "args": ["-y", "relay-os", "mcp"],
      "env": {
        "RELAY_WORKSPACE_PATH": "/absolute/path/to/your-project"
      }
    }
  }
}

Or via CLI: claude mcp add relay -- npx -y relay-os mcp (set env in config after).

GitHub Copilot — VS Code .vscode/mcp.json or Copilot CLI MCP config

VS Code / Copilot (mcp.json):

{
  "servers": {
    "relay": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "relay-os", "mcp"],
      "env": {
        "RELAY_WORKSPACE_PATH": "${workspaceFolder}"
      }
    }
  }
}

Copilot CLI — add to your MCP config file per Copilot MCP docs:

{
  "mcpServers": {
    "relay": {
      "command": "npx",
      "args": ["-y", "relay-os", "mcp"],
      "env": {
        "RELAY_WORKSPACE_PATH": "/absolute/path/to/your-project"
      }
    }
  }
}

Codex CLI — ~/.codex/config.toml or project config

[mcp_servers.relay]
command = "npx"
args = ["-y", "relay-os", "mcp"]

[mcp_servers.relay.env]
RELAY_WORKSPACE_PATH = "/absolute/path/to/your-project"

Antigravity — MCP settings (same JSON shape as Cursor)

{
  "mcpServers": {
    "relay": {
      "command": "npx",
      "args": ["-y", "relay-os", "mcp"],
      "env": {
        "RELAY_WORKSPACE_PATH": "/absolute/path/to/your-project"
      }
    }
  }
}

# Should print: relay-mcp started (local mode, workspace: ...)
RELAY_WORKSPACE_PATH=/path/to/project relay mcp

🎬 Example: three agents, one portfolio

Day 1 — Cursor builds the hero. Stop hook runs. You type /relay update.

## Now   ← .relay/current_task.md
- Hero done (gradient + CTA)
- Next: projects grid

Day 2 — Claude Code opens the same folder. /relay context → implements the grid without re-briefing.

Day 3 — Copilot CLI fixes form validation, appends to .relay/failures.md.

With relay serve + relay watch . running, Mission Control shows all three agents on one timeline.

🔁 Switch checklist: /relay update → open same folder in new tool → /relay context

Dependencies

Storage: .relay/ in your project + ~/.relay-os/projects.json — files only, no DB server.

Env vars: RELAY_PORT (3001) · RELAY_UI_PORT (6374) · RELAY_API_KEY (optional API auth) · RELAY_SKIP_UI_INSTALL=1

🪝 Stop hooks

Installed in your project folder by relay init:

Disable: .relay/config.json → "autoAgentUpdate": false

📚 Docs

docs/QUICKSTART.md