Luci for Claude Code.

Claude Code reads CLAUDE.md at the start of every session. Luci adds a managed block there that points Claude at your project's rules, design baseline and active task, and the local luci-mcp server lets Claude read your captures and the feedback you pin on the running page.

What Claude Code gets

Instead of guessing from screenshots and long descriptions, Claude Code works from files in your project and a local MCP server:

  • Project memory. Rules, decisions, the playbook and the active task in .luci/, linked from CLAUDE.md.
  • Your design system. luci capture baseline writes your type, colours and spacing from your stylesheets, so Claude Code reuses your tokens instead of inventing new ones.
  • Measured references. Components, text styles, colours and spacing captured with the dev toolbar or the extension, saved as .design.md files.
  • Pinned feedback. Notes you click onto the running page. In React, Vue and Svelte projects each one carries its component and source line.
  • Design checks. A part-by-part comparison of what Claude Code built against the capture.

1. Initialize Luci

Run this in your project root. It needs Node 18 or later:

npx @luci-dev/cli@latest init

Luci detects your framework and stylesheets, creates .luci/ and writes its block into CLAUDE.md. Claude Code is one of the default agents, so no flag is needed.

Luci only edits the lines between its <!-- LUCI and <!-- END LUCI --> markers. Anything you write elsewhere in CLAUDE.md stays as it is when luci update runs.

2. Connect luci-mcp

luci-mcp (from @luci-dev/mcp) runs on your machine over standard stdio, with no network calls. Register the server once from your project folder:

Terminal
claude mcp add luci-mcp -- npx -y @luci-dev/mcp

To share the server with your team, commit it in .mcp.json at the project root instead:

.mcp.json
{
  "mcpServers": {
    "luci": {
      "command": "npx",
      "args": ["-y", "@luci-dev/mcp"]
    }
  }
}

Run /mcp inside Claude Code to check that luci-mcp is connected.

The tools Claude Code uses most:

get_project_context
Rules, context and project setup, read at the start of a task.
list_captures · get_capture
The saved .design.md references, read before writing UI.
get_feedback_prompt · watch_feedback
Your pending notes from every page, or new ones as you save them.
get_design_checks
Recent design check results, read after edits.

Every tool is listed in the Agents and MCP docs.

3. Show it what to change

Start the dev toolbar while your app is running, then point at the page instead of describing it:

npx @luci-dev/cli@latest serve

Then ask Claude Code, for example:

  • “Read the pending Luci feedback and fix every item, then report each ID.”
  • “Watch for new Luci feedback while I review the app.”
  • “Build the pricing card from the saved Luci capture, using our tokens.”
  • “Run the design checks again and fix what still differs.”

How notes, layout plans and checks work is in the Devtool guide.

Check the setup

luci doctor checks the installation and project setup and says what to fix. After upgrading Luci, luci update refreshes CLAUDE.md and the other agent files.

Using more than one agent? They all read the same .luci/ memory. Set up Cursor, Codex, Gemini CLI or GitHub Copilot the same way.