relay

The relay between AI agents and humans — browser boards instead of terminal walls.

rly is a CLI that lets your AI agent ask questions and present work in a local browser board — real forms, charts, diagrams, sortable tables, images, and live prototypes instead of terminal text and ASCII art. You click, comment on any element, and Submit; the agent gets your answers and comments back as JSON and keeps working.

See it

The whole loop — your agent asks in the terminal, a board opens in your browser; you pick a style, expand the chart, comment on a data point, leave a note, Submit — and the agent picks up your answers and keeps going:

Quick start

# the rly CLI
npm i -g @khanglvm/relay

# the agent skill → every detected agent (Claude Code, Codex, Cursor, …)
npx skills add khanglvm/relay --skill relay --all

# enforce it (recommended) — a skill alone is an ignorable hint; `rly install`
# writes relay's usage rules into the file each agent reads (run `rly install`
# with no args to see every supported target and where it lands):
rly install --all          # every agent detected on this machine

That's it. Next time your agent needs a decision or wants to show you a plan, it opens a board like the ones above and waits for your Submit.

Keep relay current with rly upgrade — it installs the latest CLI and refreshes the skill (via npx skills, falling back to the bundled copy) in one step, leaving any boards you have open untouched.

Inside the Claude & Codex apps (MCP App)

relay also runs as an MCP App (SEP-1865) — so the same board renders inline, right in the conversation, on Claude desktop and mobile and in Codex, no browser tab. rly mcp is a stdio MCP server with no npm runtime dependencies; register it once and the agent gets two tools, relay_ask (collect decisions/feedback with real form controls) and relay_show (present a plan, diagram, diff, table, or prototype):

# Claude Code
claude mcp add relay -- rly mcp

# Claude Desktop / Codex — write the host config for you
rly mcp install --target claude     # claude_desktop_config.json
rly mcp install --target codex      # ~/.codex/config.toml

# or print the snippet for any MCP host (incl. the raw JSON/TOML)
rly mcp config

When the agent calls a relay tool, the host renders relay's ui://relay/board resource in a sandboxed iframe, hands it the board spec, and the user's answers flow back to the agent as a ui/message user turn, with ui/update-model-context used as a best-effort structured context sync — markdown, code, diffs, tables, charts, mermaid/graphviz diagrams, images, and forms, all in-chat. The classic browser board (rly ask / rly show) is unchanged; pick whichever surface fits.

What it improves

| Without relay | With relay | |---|---| | Six questions asked one at a time in the terminal | One board, all questions, real form controls, optional "Other" + notes | | "Option B is the one with caching (see my last message)" | Each answer option carries its own image / chart / diagram — pick by looking | | ASCII architecture art | Mermaid, Graphviz, PlantUML — zoomable, full-screen, even user-editable | | Numbers buried in prose | Charts and sortable tables; screenshots and HTML prototypes in a sandbox | | "Here's the diff — paste it in your editor" | Side-by-side diff blocks, syntax-highlighted code, video walkthroughs, and file paths you click to open in the default app | | "Which commits should I pick? Resolve this conflict manually." | rly git pick / rly git cherry-pick boards and color-coded git-conflict resolvers with ours/theirs/custom hunk choices | | "Type done when finished reviewing" | A Submit button; answers, notes, and inline comments returned as JSON | | Feedback = another wall of text | Click any chart point, diagram node, table cell, or sentence; drag an image region to attach a local crop — the agent replies and the thread grows on the board |

Everything autosaves in real time, detached board links keep serving after agent timeouts, multiple boards run at once, and the package has zero npm runtime dependencies — plain Node ≥ 18. Browser-side Chart.js, Mermaid, and Viz.js assets are vendored in the package and lazy-loaded offline when a board actually needs them.

Learn more

