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 serveluci 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.
1 note on /
P1-A1“Shorten to ‘Start free’.”
- element
- Start your free trial
- component
- <Hero>
- source
- Hero.tsx:42
- Click Annotate, then click any element, or select text and press Add feedback.
- Write the note with an intent (
fix,change,questionorapprove) and a priority. - 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.
- 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.
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.
Layout plan
2 changes- 1Gap 24px → 32px<FeatureGrid> · FeatureGrid.tsx:12
- 2Insert button “Book a demo”<Hero> · after “Start your free trial”
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.
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.
Saved to .luci/design/
- component.start-free.design.mdnew
- project.system.color.design.md
- project.system.typography.design.md
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.
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.
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.
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.
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.
luci-mcp
stdio- get_feedback_prompt
- 1 page, 2 items
- watch_feedback
- waiting for notes
- list_captures
- 3 files
- get_design_checks
- 1 differs
- 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.