Quickstart
Initialize .luci/ in your project, start the local dev toolbar and give AI coding agents measured design context.
Luci runs on your machine and requires Node 18 or later. You can run it straight through npx without installing anything globally.
1. Initialize your project
Run init in your project root:
npx @luci-dev/cli@latest initLuci detects your framework, package manager and stylesheets, then creates a .luci/ folder and writes agent instruction files:
.luci/rules.mdholds safety rules, stack rules and project rules..luci/context.mdholds the project goal, commands and folder structure..luci/playbook.mddescribes steps for features, bug fixes, refactors and UI work..luci/design/holds capturedDESIGN.mdfiles and the design baseline built from your stylesheets..luci/local/holds your active task (active-task.md) and a read-only summary of your Global Brain (global-brain.md). This folder stays ignored by git.
During interactive setup, init offers to add the dev toolbar loader to your app's root HTML or layout file (luci toolbar). The loader only runs on localhost in development.
2. Start the dev toolbar
Run the local bridge server while your app is running:
npx @luci-dev/cli@latest serveIf @luci-dev/cli is installed globally (npm install -g @luci-dev/cli), run luci serve.
luci serve binds to 127.0.0.1 on port 4545 by default (use --port <n> to pick another port). Open your app in the browser and click Luci's button in the bottom corner to open the toolbar.
3. Connect MCP to your agent
Your coding agent reads .luci/ through the instruction files on disk and can also query captures, design checks and live feedback over MCP (luci-mcp from @luci-dev/mcp).
See the Agents guide for instruction files and MCP configuration across Claude Code, Cursor, Codex, Gemini CLI and GitHub Copilot.
4. Pick something or add feedback
- Switch to Capture to measure a component, text style, colour or spacing value and save it to
.luci/design/. - Switch to Feedback to pin a note to an element, then copy the prompt or let your agent read it through
get_feedback_promptorwatch_feedback. - Check your setup any time with
luci doctor.