The Ultimate Cursor
Masterclass. Agent-first.

Master the New Reality

Cursor changed more in the six months between October 2025 and May 2026 than in its previous two years combined. Cursor 3.x rebuilt the entire interface around agents. Composer 2 shipped as a proprietary frontier model. Bugbot moved from beta to a 70%+ resolution rate across 2M+ PRs/month. The Plugin Marketplace launched. The five primitives architecture solidified. This module is the orientation.

1.1 What Cursor actually is today

Cursor is a fork of VS Code with AI woven into every layer. Originally a smarter autocomplete in 2023, by mid-2025 it had Composer multi-file editing, by late 2025 it had Background Agents and Bugbot, and on April 2, 2026 it launched Cursor 3.0 with the Agents Window as the new default interface.

The current version as of this writing is Cursor 3.3, released May 7, 2026. The 3.x line added:

• Agents Window (3.0) — the new agent-first default surface, replacing the file-tree-first IDE view. You can still toggle back to classic IDE mode at any time.
• Tiled Layout (3.0) — split panes for running and managing multiple agents in parallel, persistent across sessions.
• Canvases (3.1) — interactive visualizations and dashboards rendered inside agent chats; durable artifacts in the side panel.
• Quick-action pills (3.2) — pin your most-used skills as one-tap actions.
• Build in Parallel (3.3) — auto-identifies independent parts of a plan and runs them simultaneously as async subagents.
• New PR review experience (3.3) — Reviews, Commits, Changes tabs all inside Cursor.

1.2 The five primitives

The most useful mental model for the entire Cursor surface today is the five primitives architecture. See the diagram above. Everything you configure in Cursor is one of these five things or a plugin that bundles them.

1.3 Pricing reality in May 2026

Cursor switched from request-based to credit-based billing in June 2025 — a change that generated real community backlash but is now the stable model. Each paid plan includes a credit pool equal to the subscription price. Tab completions and Auto mode use minimal credits. Manually selecting frontier models like Claude Opus or GPT-5 burns credits at the underlying API rates.

1.4 The 60-second decision tree

1. Never used Cursor? → Start on Hobby. Free, no credit card.
2. Code daily and want AI everywhere? → Pro ($20). Sufficient for ~90% of working developers.
3. Burning through Pro credits every month? → Pro+ ($60). 3x usage, identical features.
4. Running agents continuously, treating Cursor as infrastructure? → Ultra ($200).
5. Team of 3+ developers? → Teams ($40/seat) for centralized billing and shared rules.
6. Compliance, audit, SSO, on-prem? → Enterprise. Contact sales.

1.5 Three things to do today

1. Install Cursor from cursor.com/download. It works on macOS, Windows, Linux.
2. Open a real project (not a toy). Press Cmd+Shift+P and type "Agents Window" to see the new interface.
3. Skim Module 2 for the mental model, then return to Module 3 to set up your first .cursor/rules file.

The Cursor Mental Model

Cursor exposes nine distinct surfaces for interacting with AI. Each has a different cost, latency, and ideal use case. The biggest productivity unlock is matching the surface to the job — most developers waste credits by reaching for Agent Mode when Inline Edit would have done it in a second.

2.1 The nine surfaces

2.2 The escalation ladder

The single most useful habit: start at the cheapest surface that could possibly work, escalate only when needed.

1. Tab first. If autocomplete can finish the line, let it.
2. Cmd+K next. For "change this function to do X", select the function and press Cmd+K. Don't open Composer.
3. Cmd+L for questions. "How does the auth flow work?" goes in Chat, not Composer.
4. Cmd+I for multi-file edits. Composer is the right tool for features that touch 2-10 files.
5. Agent Mode for open-ended. "Add OAuth support" with unclear scope = Agent Mode.
6. Background Agents for parallel. Tests running, lint fixing, doc generating — all in parallel to your active work.
7. Cloud Agents for heavy. Multi-hour migrations, large refactors, tasks that would tie up your local machine.

2.3 Auto mode: the secret to credit discipline

