<div align="center">

<br/>

<img src="src-tauri/icons/source/relay-icon.svg" alt="Relay" width="120" height="120"/>

Relay

The missing human checkpoint for AI coding agents.

Give your AI agent a "pause & ask" button — review, correct, or enrich every step before it runs.

<p align="center"> <a href="https://github.com/andeya/ide-relay-mcp/releases/latest"><img src="https://img.shields.io/badge/platform-Win%20%7C%20Mac%20%7C%20Linux-888888?style=flat-square" alt="Platform"/></a> <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-6366f1?style=flat-square" alt="License"/></a> <a href="https://tauri.app/"><img src="https://img.shields.io/badge/Tauri-2-24adc8?style=flat-square&logo=tauri&logoColor=white" alt="Tauri 2"/></a> <a href="https://www.rust-lang.org/"><img src="https://img.shields.io/badge/Rust-MCP%20%2B%20HTTP-000000?style=flat-square&logo=rust&logoColor=white" alt="Rust"/></a> <a href="https://vuejs.org/"><img src="https://img.shields.io/badge/Vue-3-42b883?style=flat-square&logo=vuedotjs&logoColor=white" alt="Vue 3"/></a> </p>

Download · 简体中文

Author: andeya · andeyalee@outlook.com

<br/>

</div>

<p align="center"> <img src="docs/ScreenShot_1.png" alt="Relay MCP hub next to Cursor IDE" width="920" style="max-width:100%; height:auto;" /> </p> <p align="center">_{<strong>Relay</strong> beside your IDE — the agent pauses, you review & answer, it continues. All in one <code>tools/call</code>.}</p>

---

Why Relay?

AI coding agents are powerful — but blindly autonomous agents are risky and wasteful. Without a checkpoint, agents go on tangents, make mistakes that cascade into multiple correction rounds, and burn through your precious plan quota on wasted requests.

Relay adds a human-in-the-loop (HITL) checkpoint to any MCP-capable agent. The agent calls one tool — relay_interactive_feedback — and blocks until you submit your Answer (text, images, files). The result returns on the same JSON-RPC round trip. You catch issues early, guide accurately, and make every request count — no cloud dashboards, no extra SaaS, just a native desktop window beside your IDE.

Key advantages

Works with any MCP IDE	First-class support for Cursor, Claude Code, Windsurf, and a generic mode for others.
100% local	All data stays on your machine — loopback HTTP only, zero telemetry, no phone-home.
One resident GUI	A single persistent window (not a popup per request) with multi-tab session management.
No ARG_MAX limits	retell travels as HTTP JSON body (up to 16 MiB), not shell argv.
Session continuity	relay_mcp_session_id links turns into coherent sessions with MM-DD HH:mm:ss tab labels.
Rich feedback	Text, screenshots, file attachments — everything the agent needs in one round trip.
Save your plan quota	Catch mistakes early and guide precisely — no more wasted correction rounds burning through premium requests.

---

Multi-IDE support

Launch Relay and pick your IDE. Each mode unlocks IDE-specific features — one-click MCP injection, tailored rule prompts, and (for Cursor) real-time usage monitoring.

<p align="center"> <img src="docs/ScreenShot_0.png" alt="Relay IDE selection page" width="520" style="max-width:100%; height:auto;" /> </p> <p align="center">_{Click a card to enter that IDE mode — all settings, CLI commands, and MCP config adapt automatically.}</p>

IDE	MCP injection	Rule prompts	Usage monitoring
Cursor	✅	✅	✅
Claude Code	✅	✅	—
Windsurf	✅	—	—
Other	manual	—	—

---

Quick start

1. Install — Grab the latest release (macOS, Linux, Windows) or build from source.

macOS — Gatekeeper / quarantine: CI-built .app bundles are not Apple-notarized (that requires a paid Developer ID certificate). Downloads from the browser get the com.apple.quarantine attribute, which can trigger “can’t be opened” or “damaged” warnings. Without a paid cert there is no fully automatic fix for all users; options are:

• Recommended: In Finder, Control-click (or right-click) the app → Open and confirm once (stores an exception for that app).
• CLI (one-time): clear quarantine after copying the app to Applications (adjust the path if yours differs):

xattr -dr com.apple.quarantine "/Applications/Relay.app"

2. Launch & choose IDE — Run relay and click your IDE card, or go directly:

relay gui-cursor        # Cursor mode
relay gui-claudecode    # Claude Code mode
relay gui-windsurf      # Windsurf mode

3. Wire MCP — Point your IDE at the Relay binary. Example for Cursor:

{
  "mcpServers": {
    "relay-mcp": {
      "command": "/path/to/relay",
      "args": ["mcp-cursor"],
      "autoApprove": ["relay_interactive_feedback"]
    }
  }
}

