How Cursor Works

Cursor is a fork of VS Code that keeps your source local and pushes heavy compute to the cloud, using small specialized models for the fast parts so a frontier model is spent only on the decision.

Architecture

• Fork, not an extension: an extension is sandboxed and cannot change how edits apply, run a hidden workspace, or control indexing deeply.
• Shape: thin local client (holds files, orchestrates, shows diffs) + cloud backend (embeddings, vector index, apply model, agent VMs).
• One idea: editor keeps code and decides what to send; cloud does the heavy compute. Cost: merging upstream VS Code forever.

Indexing and retrieval

• Cursor does not store your source. It stores embeddings (numeric vectors) + metadata (path, start/end line), then reads the actual code from your disk when needed.
• Query flow: embed query -> nearest-neighbor search -> returns paths + line ranges -> read content from local disk -> build context. Retrieved thing is a location, not code.
• Merkle tree keeps the index fresh: hash each file, hash folders from children up to a root. One edit changes only that file’s hash and its ancestors, so diffing roots finds changes in O(depth), not O(repo). 50k-file repo ~ 3.2 MB of names + SHA-256.
• Chunks cached by content, so unchanged chunks are never re-embedded. User hook: @codebase.
• Undisclosed: vector DB vendor (secondary sources say Turbopuffer) and embedding model.

Tab: next-edit model

• Custom sparse model (since March 2024) trained to predict edits, not just next tokens.
• Predicts the edit near your cursor AND a “jump” to where you go next (possibly another file). Inputs: current file + cursor, recent edit history, open tabs.
• Fusion (latest) numbers: context 5,500 -> 13,000 tokens; median latency 475 ms -> 260 ms; 25% more difficult edits/line; 10x longer change stretches; >1B edited chars/day; ~100x request growth since launch.
• Use 13,000 for context (a circulating 272,000 figure is wrong). Parameter count/architecture undisclosed.

Two models per edit

• Slow decider + fast typer.
• Reasoning: Composer (in-house MoE, RL-trained) or a frontier model you pick. ~4x faster than similar models, most turns under 30s; frontier still wins on raw quality.
• Fast Apply: fine-tuned Llama-3-70B, ~1000 tok/s (~3500 chars/s), ~13x faster than vanilla Llama-3-70B, ~9x faster than their GPT-4 apply.
• Reasoning model emits a terse edit sketch (unchanged parts elided as // ... existing code ...); Fast Apply expands it to a full-file diff.
• Speculative edits: the existing file is the “draft.” Most output matches the source, so verify long runs greedily and only diverge at the real edit. Old file is ~95% of the answer.
• Nothing writes until you approve: whole change set staged as one diff with per-file accept/reject.

Context controls

• Rules: version-controlled .mdc files in .cursor/rules (Markdown + frontmatter). Modes: always-on, glob-scoped, agent-requested, or manual. Legacy .cursorrules still works but superseded.
• @-mentions (per-turn): @Files, @Folders, @Terminals, @Chats, @Git (@Commit, @Branch), @Browser, plus retrieval @codebase, @docs, @web. @-mention when you know the files; else let the agent search.
• Context ring shows window fullness by category; older conversation auto-compressed to a summary.

Tools and MCP

• Built-in tools: read/edit files, semantic search, grep (literal), list dir, run terminal, web. Semantic = by meaning, grep = exact string.
• MCP (Model Context Protocol) adds external tools via ~/.cursor/mcp.json (global) or .cursor/mcp.json (project), over stdio or remote SSE.
• Up to ~40 MCP tools exposed, auto-selected per turn. CLI respects the same mcp.json and .cursor/rules.

Background agent vs shadow workspace

• Confused constantly; they solve different problems.

• Worktrees let N agents edit one repo without collision (and compare models on the same task).
• Shadow reads errors back over independent IPC; proposed path to full runnability is a FUSE folder proxy with in-memory writes.

Model-to-job map

• Composer training: async RL on PyTorch + Ray, MXFP8 MoE kernels, thousands of GPUs. “Cursor Router” picks a model per request (cost / balance / intelligence).