Auto mode is Cursor's automatic model routing. It picks a cost-efficient model (typically Cursor's Auto model at roughly $0.25/M cache, $1.25/M input, $6.00/M output) for whatever task you give it. Auto mode usage on paid plans does not draw from your credit pool — it is effectively unlimited.

2.4 Composer 2 vs Auto vs frontier models

Composer 2 deserves its own module (Module 4), but here is the quick frame: it is Cursor's proprietary coding-specialized model. Cheaper than Claude Opus, faster than GPT-5, and competitive on coding-specific benchmarks. For most multi-file Composer tasks, Composer 2 (or Auto routing to it) is the right answer. Reserve frontier models for tasks that need broad reasoning beyond pure coding.

2.5 The browser and Design Mode

Cursor's built-in browser opens, navigates, and prompts against local websites. Design Mode (Cmd+Shift+D) lets you annotate and target UI elements directly. Shift+drag selects an area, Cmd+L adds the selection to chat, Option+click adds an element to the input.

This is the right tool for frontend iteration. Instead of describing "the button on the top-right of the settings page", click it. Instead of asking "why is this layout broken", point at it.

Rules: The .cursor/rules System

Rules are the highest-ROI configuration in Cursor. A team running with well-crafted rules consistently generates code that matches their stack, conventions, and constraints — without re-explaining everything in every conversation. The single biggest mistake new Cursor users make is skipping this module.

3.1 The structure

Rules live in .cursor/rules/ at the repo root. Each rule is a .mdc file (markdown with YAML frontmatter). The legacy .cursorrules file at the repo root still works for backwards compatibility, but the directory pattern is the current recommended structure.

3.2 The three rule types

1. Always-on rules. Frontmatter has alwaysApply: true. Prepended to every conversation. Use sparingly — bloated always-on rules destroy context quality.
2. Glob-scoped rules. Frontmatter has globs: "**/*.ts" or similar. Only loaded when matching files are in context. Use for stack-specific rules (React conventions, Python style, Liquid patterns).
3. Description-only rules. Frontmatter has only description. Loaded when the agent decides they are relevant based on the description. Use for procedural how-tos that should only activate when needed.

3.3 Anatomy of a rule file

3.4 Frontmatter rules

• description — keyword-rich, helps the agent decide when to load the rule. The single most important field for description-only rules.
• globs — comma-separated glob patterns. Rule loads when matching files enter context.
• alwaysApply — true or false. Use sparingly. A few critical always-on rules beat dozens of bloated ones.

3.5 Precedence: Team → Project → User

Three locations for rules, in order of priority when there's a conflict:

1. Team rules — configured in the Cursor team dashboard. Apply to every team member, every project.
2. Project rules — .cursor/rules/ in the repo. Apply to anyone working in the project.
3. User rules — Cursor Settings > Rules. Apply to you across all projects.

3.6 AGENTS.md as a project-root alternative

For smaller projects, a single AGENTS.md at the repo root works as a plain markdown alternative to the .cursor/rules/ directory. No frontmatter required. Same idea: persistent instructions that shape every AI interaction in the project. Use AGENTS.md when you want one simple file. Use .cursor/rules/ when you want composable, glob-scoped rules that grow with the project.

3.7 The 5 highest-ROI rules to write first

1. Style guide (alwaysApply) — naming conventions, formatting, file structure, banned patterns. Keep under 200 lines.
2. Stack rules (globs by language) — TypeScript rules in **/*.ts, Python rules in **/*.py, etc.
3. Architecture rules (globs by directory) — "components must not import from app/api/", "lib/ has no React imports", etc.
4. Testing rules (globs by test pattern) — required coverage, naming, the testing library to use.
5. Brand voice rules (alwaysApply for content-heavy projects) — tone, banned words, copy patterns.

Composer 2 Mastery

Composer 2 is Cursor's proprietary coding-specialized model, released March 19, 2026. It is the only first-party model in the IDE and the one Auto mode routes to most often for substantive coding work. This module is everything you need to use it well.

4.1 The hard facts

