# 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: ```json { "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: ```bash aura mcp doctor --client cursor ``` Output: ```text 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: ```markdown # 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. ```text [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 ```text 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: ```text 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: ```json { "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: ```toml [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](/docs/lessons/claude-code-integration) — the sibling integration. - [The Sentinel Overview](/docs/lessons/sentinel-overview) — coordination substrate. - [Agent Collision Detection](/docs/lessons/agent-collision-detection) — where Cursor's pace matters most. - [Multi-Agent Workflows](/docs/lessons/multi-agent-workflows) — Claude-plus-Cursor patterns.