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
| Agent | Instruction file | Flag in luci init |
|---|---|---|
| Claude Code | CLAUDE.md | Default |
| Cursor | .cursorrules | Default |
| Codex | AGENTS.md | --agents codex |
| Gemini CLI | GEMINI.md | --agents gemini |
| GitHub Copilot | .github/copilot-instructions.md | --agents copilot |
| Generic Agents | AGENT_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:
npx @luci-dev/cli@latest init --agents codex,gemini,copilotPass --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:
- Safety rules in
.luci/rules.md - The user's request
- Other rules in
.luci/rules.md - Global Brain (
~/.luci/brain) - Project skills
- 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:
{
"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:
claude mcp add luci-mcp -- npx -y @luci-dev/mcpTools exposed by luci-mcp
get_project_context- Read
.luci/context.md,.luci/rules.mdand project setup get_active_task- Read
.luci/local/active-task.mdwhen status is active load_project_skills- Load project skills matched to the task within a token budget
list_captures- List
.design.mdfiles 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/