• Released: March 19, 2026
• Context window: 200,000 tokens
• Base model: Kimi K2.5 with Cursor's continued pretraining + reinforcement learning (confirmed March 20, 2026 after user discovery in API headers)
• Pricing: $0.50/M input, $2.50/M output (Standard); $1.50/M input, $7.50/M output (Fast variant, set as default)
• Benchmarks: 61.3 CursorBench, 61.7 Terminal-Bench 2.0, 73.7 SWE-bench Multilingual
• Cost vs Composer 1.5: ~86% cheaper

4.2 What Composer 2 actually is

A coding-specialized model trained in two phases: continued pretraining on coding-specific data first, then large-scale reinforcement learning on long-horizon coding tasks. The RL phase uses "compaction-in-the-loop" — the model learns to compress its own context to roughly 1,000 tokens when approaching length thresholds, which reduces compaction error by 50% versus prior methods.

Practical implication: Composer 2 can run for hundreds of sequential actions without losing the plot. This is what makes it useful for actual multi-file refactors, not just for single-file edits.

4.3 When to pick Composer 2 over Claude/GPT

4.4 The 200K context — how to actually use it

200K tokens is roughly 150,000 words of code and context. That is several large files plus your entire .cursor/rules stack plus the relevant docs. To exploit it well:

1. Start with discovery. Ask Composer to scan the relevant directory and tell you what it finds before writing code. This loads the right context.
2. Use @ mentions deliberately. @codebase for broad discovery; @filename for focused work; @folder for module-scoped context.
3. Break work into named goals. "Goal 1: create the service layer. Goal 2: add the API endpoint. Goal 3: write tests. Start with Goal 1 and show me before moving on."
4. Pause at boundaries. Approve the plan before implementation. Approve each file before the next. Long-horizon does not mean uncontrolled.

4.5 The "scan, plan, implement" template

Agent Mode Deep Dive

Composer with Agent Mode turned on is when Cursor stops being autocomplete and becomes a coworker. You describe a task in natural language, the agent makes a plan, edits files, runs commands, and shows you a diff to approve. The "let it run" workflow is where Cursor 3.x diverges hardest from VS Code + Copilot.

5.1 Agent Mode vs Composer

Composer in default mode plans, edits, and stops. Agent Mode plans, edits, runs commands, reads output, course-corrects, and continues until the task is done or you stop it. The escalation is from "edit my files" to "go execute this task."

5.2 The approval gate system

• File edit approval — by default the agent asks before touching files
• Terminal command approval — by default the agent asks before running commands
• Sandbox mode — agent runs in an isolated environment; can approve "everything in sandbox" once for the session
• YOLO / Run Everything mode — no approval gates. Use only with full Git commits and a clean branch.

5.3 The worktree pattern

Cursor 3 added the /worktree command that creates a separate Git worktree so the agent's changes happen in isolation. Pair with /best-of-n to run the same task in parallel across multiple models in their own worktrees, then compare outcomes. This is the safest way to let an agent run.

5.4 The "scan, plan, build, verify" loop

1. Scan — agent reads relevant files, asks clarifying questions if scope is ambiguous
2. Plan — agent proposes file changes and approach. You approve.
3. Build — agent implements. Approval gates trigger per-file.
4. Verify — agent runs tests, lint, build. Self-corrects on failures.

5.5 When NOT to use Agent Mode

• Single-file edits — Cmd+K is faster and cheaper
• Quick questions — Cmd+L (Chat) is faster and free
• Code you don't understand — Agent will commit code you can't review. Stay with Composer + manual approval per change.
• Tightly coupled changes — Agent's planning can fragment dependent changes. Better as a tight Composer plan.
• Brand-critical content — Agent will make creative choices. Stay tight on tone and review every diff.

Subagents and Parallel Work

Subagents are independent specialized agents with their own context window, tool access, and model selection. They run in parallel with the main agent. Cursor 3.3's "Build in Parallel" feature automatically identifies independent parts of a plan and runs them simultaneously as async subagents. This is the feature that makes Cursor materially faster than its competitors for many real workflows.

6.1 Built-in subagents

Cursor ships default subagents you can use without configuration:

• Explore — researches the codebase, returns a focused summary
• Bash — runs terminal commands in isolation
• Browser — drives the in-editor browser for verification