| | | |---|---| | rly help | every command at a glance | | rly git pick / rly git cherry-pick | choose commit actions and rank the order directly on a board; add --code to cherry-pick with split code review and per-hunk Apply/Skip/Hold | | rly git conflict [files…] | auto-detect unmerged conflict files, or open specific local paths, and return resolved content in result.blockEdits | | rly share <board-id> | activate/list/revoke same-Wi-Fi collaborator, reference-only reviewer, or read-only links for a running browser board | | rly view <file.md> … | open a quick read-only board that renders local markdown file(s), data files, or PDFs — library-free; great for plans, READMEs, reports, quotes | | rly show --file spec.json --display-only | present a browser board and continue immediately — no comment/note or acknowledgement required; inline relay_show uses this mode by default | | rly install --target <agent> | write relay's rules into an agent's instruction file — claude codex cursor copilot kiro windsurf cline gemini opencode droid agents; --all, --scope, --print, --list | | rly upgrade | update the CLI and refresh the skill in one step (safe around open boards; --dry-run, --cli-only, --skill-only) | | rly mcp | run relay as an MCP App server so boards render inline in the chat — stdio for local desktop hosts (Claude Desktop, Codex), or rly mcp --http (Streamable HTTP) for web/mobile/remote; rly mcp config / rly mcp install --target claude\|codex to register it | | rly agent | the full agent guide — spec format, all block types, annotations, patterns (docs/AGENT.md) | | rly schema | board spec JSON Schema | | skills/relay/SKILL.md | the bundled skill |

Development

npm test     # smoke tests with no external services (spawns real servers, fake-submits)

Changelog

0.16.1 — reliable area-comment zones

• Primary drag now draws a comment area directly on image and comparison views; Area remains as a visible one-shot lock. Image pan uses Space-drag or the middle button, while the comparison divider moves only from its handle.
• The selected rectangle remains visible while its comment is composed. Saved zones carry a comment icon plus count, reopen for add/edit/delete, and disappear automatically when their final comment is removed.

0.17.0 — file reference previews

• Local source references now resolve :line[:column] and #Lstart-Lend and open in a keyboard-accessible modal at the cited lines.
• Preview Markdown, source/config/logs, CSV/TSV, static sandboxed HTML, images, PDFs, and browser-compatible audio/video. Text is bounded to 1 MiB/20,000 lines; unsupported files retain an explicit Open in app fallback.
• Shorter agent skill and installed instructions, with clear display-only, feedback, file-preview, and existing-board workflows.

0.16.0 — native viewer chrome, area comments, and durable agent waits

