Direct your agent from the page.

Run luci serve and the Luci toolbar appears on your own app while you develop. It has three modes, Feedback, Layout and Capture, and a design check. This guide goes through each one.

Start the toolbar

Run the local bridge while your app is running:

npx @luci-dev/cli@latest serve

luci serve binds to 127.0.0.1 on port 4545 by default (use --port <n> to pick another). Open your app and click Luci's button in the bottom corner to open the toolbar.

The toolbar loads through a small localhost-only loader in your app's root HTML or layout. luci init offers to add it, or run luci toolbar (and luci toolbar remove to take it out).

Feedback

Point at what should change, and Luci writes the prompt. Each note is pinned to the element, its component and its source line.

localhost:3000

1 note on /

P1-A1

“Shorten to ‘Start free’.”

element
Start your free trial
component
<Hero>
source
Hero.tsx:42
get_feedback_prompt · 1 page, 1 item
  1. Click Annotate, then click any element, or select text and press Add feedback.
  2. Write the note with an intent (fix, change, question or approve) and a priority.
  3. In React, Vue 3 and Svelte projects, Luci adds the component and the exact source file. In production builds, notes keep the selector and the text around them.
  4. Press Copy prompt, or let your agent read it over MCP. Notes from every page you visited go out together, and the agent reports back on every ID.
Each note keeps a stable ID such as P1-A1. Only you can mark a note done: agents can read notes over MCP, but cannot mark them done or delete them.

Layout

Try structural changes on the running page before asking your agent to edit code. Luci turns them into a layout plan.

localhost:3000

Layout plan

2 changes
  1. 1Gap 24px → 32px<FeatureGrid> · FeatureGrid.tsx:12
  2. 2Insert button “Book a demo”<Hero> · after “Start your free trial”
Sent to your agent with the notes

1. Change existing elements

Select an element to resize it with its 8 handles, drag its grip to reorder siblings, or edit width, height, margin, padding, flex and grid settings snapped to your spacing scale.

2. Insert parts

Insert a component found on the page, a saved capture from .luci/design/, or a layout block such as a section, heading, button, image slot, card grid or form field.

3. Sketch a new page

Open New page, set a route and build rows and columns on a canvas, then copy the page prompt or save it as a feedback note.

Layout mode previews changes without altering your app's DOM. When you copy the prompt, the page goes back to what your code renders until your agent applies the edits.

Capture

The same four tools as the Luci Extension (Component, Text, Colour and Spacing), on your own app. Everything you save goes straight into .luci/design/, where your agent can read it.

localhost:3000

Saved to .luci/design/

  • component.start-free.design.mdnew
  • project.system.color.design.md
  • project.system.typography.design.md
Your agent finds them with list_captures.

Next to your captures, luci capture baseline writes the project's own type, colour and spacing system from its stylesheets, so the agent reuses what you already have.

Design check

Check what the agent built against the design, part by part.

localhost:3000

start-free.design.md

1 differs
Matches:height
44px
Matches:radius
9999px
Matches:background
--accent-primary
Differs:padding
0 16px

Padding is 16px on each side; the design says 20px.

Send as a feedback note

Manual check

Pick a saved .design.md file (or paste one) and click the built component. Luci captures it the same way and compares parts, styles, state changes, motion and accessibility. Each difference is one sentence and becomes a feedback note with one click.

Automatic re-check

Turn on auto-check to run the comparison again whenever edits reload the page. Resolved differences drop off; the rest stay listed.

localhost:3000

Your agent reported back

auto-check on
  • P1-A1 Label shortened to “Start free”.
  • Layout 1 Gap is 32px.
  • Layout 2 “Book a demo” inserted.

Auto-check: no differences left.

Only you mark a note done.

Your agent and MCP

Luci runs a local MCP server, luci-mcp, over standard stdio. Your agent reads notes, captures and design checks straight from your project.

localhost:3000

luci-mcp

stdio
get_feedback_prompt
1 page, 2 items
watch_feedback
waiting for notes
list_captures
3 files
get_design_checks
1 differs
Runs locally, with no network calls.
get_feedback_prompt
Pending notes from every page, as one prompt.
watch_feedback
Waits while you review and delivers only the new notes.
list_captures
The .design.md files saved in .luci/design/, read before writing UI.
get_design_checks
Recent design check results, read after edits.

Setup for Claude Code, Cursor, Codex, Gemini CLI and GitHub Copilot is in the Agents guide.

Supported frameworks

Finding the component and exact source file works in React, Vue and Svelte projects. Project detection and luci toolbar also support Next.js, Remix, Preact, Nuxt, Angular and plain front-end apps.

New to Luci? Start with the quickstart: initialize .luci/, connect your agent and open the toolbar.