Cursor Harness

Cursor (by Anysphere) is an agent-centric IDE: a harness that wraps a chosen model with a system prompt, a fixed tool set, and a managed context system built on a persistent embeddings index. Since Cursor 2.0 the product is organized "around agents rather than files," and the same harness runs across IDE, CLI, web, cloud VMs, and the SDK.

Each turn the agent orchestrates three things — instructions (system prompt + rules), tools (semantic search, grep, read, edit, shell, web, MCP), and the model — and loops: read prompt + injected context → call tools → observe → iterate, taking local checkpoints (separate from git) before significant edits. The harness re-tunes instructions/tools per frontier model; its in-house Composer model (Cursor 2.0 and Composer, currently Composer 2.5) is RL-trained on Cursor's own tool set and is ~4× faster than similarly capable models. Source: Cursor 2.0 blog

Modes and models

Four modes (cycle with Shift+Tab), each starting a fresh context window: Agent (full edit), Ask (read-only Q&A), Plan (research → reviewable Markdown plan in .cursor/plans/ → build), and Debug (runtime-evidence root-causing). Model selection runs two pools: Auto (Cursor picks/cost-balances from the Auto+Composer pool) and manual frontier models (GPT‑5.x, Claude 4.x, Gemini 3.x, Grok) at API rates. Source: Cursor Agent docs; Source: Plan Mode

Context system (the differentiator)

Cursor maintains a persistent embeddings index, which is its biggest architectural divergence from terminal agents:

• Merkle-tree sync: a hash per file, derived directory/root hashes; editing a file changes only its leaf + parent chain, so client↔server re-indexing walks only diverging branches.
• Files are split into syntactic chunks → embeddings (custom model) → a vector DB; a simhash of the Merkle root lets a teammate bootstrap from a similar existing index.
• Security: stores hashes + embeddings, not plaintext; content proofs require the client to prove it holds a file before results are returned. Respects .gitignore/.cursorignore.
• Hybrid search: an Instant Grep engine + semantic vectors, with a search subagent running parallel searches and returning only summaries to protect the main window. Source: Cursor secure indexing; Source: Cursor search docs

Explicit context comes via @-mentions (@Files, @Code, @Docs, @Web, @Git, @Past Chats) and Memories (per-project facts a background model proposes and the user approves).

Rules, hooks, MCP

• Rules in .cursor/rules/*.mdc with a four-type activation matrix: Always Apply (alwaysApply: true), Auto Attached (by globs), Agent Requested (by description), Manual (@rule). Plus AGENTS.md (nested, more-specific wins) and CLAUDE.md compat; precedence Team > Project > User rules. This is the architecture behind Kevin's always-on rule lattice. Source: Cursor Rules docs
• Hooks: a hooks.json maps ~20 lifecycle events (beforeSubmitPrompt, pre/postToolUse, beforeShellExecution, before/afterMCPExecution, subagentStart/Stop, preCompact, stop, …) to child processes that exchange JSON on stdin/stdout and can block actions; project/home/enterprise configs merge. Source: Cursor Hooks docs
• MCP: mcp.json with stdio, SSE, and Streamable HTTP (OAuth) transports; auto-discovered tools. See MCP Server Architecture. Source: Cursor MCP docs

Parallelism, cloud, review, SDK

Cursor 2.0 runs multiple agents in parallel isolated via git worktrees or remote machines, with best-of-N (several models attempt one problem) and a native browser tool for self-verification; /orchestrate recursively spawns SDK agents for fan-out. Cloud/Background Agents run in isolated VMs defined by .cursor/environment.json (install step, optional Dockerfile, tmux terminals, disk snapshots), kicked off from web/Slack/GitHub/Linear, producing merge-ready PRs. Automations are scheduled/event-triggered cloud agents (cron). Bugbot reviews PR diffs and can autofix via a Cloud Agent. The @cursor/sdk exposes the same harness (indexing, search, MCP, skills, hooks, subagents) programmatically. Source: Cursor Cloud Agents; Source: Cursor SDK

Contrast

Where Claude Code and Codex do agentic, on-demand search (grep/read) with no standing index, Cursor's managed embeddings index + content proofs + simhash reuse is the standout choice, alongside a harness-tuned in-house model and a managed cloud-VM fleet + Bugbot. All are instances of Harness Engineering; Cursor is Kevin's primary surface in his Agent Operating System.

Architecture Position

---

Timeline

• 2026-07-01 | Architecture category refresh added this page to the Agent harness architecture family, linked it to Architecture System Map, and kept it standalone because it owns this boundary: Cursor IDE harness: editor context, rules, MCPs, and project interaction. Source: User request, 2026-07-01

• 2026-06-02 | Page created from official cursor.com docs (Agent, Rules, Hooks, MCP, Cloud Agents, SDK) and the Cursor 2.0 blog. Captured the agent loop + four modes, Composer co-design, the Merkle/embeddings/content-proof index + hybrid search subagent, the four-type .mdc rules matrix, hooks.json, MCP transports, parallel agents/best-of-N, Cloud Agents (environment.json/snapshots), Automations, Bugbot, and the SDK. Source: Cursor 2.0 blog