Agents and MCP

How Luci configures Claude Code, Cursor, Codex, Gemini CLI, GitHub Copilot and the local luci-mcp server.

Luci keeps one shared project memory in .luci/ and writes a managed block into each agent's instruction file. Every agent reads the same rules, decisions, design context and active task.

Supported agents and files

AgentInstruction fileFlag in luci init
Claude CodeCLAUDE.mdDefault
Cursor.cursorrulesDefault
CodexAGENTS.md--agents codex
Gemini CLIGEMINI.md--agents gemini
GitHub Copilot.github/copilot-instructions.md--agents copilot
Generic AgentsAGENT_INSTRUCTIONS.md--agents generic

By default, luci init writes files for Claude Code, Cursor and any agent whose file already exists in the project. Pass --agents to add others:

bash
npx @luci-dev/cli@latest init --agents codex,gemini,copilot

Pass --agents all to write instruction files for every supported agent.

Managed blocks and precedence

Luci wraps its lines between <!-- LUCI — <AGENT> CONFIGURATION --> and <!-- END LUCI --> markers. Anything you write outside those markers stays untouched when luci update runs.

Rule precedence in every agent file follows this order:

  1. Safety rules in .luci/rules.md
  2. The user's request
  3. Other rules in .luci/rules.md
  4. Global Brain (~/.luci/brain)
  5. Project skills
  6. Tool and framework defaults

When two rules contradict each other, Luci flags the conflict with both file paths and line numbers.

Connecting the local MCP server

@luci-dev/mcp provides the luci-mcp binary. It runs locally over standard stdio with no network calls.

Add luci-mcp to your MCP client configuration:

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

If @luci-dev/mcp is installed globally, set "command": "luci-mcp" with no arguments. For Claude Code, you can also register it from the terminal:

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

Tools exposed by luci-mcp

get_project_context
Read .luci/context.md, .luci/rules.md and project setup
get_active_task
Read .luci/local/active-task.md when status is active
load_project_skills
Load project skills matched to the task within a token budget
list_captures
List .design.md files saved in .luci/design/
get_capture
Read a saved capture file with tokens, states and image slots
get_feedback_prompt
Read pending user feedback notes grouped by page
watch_feedback
Wait for new feedback notes created in the browser
get_design_checks
Read recent design check comparisons
compare_captures
Compare two saved component captures part by part
get_layout_tree
Read the computed flex and grid layout tree of a capture
propose_capture_rule
Propose a rule from a component capture into .luci/memory/proposed/