Ross

Ross

A point-and-draw layer over your own running web app. Open the overlay, select / draw / measure / capture real components — each grounded to its true source file:line — compose one intent, and Send copies a ready-to-paste instruction for your coding agent. You paste it into Claude Code, review, and run it. Selection identifies; the agent edits. See [SPEC.md](./SPEC.md) for the original design.

> Status: working dogfood. Grounding, the in-app overlay (compose gestures → > clipboard), and design.md memory work end-to-end on Next 16 + React 19 + > Turbopack. Delivery is clipboard-paste (see below); the MCP server is now > optional (design-memory tools only).

How it works

overlay in your dev app                          you, in Claude Code
  ⌥R → select / draw / measure / capture   ─►   ⌘V the pasted instruction
  gestures compose into one intent              review / edit / ↵
  Send → clipboard                              agent edits the grounded file

  build-time loader injects data-src      ·     daemon (:5179) serves overlay.js
  (grounding: file:line + component)            design.md ← agent reconciles taste

1. A build-time loader injects data-src="file:line:col" + data-component

onto host elements (Next 16 + React 19 + Turbopack; covers Server Components). It's self-contained — Babel is bundled in, so your app needs no extra deps.

1. The overlay reads those attributes as you point/draw, and builds a single

composite intent (subjects + an optional measured vector + optional marks).

1. Send composes the intent into one plain-language instruction (with the real

file:lines) and copies it to your clipboard.

1. You paste it into Claude Code, review/edit, and press Enter. The agent edits

the grounded file. You are the gate — nothing is auto-applied.

1. For design-relevant changes, the agent can reconcile the decision into an

evolving design.md (via the optional MCP tools ross_get_design_context + ross_update_design) so accumulated taste informs future edits.

The daemon (:5179) mainly serves overlay.js. The MCP server is optional: it exposes the design.md tools (and legacy intent-queue tools that the clipboard flow no longer uses).

The overlay (⌥R)

One window, top-right. Modes (each keyboard-bound), and gestures compose onto a single intent until you Send:

• ⌖ Select (S) — hover and click component(s); clicks accumulate. Selected

elements get a persistent outline.

• ✎ Draw (D) — sketch pen / arrow / box (P/A/B) about the

selection. Each mark resolves to the grounded elements it covers, so the intent carries annotation.targets + placement (container + insertion order + alignment). An arrow predicts a move; a box over empty space predicts create.

• ⤡ Measure (M) — drag a vector to capture a precise pixel delta (deltas),

predicts move.

• ⬚ Capture (C) — marquee a region to multi-select every component inside it

in one drag (not an image).

The window shows the running summary, the predicted intent (↑↓ to change it), and Send (↵). Esc clears the composition; ⟲ clears just the drawn marks. Send copies the instruction to your clipboard (navigator.clipboard); if the browser blocks it, a selectable fallback box appears.

Run the demo

# from the repo root: starts the daemon (:5179) AND the demo app (:3000). Ctrl-C stops both.
npm start

Then open the app, press ⌥R, gesture, Send, and ⌘V into your Claude Code session. Prefer two terminals? node ross/src/cli.js in one, cd spike-grounding && npm run dev in another.

Use it in your own Next.js app

Published to npm as getross (the CLI it installs is ross). Requires Next.js 16+ / React 19 / Turbopack (App Router, .tsx) and Node.js 18+.

npx getross init /path/to/your-next-app   # wire loader + overlay + design.md + .mcp.json
npx getross dev  /path/to/your-next-app   # daemon (serves overlay.js) + your `npm run dev`

Or install globally and use the ross command directly:

npm i -g getross
ross init /path/to/your-next-app
ross dev  /path/to/your-next-app

init builds the self-contained loader (no Babel needed in your app), adds it to next.config turbopack rules, injects the dev-only overlay ` into your root layout, seeds design.md, and registers the (optional) Ross MCP server in the app's .mcp.json. It's idempotent and prints manual steps for anything it can't patch confidently. Clear .next` if Turbopack reports a stale module after wiring.

Then in the browser: ⌥R → gesture → Send → ⌘V into Claude Code → review → Enter. (No need to restart Claude Code for the paste flow — the clipboard is the hand-off. Restart it only if you want the design.md MCP tools.)

Layout

ross/                     the tool (published to npm as `getross`)
  loader/                 build-time data-src injector (Turbopack loader)
  overlay/overlay.js      vanilla in-app overlay (framework-agnostic)
  src/daemon.js           localhost server that serves overlay.js (and legacy endpoints)
  src/mcp-server.js       stdio MCP server (design.md tools; legacy intent tools)
  src/store.js            intent/design store
  test/                   loader / overlay / draw / capture / mcp / design tests
spike-grounding/          demo Next.js app wired to use Ross

Tests

npm test                  # from the repo root: builds loader + overlay, runs the full suite

Covers the loader, ross init, the overlay logic against a real DOM (happy-dom: select/measure compose, draw grounding + placement, capture multi-select), the MCP server, and design.md reconciliation.

Known constraints

• Next.js + Turbopack + App Router, .tsx. The grounding loader is a Turbopack

rule for *.tsx, and the overlay is injected into app/layout.tsx. Other stacks (Webpack, Pages Router, .jsx, non-Next) need a different loader/injection.

• Port 5179 is hardcoded in the injected overlay `` — it must be free

and the daemon must be running, or the overlay never loads.

• Clear .next after changing loader config/deps — Turbopack caches the module

graph and will otherwise report stale "cannot find module" errors.

• The in-browser UI is verified with happy-dom (the headless Chromium QA tool can't

run in the build sandbox); drive it manually in a real browser.

Contributing

Issues and PRs welcome — see [CONTRIBUTING.md](./CONTRIBUTING.md). Changes are tracked in [CHANGELOG.md](./CHANGELOG.md).

License

[MIT](./LICENSE) © Renzo Viale

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Renzoviale
• Source: Renzoviale/ross
• License: MIT

Install and usage instructions live in the source repository linked above.