6.2 Custom subagent structure

Custom subagents live in .cursor/agents/ (project) or ~/.cursor/agents/ (user). Each is a markdown file with YAML frontmatter:

6.3 The three highest-ROI subagent patterns

Pattern A: Frontend / Backend split

The most immediately useful pattern. Define a shared TypeScript interface or Zod schema first. Spawn two subagents: one implements the React component against the interface, the other implements the API endpoint to match. When both finish, integration usually works on the first try.

Pattern B: Test runner in the background

Main agent writes implementation. A test-runner subagent (see file above) runs the test suite continuously in the background. Every time the main agent saves a file, the test subagent runs relevant tests and reports failures back to the main conversation. The main agent does not have to stop coding to run tests.

Pattern C: 3-agent PR review pipeline

1. Subagent A: Linting and formatting. Runs ESLint, Prettier, custom rules. Auto-fixes what it can.
2. Subagent B: Security analysis. Checks for SQL injection patterns, exposed secrets, insecure dependencies.
3. Subagent C: Test coverage. Runs tests with coverage enabled, identifies untested code paths, flags coverage regressions.

Each subagent produces a focused report. The main agent collates results into a single review summary. The full review runs in roughly the time of any single check sequentially.

6.4 Build in Parallel (Cursor 3.3)

Cursor 3.3 added a one-click "Build in Parallel" button that does the multi-subagent dispatch automatically. It scans your plan, identifies independent parts, runs them simultaneously, and keeps dependent steps in order. For plans with clear parallelism (e.g., "update 8 components to use the new design tokens"), this is the right default.

6.5 The shared-contract rule

The single biggest mistake with subagents: skipping the shared contract. If your frontend and backend subagents work without an explicit shared TypeScript interface or Zod schema, integration will break in subtle ways. Always have the main agent generate the contract first, then hand it to both subagents as a hard requirement. This pattern is non-negotiable for production work.

MCP: The Connector Layer

Model Context Protocol is the open standard for connecting AI applications to external tools through a single consistent interface. In Cursor, MCP is what turns the agent from "a text-only assistant inside the editor" into "an agent that can read Slack, query Postgres, open GitHub issues, and check Datadog logs." This is the longest module in the masterclass because MCP is also the surface where most users hit walls — context limits, security CVEs, and silent tool failures.

7.1 The architecture

MCP defines three moving pieces:

• Hosts — the application that uses MCP. Cursor is the host.
• Clients — connectors inside the host that handle individual server connections.
• Servers — the lightweight programs on the other end. They expose tools via JSON-RPC 2.0. Each server exposes a set of named tools (e.g., github.create_issue, postgres.query).

When you open Cursor, the agent scans your enabled MCP servers, loads the tools they expose, and the agent decides which tools to call as part of any given task.

7.2 The two transports

• stdio — server runs locally on your machine as a child process. Cursor communicates over stdin/stdout. The most common setup for individual developers. Does NOT work over remote SSH.
• Streamable HTTP — server runs as an independent process (locally or remotely). Cursor connects over HTTP. The right choice for team environments, remote servers, and SSH workflows.

7.3 Configuration: .cursor/mcp.json

Two locations:

• Project — .cursor/mcp.json in the repo root. Applies only to that project. Commit it (without secrets).
• Global — ~/.cursor/mcp.json. Applies everywhere. Personal API keys go here.

Same server in both files? Project config wins.

7.4 The 40-tool ceiling

Cursor has a hard practical ceiling of roughly 40 active tools across all your MCP servers combined. Exceed it and two things happen: you get a warning, and the agent silently loses access to some tools. It just cannot see them anymore.

The limit exists for a reason: each tool definition burns context tokens. Once you stack 40+ tool descriptions into the system prompt, the LLM's ability to pick the right one for any given task deteriorates noticeably.

What to do:

1. Open Cursor Settings > Tools & MCP. Each server shows its tools.
2. Toggle off tools you are not actively using. Most MCP servers expose 5-20 tools; you rarely need all of them.
3. Prefer servers exposing 5-10 well-defined tools over mega-servers trying to do 30 things.
4. Use project-level config to limit each repo's MCP stack to what that project actually needs.

