Cursor Integration

.cursorrules, the MCP bridge, and intent logging from inside the IDE.

Why This Exists

Cursor is, for many developers, the agent that sits closest to the code — inline in the editor, completing lines, running multi-file edits, carrying the rhythm of a coding session. That proximity means Cursor generates a lot of small edits, often in rapid succession, and often in files that other agents are also working on.

The Cursor integration exists because the thing that makes Cursor useful — speed and inline presence — is exactly what makes it dangerous in a multi-agent context. A Cursor session firing off six file edits per minute is the most likely source of collisions on any mixed team, not because Cursor is worse than Claude, but because its unit of work is smaller and its pace is faster.

Aura's Cursor integration is designed to keep Cursor fast while making every one of those small edits visible to the Sentinel.

How It Works

The integration has three pieces, analogous to the Claude Code setup but routed through different mechanisms:

1. .cursorrules — a repo-level instruction file Cursor reads on every session. This is where the Aura protocol lives for Cursor, parallel to CLAUDE.md.
2. The MCP bridge — Cursor's MCP client connects to the same aura-vcs server the Claude integration uses. No duplicate infrastructure.
3. The commit hook — the same git pre-commit hook enforces intent logging and zone respect regardless of which agent produced the edit.

Because Cursor is primarily an editor, most of the workflow is inline rather than conversational. The agent does not "plan, announce, execute" in the formal way a Claude session does. It edits; Aura observes; Sentinel reacts.

MCP bridge setup

Cursor reads MCP server configuration from its settings. The canonical block:

{
  "mcp": {
    "servers": {
      "aura-vcs": {
        "command": "aura",
        "args": ["mcp", "serve"]
      }
    }
  }
}

Once configured, the Cursor agent can call the same aura_* tools as Claude. Cursor's default behavior is to call MCP tools silently, without surfacing them in the chat. You can make them visible via a Cursor preference, and for mixed-agent teams this is recommended.

Verify the bridge:

aura mcp doctor --client cursor

Output:

aura-vcs MCP server: ok
cursor mcp session: connected (PID 72109)
tools exposed: 29

The .cursorrules template

Cursor's .cursorrules is to Cursor what CLAUDE.md is to Claude. Aura ships a canonical template. A working version:

# AURA PROTOCOL — CURSOR RULES

This repo is managed by Aura, a semantic VCS with multi-agent coordination.
Other AI agents (Claude, Gemini, Copilot) may be editing the same code.

## BEFORE EDITING
- Call `aura_status` once per session to see team sync state.
- Call `aura_snapshot` on each file BEFORE editing it.
  - If response shows `TEAM ZONE WARNING` → proceed cautiously, message
    the zone owner.
  - If response shows `TEAM ZONE BLOCKED` → STOP. Do not edit. Ask the
    user or send `aura_sentinel_send` to the zone owner.
- Call `aura_live_sync_pull` if the status shows pending pulls.

## WHILE EDITING
- Prefer node-level intent: before committing, call `aura_log_intent`
  with a one-sentence description of the change.
- If you receive a `SENTINEL COLLISION` event, pause and coordinate via
  `aura_sentinel_send` before proceeding.
- On any `📨 SENTINEL` banner, call `aura_sentinel_inbox` and respond.

## COMMITS
- Always call `aura_log_intent` before `git commit`.
- The pre-commit hook will refuse commits without logged intent.
- Keep the intent terse; it is matched against the AST diff.

## NEVER
- Edit a file whose `aura_snapshot` response was BLOCKED.
- Ignore `📨 SENTINEL` or `💬 TEAM` banners.
- Reduce commits to "wip" or "fix" — intent must describe the change.

Cursor's agent reads this file on session start and on every chat boundary. The rules work as long as you don't let the file drift too far from the template — aura doctor will warn if it does.

Intent logging from inline edits

Cursor's inline edit mode (Cmd-K) does not naturally produce commits — it produces file edits that the human reviews and saves. Aura bridges this with a small helper: after an inline edit session, the Cursor agent is instructed to log intent for the aggregate change.

[Cursor Cmd-K] User: "fix the timing attack in authenticate"
[Cursor agent] → edits src/auth.py (6-line diff)
[Cursor agent] → aura_log_intent "Use hmac.compare_digest in authenticate() to prevent timing attack"
[User] Cmd-S
[Git commit from user] → hook verifies intent matches diff → ok

The human is still the one running git commit in most Cursor workflows. The intent call happens automatically as part of the agent's post-edit housekeeping, which is encoded in .cursorrules.

Examples

A Cursor session in a repo with an active Claude zone

User (in Cursor): refactor AuthService to use dependency injection

[Cursor] → aura_snapshot file=src/auth/service.py
         ← 🚨 TEAM ZONE BLOCKED
            owner: claude/7f3a2b
            reason: "OAuth 2.1 migration, 1h"

[Cursor] → aura_sentinel_send to=claude-7f3a2b
            body="User wants DI refactor on AuthService.
                  Can we coordinate? I can wait or split scope."

[Claude (in its own session)] ← inbox banner
[Claude] → aura_sentinel_send to=cursor session
            body="Do DI after I land OAuth (~20 min). Will ping."

[Cursor] → presents user with: "Blocked by Claude's OAuth work.
            Estimated 20 minutes. Wait, or work on something else?"

The user got routed through the Sentinel without ever leaving the editor.

Cursor catching its own collision

Sometimes Cursor is the second agent to arrive:

User (in Cursor): update the retry logic to 3 attempts