Cursor uses .cursor/mcp.json (per-repo, merged with ~/.cursor/mcp.json). For WSL agent + Windows relay.exe, add --exe_in_wsl: ["mcp-cursor", "--exe_in_wsl"]. See docs/HTTP_IPC.md for details.

Or use Settings → Environment & MCP inside Relay for one-click setup and to copy the MCP JSON directly:

<p align="center"> <img src="docs/ScreenShot_3.png" alt="Relay Settings Environment and MCP" width="440" style="max-width:100%; height:auto;" /> </p> <p align="center">_{<strong>Settings → Environment & MCP</strong> — PATH detection, one-click MCP injection, copy JSON, pause MCP.}</p>

4. Install rule prompts — Go to Settings → Rule prompts and install with one click. This teaches the agent to call relay_interactive_feedback every turn and maintain relay_mcp_session_id.

<p align="center"> <img src="docs/ScreenShot_4.png" alt="Relay Settings Rule prompts" width="440" style="max-width:100%; height:auto;" /> </p> <p align="center">_{<strong>Settings → Rule prompts</strong> — one-click install into your IDE's rule configuration.}</p>

Cursor rule file — One-click install writes relay-interactive-feedback.mdc under user ~/.cursor/rules/ (Windows: %USERPROFILE%\.cursor\rules\). That path is separate from a repo’s .cursor/rules/; copy or symlink there if you only use project rules.

Agent still skips relay_interactive_feedback? Ensure MCP server relay-mcp is enabled; approve the tool when prompted (or set "autoApprove": ["relay_interactive_feedback"]); reload Cursor after editing the rule file on disk. Rule files guide the model — they are not hard guarantees.

---

Relay human-in-the-loop (end-to-end)

After Quick start steps 2–4, each turn follows this path (transport detail: docs/HTTP_IPC.md; vocabulary: docs/TERMINOLOGY.md):

sequenceDiagram
  participant Agent
  participant Mcp as relay_mcp-ide
  participant Http as GUI_HTTP_127.0.0.1
  participant You

  Agent->>Mcp: tools/call relay_interactive_feedback (retell, session, commands/skills…)
  Mcp->>Http: POST /v1/feedback → request_id
  Http->>You: tab shows retell
  You->>Http: Answer / dismiss / idle cutoff
  Http-->>Mcp: GET …/wait → JSON result
  Mcp-->>Agent: same tools/call response

1. MCP runs — The IDE launches relay mcp-<cli_id> (stdio), e.g. mcp-cursor. The matching GUI is relay gui-<cli_id> (often already open).
2. Agent calls the tool — Non-empty retell. New session: omit relay_mcp_session_id (or empty) and send commands and skills (each may be [] only if the host truly exposes nothing). Continue: pass the relay_mcp_session_id from the previous result.
3. MCP reaches the GUI — Reads gui_endpoint_<cli_id>.json in your Configuration & paths directory (e.g. gui_endpoint_cursor.json), or spawns relay gui-<cli_id> and waits ≤ ~45 s. Then POST /v1/feedback and blocks on GET /v1/feedback/wait/:id until the tab completes.
4. You interact — Submit Answer, attach files, dismiss, or let the ~60 min idle cleanup return empty human (same as dismiss from the agent’s perspective).
5. Same JSON-RPC returns — Body includes relay_mcp_session_id, human, cmd_skill_count, optional attachments. The next turn must send that relay_mcp_session_id unless starting a new tab.

Rules vs MCP: Step 4’s rule prompt install writes relay-interactive-feedback.mdc under user ~/.cursor/rules/ (Cursor only). Rules encourage the loop; relay-mcp in MCP settings executes it.

---

Architecture

flowchart LR
  IDE[IDE / Agent] -->|stdio JSON-RPC| MCP["relay mcp-{ide}"]
  MCP -->|read or spawn| GUI["relay gui-{ide}"]
  MCP <-->|127.0.0.1 Bearer| HTTP[Tauri HTTP API]
  HTTP <--> UI[Vue tabs]
  UI --- User((You))
  MCP -->|JSON result| IDE

• relay mcp-{ide} — Stdio MCP server (clap). Handles initialize, tools/list, tools/call. Concurrent human rounds on one connection. Optional auto-reply rules.
• relay / relay gui-<cli_id> — Tauri app + HTTP on 127.0.0.1:0. Writes gui_endpoint_<cli_id>.json (e.g. gui_endpoint_cursor.json) with { port, token, pid }; cleans up on exit.
• Bridge — MCP reads the endpoint file; if missing, spawns gui-{ide} and polls up to ~45 s. Then POST /v1/feedback → GET /v1/feedback/wait/:id. The wait resolves on submit, dismiss, supersede, or ~60 min idle.

---

MCP tool: relay_interactive_feedback

Argument	Required	Meaning
retell	yes (non-empty)	This turn's user-visible assistant reply, verbatim.
relay_mcp_session_id	if you have one	Continue the same session; returned in the JSON result.
commands	new tab: required	Array of IDE commands for slash-completion. [] only if the host truly has none.
skills	same as commands	Array of IDE skills. Same merge/dedupe rules.

Pause MCP (Settings): sentinel <<<RELAY_MCP_PAUSED>>> — do not call again until resumed.

<p align="center"> <img src="docs/ScreenShot_2.png" alt="Relay composer slash menu" width="440" style="max-width:100%; height:auto;" /> </p> <p align="center">_{<strong>Slash completion</strong> — <code>commands</code> and <code>skills</code> populate the palette with optional category badges.}</p>

---

Features at a glance

• Multi-tab hub — Each request opens or refreshes a tab. relay_mcp_session_id merges streams. Labels show MM-DD HH:mm:ss with turn-status color indicators.
• Rich composer — Enter to submit, Shift+Enter for newline, ⌘/Ctrl+Enter to submit & close. Paste images, attach files — they appear as attachments in the tool result.
• Cursor Usage monitoring — Auto-detect your Cursor token (cross-platform decryption), view plan quotas, request history, and predicted quota exhaustion in a live popover.
• Auto-reply — auto_reply_oneshot.txt / auto_reply_loop.txt for instant 0|reply responses without opening the UI.
• Local storage — feedback_log.txt, qa_archive/<session_id>.jsonl, configurable attachment retention (default 30 days).
• CLI — relay feedback --retell "…" prints JSON on stdout; --timeout for CI/automation.

<p align="center"> <img src="docs/ScreenShot_5.png" alt="Relay Settings Cache" width="440" style="max-width:100%; height:auto;" /> </p> <p align="center">_{<strong>Settings → Cache</strong> — attachment + log usage, open folder, auto-clean.}</p>

---

CLI reference

Command	Role
relay	Open IDE selection page
relay gui-cursor	Launch GUI in Cursor mode
relay gui-claudecode	Launch GUI in Claude Code mode
relay gui-windsurf	Launch GUI in Windsurf mode
relay mcp-cursor	MCP stdio server for Cursor (what the IDE runs)
relay mcp-claudecode	MCP stdio server for Claude Code
relay mcp-windsurf	MCP stdio server for Windsurf
relay feedback --retell "…"	Terminal tryout; --timeout, --relay-mcp-session-id

Only one GUI process per IDE mode is allowed; bare relay (no mode) can run multiple instances.

---

Configuration & paths

Data lives under your OS application-data directory (directories::ProjectDirs → config_dir()):

OS	Path
macOS	~/Library/Application Support/com.relay.relay-mcp/
Linux	~/.config/relay-mcp/
Windows	%APPDATA%\relay\relay-mcp\config\

Key files: feedback_log.txt, qa_archive/*.jsonl, ui_locale.json, gui_endpoint_<cli_id>.json (e.g. gui_endpoint_cursor.json), relay_gui_<cli_id>_alive.marker, mcp_pause.json, attachment_retention.json, auto_reply_*.txt, legacy gui_endpoint.json when applicable.

---

Build

npm install
npm run build          # Vite frontend
cargo build --manifest-path src-tauri/Cargo.toml --release
npm run tauri build    # installers / .app / etc.

Develop:

npm run lint && npm run typecheck
npm run tauri:dev

Icons (from src-tauri/icons/source/relay-icon.svg):

npm run icons:build

CI: lint, typecheck, Vite, cargo fmt, clippy -D warnings, cargo test — see docs/RELEASING.md.

---

Documentation

Doc	Content
docs/HTTP_IPC.md	HTTP API, timeouts, WSL path rewrite
docs/RELAY_MCP_SESSION_ID.md	Session ID & tab labels
docs/TERMINOLOGY.md	Vocabulary + binaries / endpoint files
docs/RELEASING.md	Releases & CI

---

Privacy

Data stays on device. All answers, logs, attachments, and settings are written only under your OS user paths. The GUI and MCP process communicate over 127.0.0.1 — nothing leaves your machine.

No telemetry. Relay ships no analytics SDKs, crash reporters, or remote instrumentation. Local files like feedback_log.txt may contain sensitive content — handle them accordingly.

---

Acknowledgements

Inspired by interactive-feedback-mcp. Relay replaces per-request subprocess UIs with a resident GUI and a Bearer-authenticated local HTTP layer.

---

License

MIT