• Viewer toolbars now use browser-native sticky positioning instead of a scroll-event counter-translation; open comment composers re-anchor on scroll and preserve unsaved per-target drafts.
• Hold then drag on an image to comment on an exact rectangular area. Relay saves the crop beside the browser-board record and returns its path; comparison crops also identify and capture the selected Before/After source.
• Browser boards support responseRequired:false / --display-only; inline relay_show is display-only by default. Board and waiter deadlines now default to one day (--timeout 0 removes Relay's deadline), with client-specific background/polling guidance in the agent docs.

0.11.0 — render inline inside the Claude & Codex apps (MCP App)

• rly mcp — relay as an MCP App (SEP-1865, extension io.modelcontextprotocol/ui). A stdio MCP server with no npm runtime dependencies that declares a ui://relay/board resource (text/html;profile=mcp-app) and two tools, relay_ask and relay_show, linked to it via _meta.ui.resourceUri (plus openai/outputTemplate for ChatGPT/Codex). The host renders the board inline in the conversation — Claude desktop and mobile, Codex — instead of opening a browser tab.
• Same board, postMessage transport. The inline board reuses relay's block renderer (markdown, code, diff, table, chart, mermaid, graphviz, image, html) over the MCP Apps JSON-RPC bridge: the spec arrives as the tool result, the user's submit goes back via ui/message so the agent resumes, the structured payload is also offered through ui/update-model-context, the iframe auto-sizes via ui/notifications/size-changed, and vendored Chart.js / Mermaid / Viz.js load on demand through the host's resources/read (no /vendor route, no server in the sandbox).
• One-command setup — rly mcp install --target claude|codex writes the host config; rly mcp config prints the snippet for any MCP host. The classic browser board is untouched.
• Streamable HTTP transport for web/mobile/remote — rly mcp --http [--port N --host H --token SECRET --allow-origin ORIGIN] serves the same tools over MCP's Streamable HTTP transport (single /mcp endpoint, JSON responses, CORS, Origin validation, bearer auth, Mcp-Session-Id, $PORT-aware). relay is stateless, so one instance serves everyone — deploy it once with the repo Dockerfile on any free MCP host (mcpdeploy.dev, mcphosting.io, Render/Railway/Fly, Glama) or publish to Smithery, then add the URL as a custom connector. Only the relay CLI is required — no tunnel/tailscale. stdio stays the zero-setup path for local desktop.
• Native look — the inline board color-blends onto the host's SEP-1865 style variables (surfaces, text, borders, primary button, fonts), pins color-scheme so light-dark() tokens resolve, and uses the host's own full-screen control (centering content to a readable column in fullscreen). After submit it collapses to a one-line confirmation so the iframe shrinks.
• Progressive rendering — when the host streams the tool call (ui/notifications/tool-input-partial), the board renders valid blocks as they arrive (a "Composing…" preview) instead of waiting for the whole spec.
• palette block — color palettes as swatch cards (hover reveals hex, click copies); mark one featured for a spotlight. color question type — native picker + hex field + optional presets, returns a hex string. Both work on the browser board and inline.
• Element annotations inline — comment on chart points, diagram nodes, table cells, images and text selections in the MCP board too, returned in annotations exactly like the CLI board.

0.10.0 — open files, richer code, diffs & video

• Clickable local file-links. Write a path in any markdown (~/clip.mp4, ./src/app.ts, /abs/report.pdf, a file:// URL, a backtick-wrapped path, or [label](path)) and it renders as a link that opens the file in the OS default app — guarded by a same-origin check + an allowlist of paths the board actually references. RLY_OPEN_CMD overrides the opener.
• code blocks leveled up — syntax highlighting for ~20 languages (js, ts, py, go, rust, java, c, cpp, csharp, ruby, php, swift, kotlin, sql, yaml, json, sh, css, html…), a line-number gutter, a filename/lang header, and codeFile to load source straight from a local file.
• diff block — render a unified git diff as a colored, line-numbered comparison with a live Unified ⇄ Split (side-by-side) toggle. No git required; the agent supplies the diff text (diff/diffFile, view).
• video block — YouTube/Vimeo embeds, a direct media URL, or a local video file streamed from the server with HTTP Range (seekable), never embedded in the payload.
• pdf block — render local .pdf files or PDF URLs inline. Local PDFs stream from the board server and are never embedded in the page payload.
• Durable boards / rescue — detached boards keep serving after timeout until Submit or rly stop; every autosave mirrors to localStorage; a board whose connection drops blocks further input instead of losing it, and rly rescue <id> re-serves on the same port so an open tab reconnects. Active same-Wi-Fi share links stay tied to the board and survive a same-port re-serve until revoked. Reviewer submissions are isolated, reference-only side reviews that never finish the owner's board; read-only links cannot mutate feedback.
• Still zero npm runtime dependencies, offline, and cross-platform. Vendored browser libraries are loaded only for boards that need them.

0.9.1

• The board intro renders as markdown (bold/italic/code/links/lists).

0.9.0 — interactive visual annotations

• Drag/zoom/full-screen viewer, per-element and whole-block comments, chart data-point comment badges, and inline-SVG PlantUML rendering.

0.8.1

• rly install adds OpenCode (~/.config/opencode/AGENTS.md) and Droid / Factory (~/.factory/AGENTS.md) targets.
• README documents rly install and rly upgrade.

0.8.0 — install into any agent

• rly install --target <agent> writes relay's usage rules into the right file for Claude Code, Codex, Cursor, GitHub Copilot (VS Code / Visual Studio / JetBrains), Kiro, Windsurf, Cline, Gemini, or the generic AGENTS.md — cross-platform (macOS / Linux / Windows), idempotent, with --all, --scope, and --print.
• Fixed rly skill install crashing when the target skill dir was a symlink.

0.7.0 — sturdier boards, self-update

• Markdown blocks render GFM tables; element comments moved to an Outline-style right sidebar with inline highlights on commented text.
• Seamless timeouts — a detached board that runs past its deadline keeps serving until Submit or explicit stop, so you can still submit (it lands as submitted); the page shows a calm note instead of disconnecting.
• rly upgrade — install the latest CLI and refresh the skill in one step.
• Per-question notes are multi-line textboxes.

0.6.0 — comment on anything

• Comment on any part of a custom-HTML mockup. Hover any element — a heading, a button, a card, the price — and a pin appears to leave an inline note. No setup needed; the agent writes zero annotation code. Want to scope it? Mark specific elements with data-relay-annotate="label".
• Radio questions can carry a note. Pick an option and say why, in one optional field — now shown by default (set "note": false to hide it).
• Edge-to-edge fullscreen for charts and HTML mockups, with the toolbar pinned to the top while you scroll.
• The board title and intro are commentable too.

0.5.0

• Visual answer options, image blocks, viewer redesign, adoption rules.

Migration from quest-board

relay was formerly @khanglvm/quest-board (CLI: qbd) — that package is deprecated. Storage moved from ~/.quest-board to ~/.relay (override with RLY_HOME); legacy "html" / "htmlFile" spec fields keep working.

License

MIT © Le Vu Minh Khang