[Cursor] → aura_snapshot file=src/net/retry.py
         ← ⚠️ SENTINEL COLLISION
            peer: gemini-0091 ("reduce retry delay for latency")
            recommended: aura_sentinel_send

[Cursor agent, following .cursorrules]
         → aura_memory_read query="retry policy"
         ← k_01HW...: "base delay must be ≥200ms or rate limiter trips"

[Cursor] → aura_sentinel_send to=gemini-0091
            body="Heads up — knowledge entry k_01HW says retry base
                  delay must stay ≥200ms. Also changing retry count
                  to 3. Coordinate?"

Cursor queried the knowledge base on the way to handling the collision, which is exactly the behavior the .cursorrules protocol encodes.

Silencing tool output in the editor UI

By default Cursor shows every MCP tool call in the chat. For heavy Aura usage this becomes noise. The recommended team setting:

{
  "cursor.mcp.toolDisplay": "banner-only",
  "cursor.mcp.alwaysShowSentinelEvents": true
}

Routine calls (aura_snapshot, aura_status) are suppressed; Sentinel events (collisions, zone warnings, inbox messages) are always visible.

Configuration

The Aura-side config for Cursor lives alongside the Claude config:

[cursor]
cursorrules_path = ".cursorrules"
enforce_presence = true
cursorrules_version = "v0.12.6"

[cursor.mcp]
transport = "stdio"
tool_timeout = "20s"       # shorter than Claude — Cursor is snappier
silence_routine_tools = true

[cursor.intent]
auto_log_on_edit = true    # ask the agent to log intent after edits
aggregate_window = "2m"    # combine rapid edits into one intent log

aggregate_window is the Cursor-specific knob worth knowing about. Cursor tends to produce many small edits; without aggregation, the intent log fills with low-value entries. The aggregation window combines edits inside a two-minute burst into a single intent.

Feature Matrix

| Feature | Cursor Support | Notes | | --- | --- | --- | | MCP client | Native | Same server as Claude | | Instruction file | .cursorrules | Canonical template in Aura repo | | Pre-commit hook | Yes | Works regardless of agent | | Inline edits | Yes | Aggregated into intent via config | | Sentinel inbox | Full | Visible via banner-only mode | | Zone claims | Full | Honored on pre-edit | | Knowledge base | Full | Read/write | | Handover | Partial | No long-context window, handover is less relevant | | Plan tools | Partial | Cursor is lighter-touch; plans are usually Claude's job |

The partial entries are not limitations of Aura — they reflect Cursor's product shape. Cursor is an editor with an agent, not a standalone agent, and some of Aura's ceremonial tooling doesn't map onto that mode of work.

Recommended Roles

On mixed Claude-plus-Cursor teams, a useful convention is to let each agent play to its strengths:

• Claude — planning, multi-file refactors, documentation, code review.
• Cursor — inline edits, bug fixes, test authoring, UI work.
• Sentinel — ensures the two don't step on each other.

When both agents follow their respective protocol files, the coordination happens almost automatically. The humans on the team see Sentinel events in the dashboard and intervene only on escalations.

Cursor is fast. The Sentinel is how the team keeps up.

Working With Cursor's Composer

Cursor's Composer (the multi-file edit mode) is where most of the real Aura wiring shines. Composer produces a plan, applies it across files, and then asks for user confirmation. The Aura protocol layers in:

• A pre-plan pass where .cursorrules instructs the agent to call aura_memory_read and aura_live_impacts before drafting the plan.
• A pre-edit pass where the agent calls aura_snapshot on each file the plan will touch. Zone conflicts surface here; the agent pauses the plan and coordinates before applying it.
• A post-apply pass where the agent calls aura_log_intent with the plan summary and any Sentinel events raised during the apply.

The result is that Cursor's native Composer workflow becomes Sentinel-aware without changing Cursor itself. The agent is simply following its rules.

Intent Aggregation Details

Cursor's edit pattern is bursty. A session might produce twenty edits in five minutes and then go quiet. Without aggregation, the intent log becomes unreadable. The aggregation window collapses bursts into a single intent call.

The mechanics:

1. On the first edit after a quiet period, Cursor opens an intent buffer.
2. Subsequent edits within aggregate_window append to the buffer.
3. When the window closes — either by inactivity or by explicit commit — the agent synthesizes a single intent string from the buffer and calls aura_log_intent.

The synthesis is lightweight — the agent summarizes its own buffer, which is within its context. Teams with strict intent hygiene can disable aggregation and require per-commit intent, but the resulting log is noisier.

Switching Sessions Mid-Feature

Most multi-agent teams end up running Claude and Cursor on the same feature, handing off in one direction or the other. The inbox is how the handoff works; .cursorrules tells Cursor to read the inbox on session start; CLAUDE.md tells Claude to send handoffs when its work is done. The handoff includes refs to commits and nodes, so Cursor picks up with full context.

What the human sees: a Claude conversation that ends with "I have handed off the UI work to Cursor — check your inbox there," and a Cursor session that opens with "I see a handoff from Claude, here is the plan for wave 2." The human has done nothing special. The protocol files did the work.

Cursor is only as coordinated as the fleet around it. Sentinel is what makes a fleet out of disparate tools.

See Also

• Claude Code Integration — the sibling integration.
• The Sentinel Overview — coordination substrate.
• Agent Collision Detection — where Cursor's pace matters most.
• Multi-Agent Workflows — Claude-plus-Cursor patterns.