7.5 The 12 essential MCP servers

7.6 Security: the CVEs that matter

The CVEs you should know about:

• CVE-2025-54136 (MCPoison) — Check Point Research found that Cursor pinned trust to the MCP server's key name in the config file, not to the actual command being run. An attacker who could modify .cursor/mcp.json (e.g., via a malicious PR) could swap the command behind a trusted-looking name. Cursor patched this; the lesson stands.
• Multiple 2025 CVEs targeting MCP server trust models. Snyk and others have published research throughout 2025-2026 on supply-chain attacks targeting MCP servers, skills marketplaces (including the ClawHub incident in January 2026), and plugin distributions.

7.7 Hardening checklist

1. Never commit secrets in .cursor/mcp.json. Use ${env:VAR_NAME} references; set env vars in your shell.
2. Check security scores on the MCP Marketplace before installing. Every listing includes a security report.
3. Review the command field every time .cursor/mcp.json changes. A malicious PR can swap a binary.
4. Limit credentials to read-only where possible. A GitHub PAT with full repo write access is a much bigger blast radius than a read-only one.
5. For team environments, prefer the HTTP transport with a centrally-managed MCP gateway. Easier audit, easier rotation.
6. Run npm audit on stdio servers periodically. They are npm packages with all the usual supply-chain risks.

7.8 Troubleshooting the silent failures

The most frustrating MCP problem: Cursor shows no error, no warning, and tools just are not showing up. Nine times out of ten, it is one of these:

• Missing mcpServers root key. Cursor silently ignores the entire file.
• Node.js or Python not on PATH. The stdio command fails to launch.
• Package version doesn't exist. @some-org/mcp-server@9.9.9 when only 0.1.0 exists.
• Forgetting -y with npx. The process hangs forever waiting for "y" at the install prompt with no interactive terminal.
• Empty or missing environment variable. ${env:GITHUB_PAT} resolves to empty and the server can't auth.

Fastest debug path: copy the command from mcp.json verbatim and run it in a terminal. Whatever error Cursor was swallowing prints to your screen.

Plugin Marketplace

Launched February 17, 2026 with Cursor 2.5, the Plugin Marketplace is the official distribution platform for plugins that bundle one or more of the five primitives (MCP servers, skills, subagents, hooks, rules) into a single installable package. Browse at cursor.com/marketplace or install via /add-plugin in the editor.

8.1 The 10 launch partners

Cursor 2.5 launched with first-party plugins from ten partners spanning design, payments, infrastructure, and analytics:

8.2 Why plugins matter

Before plugins, configuring all five primitives for a stack meant manually wiring an MCP server, writing a SKILL.md, defining subagents, configuring hooks, and writing rules. Five files, five mental models, lots of glue.

A plugin installs all five at once. The Stripe plugin, as one example, bundles a Stripe MCP server (for API access), a SKILL.md (for "build a Stripe integration" workflows), rules for Stripe API conventions, and pre-configured agent behaviors for payments work. One click. One install. Five primitives, configured.

8.3 Installing plugins

1. Browse cursor.com/marketplace or type /add-plugin in the editor
2. Review what the plugin bundles (MCP servers, skills, subagents, hooks, rules)
3. Click Install. Plugins configure themselves; no manual mcp.json editing
4. Open Cursor Settings > Plugins to view, configure, or uninstall

8.4 Team marketplaces

Teams and Enterprise plans can create custom team marketplaces with private plugins. Admins control which plugins are available to the team and how they distribute. Three distribution modes:

• Default Off — users discover the plugin in the marketplace and can opt in
• Default On — users get the plugin installed automatically but can opt out
• Required — users always have the plugin and cannot uninstall it

