Mental Models & Architecture
Understand how Cursor IDE thinks — tools, models, rules/skills/hooks, and context indexing.
title: "Mental Models & Architecture" description: "Understand how Cursor IDE thinks — tools, models, rules/skills/hooks, and context indexing." section: "Full Guide" readTime: "10 min"
Mental Models & Architecture
Before diving into Cursor, understand how it thinks. This mental model unlocks everything else.
The Tool Selection Matrix
| Tool | Shortcut | Scope | When to Use |
|---|---|---|---|
| Tab | Tab | Inline, multi-line | Boilerplate, repetitive patterns, next-edit jumps |
| Inline Edit | Cmd/Ctrl+K | Selection | Refactor a function, rename, small fixes |
| Agent | Cmd/Ctrl+I or Cmd/Ctrl+L | Multi-file | Large refactors, migrations, architectural changes |
| Plan Mode | Shift+Tab | Planning | Complex features, unclear requirements |
| Debug Mode | Mode picker | Any | Elusive bugs, race conditions, runtime issues |
| Worktrees / Parallel Agents | /worktree, /best-of-n | Git worktrees | Explore multiple approaches simultaneously |
| Cloud Agents | Agent input dropdown, cursor.com/agents | Remote VM | Long tasks that shouldn't tie up your machine |
| Browser | Agent tool | Web UI | Testing UI, screenshots, console and network checks |
Thumb rule: Tab for speed, Inline Edit for precision, Agent for correctness.
Cursor merged the old Chat and Composer panels into a single Agent panel in version 0.46. "Composer" is now the name of Cursor's own coding model. The Agent panel has several modes:
- Agent — autonomous: file edits, search, terminal commands
- Ask — read-only Q&A and exploration
- Plan — research, clarifying questions, and an editable plan before building
- Debug — hypothesize, instrument with logs, reproduce, fix
Switch with the mode picker, or rotate with Shift+Tab.
How Cursor Actually Works
Cursor is an orchestration layer, not a single LLM:
- Three parts drive the agent: instructions (system prompt and rules), tools, and the model you pick
- Models are stateless between requests, so conversation history and rules are sent each time
- Context management matters: garbage in, garbage out
- Connects to external systems via MCP (Model Context Protocol)
- Checkpoints are taken before significant changes so you can restore files
Model Selection Guide
Cursor's model list changes often. Check cursor.com/docs/models for what's current. Models fall into two pools: Cursor models (Composer, Grok) and Other models (Anthropic, OpenAI, Google, and more, billed at API rates).
| Phase | Example choice | Why |
|---|---|---|
| Planning / analysis | A frontier reasoning model (e.g., Claude Opus 5.5, GPT-5.5) | Deeper reasoning |
| Multi-file execution | Composer 2.5 | Cursor's own model, tuned for agentic coding |
| Large-context review | Gemini 3.1 Pro | Large context window |
| Not sure | Auto | Routes each request for cost, balance, or intelligence |
Workflow: Plan with a reasoning model in Plan Mode, then build with a faster model such as Composer. See the model comparison for trade-offs.
Guidance System: Rules, Skills, Hooks
| Type | Location | Purpose | Always Active? |
|---|---|---|---|
| Rules | .cursor/rules/*.mdc, AGENTS.md | Standing project constraints and context | Per rule type (always, by glob, by description, manual) |
| Skills | .cursor/skills/<name>/SKILL.md | Reusable workflows | Agent applies when relevant, or /skill-name |
| Hooks | .cursor/hooks.json | Scripts at agent lifecycle events | Yes, when configured |
Decision framework:
- Must this always hold, or explain project context? → Rule (e.g., "never use
anytypes", "why we chose Fastify") - Is this a reusable workflow? → Skill (e.g., TDD test-fix loop)
- Must something be enforced or automated by a script? → Hook (e.g., format after every edit)
Codebase Search and Indexing
Cursor builds a local index for fast search, and the agent also uses semantic search to find relevant code. Cursor says it does not upload file paths or code to build the search index, but when the agent opens a file, that content can be included in the model request.
- Cursor ignores everything in
.gitignoreplus a built-in list (lock files,.env*,node_modules/, binaries, media) - Add a
.cursorignoreto block Cursor (Agent, Tab, Inline Edit, @ mentions) from specific files. It is not a hard guarantee: terminal and MCP tools can't enforce it - Narrower scope means more focused context, so open the subfolder you actually work in for very large repos
MCP (Model Context Protocol)
Connect Cursor to external live systems via .cursor/mcp.json (project) or ~/.cursor/mcp.json (global):
- Custom servers — GitHub, databases, Slack, docs, and more
- Cursor asks for approval before running MCP tools by default
- Install official plugins from the Cursor Marketplace under Customize
Context7 vs documentation guessing: Context7 is a third-party MCP server (@upstash/context7-mcp) that serves version-specific library docs. Add it to mcp.json yourself. It helps when a library updates often or you need a specific version.