relay-os 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Krishna Sai
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,389 @@
+<p align="center">
+  <strong>Relay</strong><br/>
+  <em>One project brain. Any coding agent.</em>
+</p>
+
+<p align="center">
+  <a href="https://nodejs.org"><img src="https://img.shields.io/badge/node-%3E%3D18-brightgreen?style=flat-square" alt="Node 18+"></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue?style=flat-square" alt="MIT"></a>
+  <img src="https://img.shields.io/badge/agents-Cursor%20%7C%20Claude%20%7C%20Copilot%20%7C%20Codex%20%7C%20Antigravity-8b5cf6?style=flat-square" alt="Agents">
+  <img src="https://img.shields.io/badge/storage-markdown%20%2B%20json-64748b?style=flat-square" alt="Storage">
+</p>
+
+<p align="center">
+  Git tracks your code. Relay tracks your <strong>project intelligence</strong> — tasks, decisions, failures, and what every agent did last session.<br/>
+  Switch tools without re-explaining the repo.
+</p>
+
+---
+
+## Why Relay
+
+Every coding agent wants its own instruction file — `CLAUDE.md`, `.cursorrules`, `copilot-instructions.md`, and so on. Relay patches them automatically and keeps **one shared `.relay/` brain** in sync across:
+
+| Cursor | Claude Code | GitHub Copilot | Codex | Antigravity |
+|:------:|:-----------:|:--------------:|:-----:|:-----------:|
+
+**One install** gives you the CLI, stop hooks, agent prompts, relay-sync skill, `.relay/` scaffolding, Mission Control UI, and an optional MCP server.
+
+---
+
+## Quick start
+
+```bash
+cd your-project
+npx relay-os init          # .relay/, hooks, prompts, API key
+npx relay-os serve         # Mission Control → :6374  ·  API → :3001
+npx relay-os watch .       # background sync (keep running)
+```
+
+Work in any agent. Stop hooks (or `/relay update`) refresh IR markdown. Switch agents → `/relay context` or read `.relay/relay_context.md`.
+
+<details>
+<summary><strong>Install options</strong></summary>
+
+| Method | Command |
+|--------|---------|
+| npm | `npx relay-os init` |
+| local dev | `npm link` in this repo, then `relay init` |
+| GitHub | `npx github:AspiringPianist/OrbitOS init` |
+
+Requires **Node.js 18+**. No database. First `relay serve` installs Mission Control deps automatically.
+
+</details>
+
+---
+
+## How it works
+
+```text
+  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
+```
+
+| Layer | Who runs it | Output |
+|-------|-------------|--------|
+| **Sync** | `relay watch`, stop hook, `relay sync` | `memory.json` + timeline |
+| **Compile** | same | `compile_brief.md` |
+| **IR update** | **you / the session agent** | `project.md`, `decisions.md`, … |
+| **Handoff** | `relay context` | `relay_context.md` |
+
+`relay watch` = sync + compile only. `relay refresh` = sync + compile + context.
+
+---
+
+## What `relay init` creates
+
+```text
+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
+
+| Command | Description |
+|---------|-------------|
+| `relay init [path]` | Scaffold `.relay/`, hooks, agent patches, API key |
+| `relay install [path]` | Re-apply hooks after upgrade |
+| `relay serve` | Mission Control (:6374) + API (:3001) |
+| `relay watch [path]` | Background sync + compile |
+| `relay sync [path]` | Harvest transcripts → `memory.json` |
+| `relay compile [path]` | Write `compile_brief.md` |
+| `relay context [path]` | Generate `relay_context.md` |
+| `relay refresh [path]` | sync + compile + context |
+| `relay mcp` | MCP server (stdio) — optional |
+| `relay open` | Print UI + API URLs |
+
+**Pseudo-commands** (patched into agent instructions — not native slash commands):
+
+| Say | Agent does |
+|-----|------------|
+| `/relay update` | sync → compile → update IR → `relay context .` |
+| `/relay context` | read `.relay/relay_context.md` |
+| `/relay init` | run `npx relay-os init` if missing |
+
+Terminal shortcut: `relay refresh .` ≈ `/relay update`
+
+---
+
+## Mission Control
+
+Started by `relay serve` — no login, runs locally.
+
+| | URL |
+|---|-----|
+| Dashboard | http://localhost:6374 |
+| API | http://localhost:3001/api/health |
+
+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.
+
+### 1. Get your paths
+
+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
+
+### 2. Base config
+
+Always set `RELAY_WORKSPACE_PATH` to your project root (required — MCP may not inherit the right cwd):
+
+```json
+"env": {
+  "RELAY_WORKSPACE_PATH": "/absolute/path/to/your-project"
+}
+```
+
+**Local mode** (reads/writes `.relay/` on disk — default):
+
+```json
+{
+  "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):
+
+```json
+{
+  "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):
+
+```json
+{
+  "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"
+  }
+}
+```
+
+### 3. Register per agent
+
+<details>
+<summary><strong>Cursor</strong> — <code>.cursor/mcp.json</code> (project) or user MCP settings</summary>
+
+```json
+{
+  "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.
+
+</details>
+
+<details>
+<summary><strong>Claude Code</strong> — <code>.mcp.json</code> (project) or <code>~/.claude.json</code></summary>
+
+```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).
+
+</details>
+
+<details>
+<summary><strong>GitHub Copilot</strong> — VS Code <code>.vscode/mcp.json</code> or Copilot CLI MCP config</summary>
+
+VS Code / Copilot (`mcp.json`):
+
+```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](https://docs.github.com/en/copilot/how-tos/use-copilot-agents/coding-agent/extend-coding-agent-with-mcp):
+
+```json
+{
+  "mcpServers": {
+    "relay": {
+      "command": "npx",
+      "args": ["-y", "relay-os", "mcp"],
+      "env": {
+        "RELAY_WORKSPACE_PATH": "/absolute/path/to/your-project"
+      }
+    }
+  }
+}
+```
+
+</details>
+
+<details>
+<summary><strong>Codex CLI</strong> — <code>~/.codex/config.toml</code> or project config</summary>
+
+```toml
+[mcp_servers.relay]
+command = "npx"
+args = ["-y", "relay-os", "mcp"]
+
+[mcp_servers.relay.env]
+RELAY_WORKSPACE_PATH = "/absolute/path/to/your-project"
+```
+
+</details>
+
+<details>
+<summary><strong>Antigravity</strong> — MCP settings (same JSON shape as Cursor)</summary>
+
+```json
+{
+  "mcpServers": {
+    "relay": {
+      "command": "npx",
+      "args": ["-y", "relay-os", "mcp"],
+      "env": {
+        "RELAY_WORKSPACE_PATH": "/absolute/path/to/your-project"
+      }
+    }
+  }
+}
+```
+
+</details>
+
+### Test MCP
+
+```bash
+# Should print: relay-mcp started (local mode, workspace: ...)
+RELAY_WORKSPACE_PATH=/path/to/project npx relay-os mcp
+```
+
+---
+
+## Example: three agents, one portfolio
+
+**Day 1 — Cursor** builds the hero. Stop hook runs. You type `/relay update`.
+
+`.relay/current_task.md`:
+```markdown
+## Now
+- Hero done (gradient + CTA)
+- Next: projects grid
+```
+
+**Day 2 — Claude Code** opens the same folder. `/relay context` → implements 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
+
+| | |
+|---|---|
+| **Required** | Node.js 18+, npm |
+| **Auto-installed** | `express`, `cors` (API) · `next`, `react` (Mission Control) |
+| **Not needed** | MongoDB, Redis, Docker, login/OAuth |
+| **Optional** | [`sqlite3` CLI](https://sqlite.org/download.html) on PATH — richer Copilot sync via VS Code `state.vscdb` (not an npm package) |
+| **Optional LLM keys** | `OPENAI_API_KEY` / `ANTHROPIC_API_KEY` for smarter `relay compile-ir` (heuristics work without) |
+
+**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`:
+
+| Agent | Config |
+|-------|--------|
+| Cursor | `.cursor/hooks.json` |
+| Claude Code | `.claude/settings.json` |
+| Codex | `.codex/hooks.json` |
+| Copilot CLI | `.github/hooks/relay-os.json` |
+| Antigravity | `.agents/hooks.json` |
+
+Disable: `.relay/config.json` → `"autoAgentUpdate": false`
+
+---
+
+## Docs
+
+[docs/QUICKSTART.md](docs/QUICKSTART.md)
+
+---
+
+<p align="center">
+  <sub>Git tracks code. Relay tracks what your agents know about the project.</sub>
+</p>

package/backend/hooks/relay-antigravity-stop.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+const { runStopHook } = require('./relay-hook-lib');
+runStopHook('antigravity').catch(() => process.exit(0));

package/backend/hooks/relay-claude-stop.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+const { runStopHook } = require('./relay-hook-lib');
+runStopHook('claude').catch(() => process.exit(0));

package/backend/hooks/relay-codex-stop.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+const { runStopHook } = require('./relay-hook-lib');
+runStopHook('codex').catch(() => process.exit(0));

package/backend/hooks/relay-copilot-stop.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+const { runStopHook } = require('./relay-hook-lib');
+runStopHook('copilot').catch(() => process.exit(0));

package/backend/hooks/relay-cursor-stop.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+const { runStopHook } = require('./relay-hook-lib');
+runStopHook('cursor').catch(() => process.exit(0));

package/backend/hooks/relay-hook-lib.js

@@ -0,0 +1,170 @@
+#!/usr/bin/env node
+/** Shared sync+compile + session-agent IR follow-up for all agent stop hooks. */
+const fs = require('fs');
+const path = require('path');
+const { spawnSync } = require('child_process');
+
+const AGENT_FOLLOWUP = `Relay IR update (required — do not ask the user):
+
+1. Read \`.relay/compile_brief.md\`
+2. Update these files under \`.relay/\`:
+   - \`project.md\` — overview, stack, goals
+   - \`current_task.md\` — in progress / next tasks
+   - \`decisions.md\` — open + resolved decisions
+   - \`failures.md\` — what failed or not to repeat
+   - \`architecture.md\` — only if the timeline changed architecture
+3. Run \`relay context .\` (or \`npx relay-os context .\`)
+4. Reply only: Relay memory updated.`;
+
+const CONTINUATION_MARKER = '.relay-hook-continuing';
+
+function readStdin() {
+  return new Promise(resolve => {
+    let data = '';
+    process.stdin.setEncoding('utf8');
+    process.stdin.on('data', chunk => {
+      data += chunk;
+    });
+    process.stdin.on('end', () => resolve(data));
+  });
+}
+
+function getRelayInvocation(workspacePath) {
+  try {
+    const manifest = JSON.parse(
+      fs.readFileSync(path.join(workspacePath, '.relay', 'install.json'), 'utf-8')
+    );
+    if (manifest.relayCommand) return { cmd: manifest.relayCommand, argsPrefix: [] };
+  } catch (_) {
+    /* fallback */
+  }
+  return { cmd: 'npx', argsPrefix: ['relay-os'] };
+}
+
+function loadConfig(workspacePath) {
+  try {
+    return JSON.parse(fs.readFileSync(path.join(workspacePath, '.relay', 'config.json'), 'utf-8'));
+  } catch (_) {
+    return {};
+  }
+}
+
+function markerPath(workspacePath) {
+  return path.join(workspacePath, '.relay', CONTINUATION_MARKER);
+}
+
+function clearContinuationMarker(workspacePath) {
+  try {
+    fs.unlinkSync(markerPath(workspacePath));
+  } catch (_) {
+    /* ignore */
+  }
+}
+
+function setContinuationMarker(workspacePath) {
+  fs.writeFileSync(markerPath(workspacePath), new Date().toISOString(), 'utf-8');
+}
+
+function hasContinuationMarker(workspacePath) {
+  return fs.existsSync(markerPath(workspacePath));
+}
+
+function runRelay(workspacePath, subcommand) {
+  const { cmd, argsPrefix } = getRelayInvocation(workspacePath);
+  spawnSync(cmd, [...argsPrefix, subcommand, '.'], {
+    cwd: workspacePath,
+    shell: true,
+    encoding: 'utf-8',
+    timeout: 120000,
+    stdio: 'ignore',
+  });
+}
+
+function shouldSkip(workspacePath, input, mode) {
+  if (!fs.existsSync(path.join(workspacePath, '.relay', 'config.json'))) {
+    return true;
+  }
+
+  const config = loadConfig(workspacePath);
+  if (config.autoAgentUpdate === false || config.autoUpdate === false) {
+    return true;
+  }
+
+  if (hasContinuationMarker(workspacePath)) {
+    clearContinuationMarker(workspacePath);
+    return true;
+  }
+
+  if (mode === 'cursor' && Number(input.loop_count || 0) > 0) {
+    return true;
+  }
+
+  if ((mode === 'claude' || mode === 'codex') && input.stop_hook_active === true) {
+    return true;
+  }
+
+  if (mode === 'antigravity' && input.fullyIdle === false) {
+    return true;
+  }
+
+  return false;
+}
+
+async function prepareAgentIrUpdate(workspacePath, input, mode) {
+  if (shouldSkip(workspacePath, input, mode)) {
+    return { skip: true };
+  }
+
+  runRelay(workspacePath, 'sync');
+  runRelay(workspacePath, 'compile');
+  setContinuationMarker(workspacePath);
+  return { skip: false, message: AGENT_FOLLOWUP };
+}
+
+function emitContinuation(mode, message) {
+  switch (mode) {
+    case 'cursor':
+      process.stdout.write(JSON.stringify({ followup_message: message }));
+      break;
+    case 'claude':
+      process.stderr.write(message);
+      process.exit(2);
+      return;
+    case 'codex':
+    case 'copilot':
+      process.stdout.write(JSON.stringify({ decision: 'block', reason: message }));
+      break;
+    case 'antigravity':
+      process.stdout.write(JSON.stringify({ decision: 'continue', reason: message }));
+      break;
+    default:
+      process.stdout.write(JSON.stringify({ followup_message: message }));
+  }
+}
+
+async function runStopHook(mode) {
+  const raw = await readStdin();
+  let input = {};
+  try {
+    input = raw ? JSON.parse(raw) : {};
+  } catch (_) {
+    input = {};
+  }
+
+  const workspacePath = process.cwd();
+  const result = await prepareAgentIrUpdate(workspacePath, input, mode);
+  if (result.skip) {
+    process.exit(0);
+  }
+
+  emitContinuation(mode, result.message);
+  process.exit(0);
+}
+
+module.exports = {
+  AGENT_FOLLOWUP,
+  readStdin,
+  prepareAgentIrUpdate,
+  emitContinuation,
+  runStopHook,
+};

package/backend/lib/relayAuth.js

@@ -0,0 +1,41 @@
+const { getProjectByApiKey } = require('./relayProjects');
+
+function getApiKey() {
+  return process.env.RELAY_API_KEY || '';
+}
+
+function extractToken(req) {
+  const header = req.headers.authorization || '';
+  if (header.startsWith('Bearer ')) return header.slice(7);
+  return req.headers['x-relay-api-key'] || '';
+}
+
+function requireApiKey(req, res, next) {
+  const globalKey = process.env.RELAY_API_KEY || '';
+  const token = extractToken(req);
+
+  if (globalKey && token === globalKey) return next();
+
+  const project = getProjectByApiKey(token);
+  if (project) {
+    req.relayProject = project;
+    return next();
+  }
+
+  if (!globalKey && !token) return next();
+
+  return res.status(401).json({
+    error: 'Invalid or missing API key. Use your project API key from the Relay dashboard.',
+  });
+}
+
+function isAuthEnabled() {
+  return Boolean(process.env.RELAY_API_KEY);
+}
+
+module.exports = {
+  getApiKey,
+  requireApiKey,
+  isAuthEnabled,
+  extractToken,
+};