Use Required for plugins that enforce team standards (e.g., a custom BUGBOT.md, mandatory security rules). Use Default On for plugins most of the team needs (e.g., the company's internal Linear plugin). Use Default Off for niche stack plugins.

8.5 The Cursor Team Kit reference

Cursor publishes their internal CI, code review, and testing workflows as a public reference plugin: the Cursor Team Kit. Open it and study how Cursor itself uses Cursor — the rules, skills, and automation patterns are unusually high-quality references.

8.6 Publishing your own plugin

Submissions accepted at cursor.com/marketplace/publish. A plugin is a bundle of any combination of the five primitives plus a manifest. The marketplace runs a security review on every submission before listing.

Bugbot for Production Quality

Bugbot is Cursor's automated PR review agent — and as of May 2026, the most credible AI-powered code review tool on the market. It reviews every PR, posts inline comments on potential issues, and with Autofix enabled it spins up cloud agents in isolated VMs that push proposed fixes directly to your PR branch. Cursor's own engineering team uses it heavily; so do Sentry, Discord, Rippling, and dozens of other major shops.

9.1 The numbers that matter

• 2M+ PRs per month reviewed across all customers
• 70%+ resolution rate — issues flagged get fixed before merge
• 35%+ Autofix merge rate — Cursor's cloud agents push fixes that get merged without modification
• $1.00-$1.50 average cost per run on the new usage-based billing
• 40% time savings on code review reported by Rippling
• 80% resolution rate at default effort — high effort finds 35% more bugs at constant resolution rate

9.2 How Bugbot actually works

Bugbot is built on a fully agentic architecture (rebuilt fall 2025 from a pipeline-based design). The agent reasons over the diff dynamically, calls tools as needed, and decides where to investigate deeper rather than following a fixed sequence of passes.

1. PR opens / updates. Bugbot detects the trigger via GitHub webhook.
2. Agent reads the diff and surrounding code paths. Uses semantic search across the repo.
3. For each candidate issue, the agent traces attacker-controlled input to real sinks. Verifies whether existing controls (auth checks, schema validation, framework escaping) already block exploitation.
4. Bug classification. Trained classifiers separate genuine bugs from false positives. Issues categorized by type (logic, security, edge case, race condition) and severity.
5. Inline PR comments. Findings posted at exact line numbers with explanation, impact, and suggested fix approach.
6. (Optional) Autofix. If enabled, cloud agents spawn in their own VMs, generate fix implementations, and push them as commits to the PR branch.

9.3 The four effort levels

Bugbot's usage-based billing (rolling out by June 2026) introduces configurable effort levels:

Default for most teams. High effort for security-sensitive repos, infrastructure code, or large refactors. Custom logic is the right answer for teams with mixed-risk codebases — small documentation PRs get low effort, anything touching auth or billing gets high.

9.4 BUGBOT.md — custom rules

Drop a BUGBOT.md in your repo root to define team standards. Bugbot uses it to score PRs against your specific conventions, not just generic best practices.

9.5 Cross-model review pattern

If your team uses Claude Code (or any other AI) to write PRs, run Bugbot as the cross-model reviewer. Bugbot uses Cursor's own model stack, so when it reviews Claude-written code (or vice versa), you get genuine diversity-of-perspective benefits. As Sentry's David Cramer put it: "The hit rate from Bugbot is insane. Catching bugs early saves huge downstream cost."

The pattern is fire-and-forget once configured:

1. Describe what you want to Claude Code / Cursor Agent / any other AI
2. The AI opens the PR on GitHub
3. Within minutes, Bugbot reviews and Autofix agents push fix commits
4. By the time you open the PR for human review, the obvious stuff is handled
5. Your review starts from a cleaner baseline

9.6 The four-agent security stack

Cursor's own security team publishes their four-agent stack as a reference pattern for teams who need security-specific review (not just general bug-finding):

1. Agentic Security Review — runs on every PR; prompt-tuned to a specific threat model; can block CI on security findings without blocking on general code quality issues.
2. Vuln Hunter — divides the existing codebase into segments and searches each one for vulnerabilities. Security team triages and fixes via @Cursor in Slack.
3. Anybump — automated dependency patching with reachability analysis. Determines which CVEs are actually impactful in your code, traces relevant paths, runs tests, opens a patch PR if no breakage.
4. Invariant Sentinel — daily monitoring for drift against security and compliance properties. Catches changes that violate invariants like "no PII in logs" or "all API endpoints require auth."

Cursor publishes these as automation templates. Other security teams customize them for their own threat models.

9.7 False positives and how to manage them

Bugbot is aggressive by design — it errs on the side of flagging potential issues. Some flags will be wrong. Two practical rules:

• Resolution rate over flag count. Bugbot optimizes for bugs that get fixed, not raw flag volume. If your team is dismissing > 30% of flags, write more BUGBOT.md rules to teach it your conventions.
• LLMs confidently flag false issues sometimes. A parameterized SQL query is safe; if Bugbot calls it injection, it misread the data flow. Use the inline comment thread to push back; Bugbot updates its model from this feedback.

Hooks, Skills, and Custom Automations

Hooks and Skills are the two primitives where Cursor genuinely diverges from Claude Code, Windsurf, and Copilot. Hooks are deterministic — they run real scripts with real consequences. Skills are dynamic — they teach the agent how to do something specific, packaged for reuse. Together they enable the "agent runs the workflow you defined" pattern.

10.1 Hooks: deterministic guardrails

Hooks are scripts. They execute real code with real consequences, with no AI judgment involved. This is what makes them different from rules. A rule says "the agent should run the formatter before saving"; a hook makes sure the formatter runs whether the agent wants to or not.

Cursor supports four hook types as of May 2026:

• PreToolUse — fires before the agent calls any tool. Can modify the call or block it.
• PostToolUse — fires after a tool call completes. Can run formatters, lint, or validation.
• beforeSubmitPrompt — fires before the agent submits a prompt. Can modify the prompt, inject context, or block submission.
• stop — fires when an agent run completes or aborts. Can decide to continue the loop.

10.2 The hooks.json structure

10.3 The loop-until-done pattern

One of the most powerful Cursor patterns: a stop hook reads the conversation status, checks for a "DONE" marker in a scratchpad file, and if the work isn't done, returns a followup_message that keeps the agent grinding.

The pattern: ask the agent to work toward a goal and to mark a scratchpad file with DONE when complete. The stop hook automatically keeps the agent going up to MAX_ITERATIONS times until DONE is written. This is how teams build agents that "just keep working until the tests pass."

10.4 Skills: dynamic capability modules

Skills sit alongside Rules but serve a different purpose. Rules describe persistent project conventions. Skills encode the steps for a recurring domain task — scaffolding a new database migration, releasing a hotfix, running a release checklist, generating a feature flag.

Skills live in .cursor/skills/<skill-name>/SKILL.md. Each skill folder can include optional scripts/, references/, and assets/ directories.

10.5 Skills vs Rules vs Subagents

10.6 Custom commands

Reusable workflows triggered with / in the agent input live in .cursor/commands/. Examples: /pr, /fix-issue, /review, /update-deps, /docs. Each is a markdown file with a prompt template. Cursor 3.2 added quick-action pills that let you pin commonly-used commands as one-tap buttons.

Production Engineering and Cost Discipline

Cursor works fine for solo developers out of the box. Cursor at team scale needs deliberate engineering. This module is what you set up before rolling Cursor out to 5+ developers, or before your monthly bill scares your finance team.

11.1 Teams plan setup checklist

1. Move billing to a single corporate card (the $40/seat consolidates personal Pro subs)
2. Configure shared .cursor/rules via the team dashboard
3. Set up the team marketplace for shared internal plugins
4. Enable Privacy Mode org-wide (guarantees code is not stored or trained on)
5. Configure role-based access control for who can install plugins, view usage, manage billing
6. Set spend limits per user to prevent runaway monthly bills

11.2 Cost discipline patterns

11.3 Watching the dashboard

cursor.com/dashboard shows real-time credit consumption broken down by user and by feature. Admins should review weekly:

• Top spenders — are they shipping enough work to justify the cost?
• Feature breakdown — Bugbot, Cloud Agents, frontier model usage
• Spike detection — sudden jumps usually indicate someone left an agent running
• Per-product surface usage — clients vs Cloud Agents vs automations vs Bugbot vs Security Review

11.4 Enterprise admin controls

Cursor's Enterprise plan added several admin controls in 2026 worth knowing about:

• Granular model allow/blocklists — block entire providers or specific model configurations
• Soft spend limits with usage alerts — alerts instead of hard cutoffs that block users
• Detailed usage filtering — by user, by product surface (clients, Cloud Agents, automations, Bugbot, Security Review)
• Self-hosted pool — run Cloud Agents on your own infrastructure (Google Cloud Run, custom pools)
• SAML/OIDC SSO + audit logs — standard enterprise security stack

11.5 The Cursor SDK for CI/CD

The Cursor SDK gives programmatic access to every model in Cursor for use outside the IDE. Teams ship custom agents from CI/CD pipelines:

• PR summary agents — generate change summaries on every PR open
• CI failure root-cause agents — when a build breaks, an agent reads the failure logs and posts a probable cause
• Stale-PR fixers — agents that rebase old PRs and resolve conflicts
• Custom agent platforms — internal apps that let non-engineers query data through agents without writing code

11.6 Git discipline with agents

Hard rules that prevent agent-caused disasters:

1. Agents always work on branches. Never run an agent against main with auto-commit enabled.
2. Use /worktree for risky tasks. Isolated worktrees mean an agent error doesn't pollute your local main.
3. Commit before agent runs. A clean working tree means easy revert via git reset --hard.
4. Review every diff. Even with Bugbot. Even with high-confidence agents. Even when you trust the model.
5. No agent-only commits to main. All agent work goes through PR review at minimum.

Comparison, Limits, and the Honest Take

Cursor is the best AI-native IDE in May 2026. It is not the only good tool. It is not the right primary for every developer. This module is the honest decision matrix vs Claude Code, Windsurf, Copilot, Antigravity, and Aider — and the failure modes that no Cursor marketing page will tell you about.

12.1 The five major AI coding tools in May 2026

12.2 Cursor vs Claude Code — the head-to-head

This is the comparison most developers actually care about. The honest answer: many production teams use both.

The practical answer: most working developers in May 2026 use Cursor for daily IDE work (Tab, Composer, multi-file edits) and Claude Code for weekly deep tasks (large refactors, security audits, multi-agent parallel work). The tools complement more than compete.

12.3 Cursor's hard limits

• 40-tool MCP ceiling. Hard cap that silently breaks once exceeded. Active management required.
• Credit-based pricing is unpredictable for some workflows. If you live in frontier models, expect to budget for overages or graduate to Ultra.
• Mobile and remote SSH workflows are second-class. Most heavy features (Cloud Agents, Bugbot) assume a desktop GUI session.
• Composer 2 trails GPT-5 on the hardest coding benchmarks. 61.7 vs 75.1 on Terminal-Bench 2.0. For the toughest 10% of tasks, frontier models still win.
• Background Agents work best with well-structured, modern codebases. A legacy monolith with inconsistent conventions needs more manual steering.
• JetBrains support exists but is younger than the VS Code experience. ACP launched March 2026; expect feature drift between editors.
• The pace of change is its own cost. The Cursor you learned six months ago is not the Cursor of today. Plan to re-read the changelog quarterly.

12.4 When NOT to make Cursor your primary

• You live in JetBrains and your team standardizes on it (Copilot or Windsurf may fit better)
• You need to embed AI coding into a customer-facing product (Cursor SDK works, but Claude API may be cheaper)
• You spend 80%+ of your time on autonomous long-running tasks (Claude Code's terminal-native model is leaner)
• You need on-prem or air-gapped (Enterprise self-hosted works, but Aider or local models may be simpler)
• You are a hobbyist who codes < 4 hours/week (the free tier is fine, the paid tier rarely pays back)

12.5 The multi-tool workflow

Most professional teams in May 2026 run 2-3 tools in combination:

1. Cursor as the daily IDE. Tab, Composer, multi-file work, MCP integrations, Bugbot.
2. Claude Code for deep tasks. Multi-hour refactors, security audits, anything where you want Opus 4.7's reasoning depth and 1M context.
3. GitHub Copilot or Windsurf as the team baseline. If standardization across a large org is the constraint, the Copilot/Windsurf-as-baseline + Cursor-or-Claude-for-individual-power-users pattern is common.