Cursor

Cursor gets native hooks on session start, prompts, tool calls (shell, file writes, deletes) and stop, plus the Comity MCP server and an always-on rule. The same project hooks run in the Cursor IDE agent, the Cursor CLI and Cursor cloud agents.

Set up

cd your-repo
comity init --tools cursor
git add .cursor/hooks.json .cursor/mcp.json .cursor/rules/comity.mdc
git commit -m "Set up Comity for Cursor"

Then:

1. Open the repo in Cursor and trust the workspace. Cursor loads project hooks only in trusted workspaces; Customize → Hooks lists them.
2. Run comity login once on each machine (see Authentication for MCP).
3. In Cursor Settings → MCP, enable the comity server.

What init writes

.cursor/hooks.json

Shown for one event; the others differ only in event name, matcher and timeout. Your own hooks in the file are kept.

{
  "version": 1,
  "hooks": {
    "preToolUse": [
      {
        "command": "comity hook --tool cursor --event PreToolUse",
        "timeout": 5,
        "matcher": "Shell|Write|Edit|Delete"
      }
    ]
  }
}

The command is a plain comity hook call because Cursor runs hook commands through PowerShell on Windows and a POSIX shell elsewhere, and both parse it. On a machine without the CLI, the command fails with a non-zero exit code other than 2. Cursor treats that as a failed hook, logs it in the Hooks output channel and lets the action continue.

.cursor/mcp.json

{
  "mcpServers": {
    "comity": { "command": "node", "args": ["-e", "<launcher>", "mcp"] }
  }
}

Cursor starts comity mcp, a local stdio bridge to the Comity server, through a short node -e launcher that finds comity on any OS. The file is identical for every teammate, whatever OS ran comity init. Node must be on PATH; the CLI needs it anyway. comity doctor warns about comity mcp or cmd /c comity mcp entries written by an earlier init, because each works on one OS only. Rerun comity init --tools cursor to replace them.

.cursor/rules/comity.mdc

An alwaysApply: true rule with Comity's coordination instructions (declare intent, check scope, answer conflicts).

Authentication for MCP

No token is written to the repo, and comity login is enough: comity mcp and comity hook both use the login stored on the machine. COMITY_TOKEN and COMITY_SERVER, if set, override it.

An older entry with "url" and "Bearer ${env:COMITY_TOKEN}" still works if COMITY_TOKEN is exported before Cursor starts. comity doctor warns when it isn't, and rerunning comity init --tools cursor replaces it with the bridge.

What your agent sees

• Session start: the briefing as additional_context.
• Before a shell command, file write or delete: a block denies the call (permission: "deny") and shows Comity's reason to you and the agent. Otherwise the hook prints nothing and Cursor proceeds as usual.
• After a tool call: new conflicts, messages and notices as additional_context.
• Prompts and pre-tool warnings: Cursor's beforeSubmitPrompt and preToolUse can't add context. These warnings are queued and delivered after the next tool call.

Claude Code hooks in Cursor

Cursor also runs the Claude Code hooks in .claude/settings.json (see Cursor's third-party hooks docs). If the repo has both, the invocation from .claude/settings.json steps aside whenever a Cursor hooks.json (repo or ~/.cursor/) calls comity hook, so each event is evaluated once. Repos set up only with comity init --tools claude_code keep working in Cursor through that import.

Cloud agents

Cursor cloud agents run .cursor/hooks.json from the repo, except sessionStart and sessionEnd. The hooks only do anything if the cloud environment has the comity CLI installed and COMITY_TOKEN set. Sessions report the cloud surface (CURSOR_CODE_REMOTE=true).

Verify

comity doctor

Expect cursor hooks all 6 events installed (Cursor runs project hooks in trusted workspaces) and cursor mcp configured in …/.cursor/mcp.json. In Cursor, open the Hooks output channel and start an agent chat; the hooks should run without errors.

Limits

• beforeSubmitPrompt can't add context, so prompt-time briefings arrive after the next tool call.
• The matcher uses the tool names Cursor documents for preToolUse (Shell, Write, Delete, plus Edit). Reads, searches and MCP calls aren't evaluated.