Cursor Setup

One-command setup

From the repo root:

npx enagrams init

The CLI writes everything Cursor needs:

.cursor/mcp.json — MCP server config pointing to npx -y enagrams --mcp
.cursor/hooks.json — event-to-script wiring
.cursor/hooks/enagrams-hooks.mjs — the hook script itself

Restart Cursor (or re-open the project) so it picks up the new configuration.

Verify

Open the MCP panel in Cursor (command palette → Cursor: Open MCP Settings). You should see enagrams listed as a connected server with 26 tools. In a terminal:

enagrams status

With Cursor open on this project you should see at least one active agent session.

What the Hooks Do

Event	Action
`sessionStart`	Registers a new `agent_sessions` row and injects a team briefing (active agents, recent decisions, conventions that apply) into the agent’s context.
`preToolUse` (on writes)	Calls `file_lock` for the file. If another agent owns it — or a `must`-tier convention matches — the write is denied with an explanatory message.
`postToolUse` (on writes)	Re-extracts the symbol graph for the changed file.
`beforeSubmitPrompt`	Compact team-state refresh.
`sessionEnd`	Releases reservations and closes the session.

Manual Configuration

If you’d rather set it up by hand, .cursor/mcp.json:

{
  "mcpServers": {
    "enagrams": {
      "command": "npx",
      "args": ["-y", "enagrams", "--mcp"],
      "env": {
        "ENAGRAMS_API_KEY": "your-api-key",
        "ENAGRAMS_WORKSPACE": "your-workspace-slug"
      }
    }
  }
}

For the hook scripts run npx enagrams init in a scratch directory and copy the generated files — keeping them in sync with the CLI is easier than maintaining them manually.

Troubleshooting

MCP server not appearing in Cursor — fully quit and relaunch Cursor. Restart-Cursor-window is not enough. “Permission denied” on every write — must-tier convention matched. Run convention_list with the file path to see which one. Hooks not firing — check .cursor/hooks.json exists and references .cursor/hooks/enagrams-hooks.mjs. Re-run npx enagrams init to regenerate.

Getting Started

Setup Guides

Concepts

One-command setup

Verify

What the Hooks Do

Manual Configuration

Troubleshooting

​One-command setup

​Verify

​What the Hooks Do

​Manual Configuration

​Troubleshooting

One-command setup

Verify

What the Hooks Do

Manual Configuration

Troubleshooting