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:

bash
npx @luci-dev/cli@latest init

Luci detects your framework, package manager and stylesheets, then creates a .luci/ folder and writes agent instruction files:

  • .luci/rules.md holds safety rules, stack rules and project rules.
  • .luci/context.md holds the project goal, commands and folder structure.
  • .luci/playbook.md describes steps for features, bug fixes, refactors and UI work.
  • .luci/design/ holds captured DESIGN.md files 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:

bash
npx @luci-dev/cli@latest serve

If @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_prompt or watch_feedback.
  • Check your setup any time with luci doctor.