rails-markup

Rails engine · toolbar · MCP server · CLI

Version 1.5.0 · Early stage · Used by our team across our projects

Point-and-click annotation for AI agents.

Mark up your Rails views right in the browser. Connect your AI agent over MCP to read the feedback, make changes in your code, and reply or update its status.

$ gem install rails-markup

Inside the app

Real captures from the Rails demo. Expand a step to see how feedback moves from the page to your dashboard.

01Toolbar · Point to what needs changing
Rails Markup toolbar expanded on a Kuickr page, with an element selected and its feedback form open.
Select an element and leave a comment. The floating toolbar stays on your app. View full size ↗
02List · See what needs attention
Compact feedback dashboard with counted status filters, search, Options and three feedback rows.
Review feedback across pages, filter by status, and open a row to act on it. View full size ↗
03Board · Follow feedback through its status
Feedback board with Pending, Acknowledged, Resolved and Dismissed columns, and contextual Move controls.
Use the board to follow pending and acknowledged feedback. Move controls expand when needed. View full size ↗
04Feedback · Review the image and take action
Feedback modal containing the original comment, attached screenshot, Acknowledged status, Resolve and Dismiss actions, and a reply disclosure.
List and board open the same modal. Review the image, reply, acknowledge or resolve, then return to your view. View full size ↗
05Image markup · Draw what you mean
A screenshot marked in Rails Markup: a red box surrounds a low-contrast label, a red arrow points to it, and a yellow highlight marks the heading.
Box a detail, point with an arrow, or highlight what needs attention. The drawing stays with your feedback. View full size ↗

Draw what you mean

An 18-second captioned demo: attach a screenshot, add a box, arrow and highlight, then review the saved feedback in the dashboard.

A captioned sequence of real app captures. Download MP4

See the workflow

A 38-second captioned walkthrough using a Kuickr design experiment in a local Rails app: leave feedback, attach an image, then review it in the list or board.

The loop

Feedback flows from your browser to your agent and back — no copy-pasting screenshots or describing where things are.

1

Annotate in the browser

Click an element and say what should change. Optionally capture, upload or paste an image, then add arrows & highlights. Review feedback in a shared modal from the compact list or board.

2

Agent reads over MCP

Your AI agent lists pending annotations through the MCP server and gets the exact element, page, and your note.

3

Fix & resolve

The agent edits the code and resolves the annotation with a summary — which syncs back to the pin and the dashboard.

What's in the box

One Ruby gem: a mounted engine with its own dashboard, a self-contained browser toolbar, an MCP server, and a CLI.

Toolbar

Floating annotation UI

Zero-dependency overlay — no Stimulus, no importmap. Configurable FAB (show/hide, size, 4 corners) that works in any Rails app.

Dashboard

Mounted engine interface

A compact list and drag-and-drop board share the same feedback modal. Search, filter, export, reply, and update status without losing your place.

MCP

Agent-native server

Read feedback, acknowledge or resolve it, add replies, and dismiss it over stdio MCP. Configure it in Claude Code, Codex, or another stdio MCP client. The standard HTTP proxy uses polling; watch is available only with the in-memory server.

CLI

Thor-based commands

rails-markup ships server, init, mcp, watch, pending, resolve, and more.

Sync

Server-backed state

Client UUIDs, an outbox with retries, and reconciliation keep the browser, the database, and your agent converged.

Portable

SQLite · MySQL · Postgres

Adapter-aware migrations and a configurable table name. Protect the dashboard through your host app's controller. The external MCP API uses a separate bearer token in production; development skips token authentication by default.

Install in three commands

Add the gem, run the generator, migrate. The generator mounts the engine, injects the toolbar, and writes an initializer.

# Gemfile
gem "rails-markup", require: "rails_markup"

# then
bundle install
bin/rails generate rails_markup:install
bin/rails db:migrate

Configure the toolbar

OptionValuesWhat it does
fab_visibletrue / falseShow or hide the entire floating dock. Pins and synchronization stay active; restore it from dashboard Options.
toolbar_enabledtrue / falseMaster switch for the whole toolbar system.
toolbar_positionbl / br / tl / trWhich corner the FAB sits in.
toolbar_sizeslim / compact / default32 / 36 / 40px button.
toolbar_accentindigo / amber / blue / emerald / roseAccent color for the UI.
base_controller_class"AdminController"Parent controller that enforces auth.