Cursor Advanced Composer

Overview

Use Composer for bounded multi-file proposals when a human owner can inspect the plan, diff, tests, and rollback before applying changes.

Prerequisites

• A defined task, affected-file boundary, repository rules, and a clean working tree or recoverable branch.
• Required test commands and a reviewer for changes that alter architecture, security, or data flow.

Instructions

1. Ask Composer for a plan and affected-file list before applying any edits.
2. Constrain it to the approved scope and provide acceptance checks/non-goals.
3. Inspect each diff, run focused validation, and split or reject changes that exceed scope.
4. Commit only reviewed, test-backed changes; retain a revert path.

Output

• A reviewed multi-file change proposal with affected files, validation results, and rollback reference.

Error Handling

Examples

Ask Composer to add a feature only in src/feature/ and its existing tests, requiring a plan first. Apply no files until the plan and diff are reviewed; run the focused suite and revert the commit if acceptance fails.

Advanced patterns for Cursor Composer including agent orchestration, complex multi-file refactoring, architecture migrations, and quality-control workflows.

Agent Mode Deep Dive

In Agent mode, Composer autonomously chains tool calls: reading files, searching the codebase, running terminal commands, and writing code. It operates in a loop until the task is complete or it hits the 25-tool-call limit.

Agent Tool Capabilities

Controlling Agent Behavior

Give the agent constraints in your prompt:

Migrate all React class components in src/components/ to functional
compo…

Cursor AI Chat

Overview

Use Chat to reason about a bounded question or planned change while preserving human ownership of decisions, edits, review, and validation.

Prerequisites

• Approved privacy/model settings and a workspace with sensitive paths excluded.
• A clear question, relevant non-sensitive files, and the project's test/review expectations.

Instructions

1. Start a topic-scoped chat and attach only the files needed for the question.
2. Ask for assumptions, tradeoffs, and a testable proposal rather than accepting generated code blindly.
3. Verify suggestions against source, tests, security controls, and a human code review.
4. Start a new conversation when context becomes stale or the topic changes.

Output

• A bounded explanation or proposal with assumptions, affected files, and validation steps.

Error Handling

Examples

Ask Chat to compare SSE and WebSockets for the stated service, attaching only the API contract and architecture note. Require it to list assumptions and a rollout/rollback test plan; then review the proposal before authoring any change.

Master the Cursor AI Chat panel and inline edit for code assistance, debugging, and exploration.

Core Chat Interfaces

Chat Panel (Cmd+L / Ctrl+L)

The side-panel chat for conversational code assistance:

┌─────────────────────────────────┐
│  Chat                     [M]   │  ← Model selector
│─────────────────────────────────│
│  Context Pills:                 │
│  [main.ts] [utils/] [@Web]      │  ← Active context shown as pills
│─────────────────────────────────│
│  User: Explain the auth flow    │
│  in @src/auth/middleware.ts     │
│                                 │
│  AI: The middleware checks...   │
│─────────────────────────────────│
│  [Type message...]    [Send]    │
└─────────────────────────────────┘

Key actions:

• Select code in editor, then Cmd+L to add selection as context
• Cmd+Shift+L adds selection to existing chat without clearing
• Click model name in top-right to switch models mid-conversation

Inline Edit (Cmd+K / Ctrl+K)

Surgical edits within the editor. Select code (or place cursor), press Cmd+K, type instruction:

Selected: function calcul…

Cursor API Key Management

Overview

Manage any Cursor BYOK/provider credentials as individual, least-privilege secrets with approved routing, ownership, rotation, spending limits, and exposure response.

Prerequisites

• An approved provider/model route, named key owner, secrets-manager integration, and budget policy.
• Confirmation that BYOK is permitted for the intended data classification and tenant configuration.

Instructions

1. Issue one scoped key per owner or approved service through the provider/secrets manager.
2. Configure it through the approved UI/injection path; never commit it, paste it into rules, or share it between users.
3. Set provider spending/rate controls, review usage, and rotate on schedule or suspected exposure.
4. Revoke first, then investigate, when a key is lost, leaked, or no longer required.

Output

• An attributable, scoped credential with rotation, budget, and revocation evidence.

Examples

Create a personal provider key in the approved secret manager, configure it only in the local secure setting, verify a low-cost non-sensitive request, and confirm usage attribution. If it appears in logs, chat, or git, revoke it immediately and replace it; do not attempt to redact history before revocation.

Configure Bring Your Own Key (BYOK) for AI model providers in Cursor. BYOK lets you use your own API keys to bypass Cursor's monthly quota, pay per token directly, and access models not included in Cursor's subscription.

Supported Providers

Configuration Steps

OpenAI

1. Go to platform.openai.com/api-keys
2. Create a new API key (project-scoped recommended)
3. In Cursor: Cursor Settings > Models > check Use own API key
4. Paste key in the OpenAI API Key field
5. Select model from dropdown (e.g., gpt-4o)

Anthropic

1. Go to console.anthropic.com/settings/keys
2. Create …

Cursor Codebase Indexing

Overview

Configure codebase indexing so relevant source and documentation are available while sensitive, generated, oversized, and unrelated files remain excluded from AI context.

Prerequisites

• Repository ownership, expected source/documentation paths, and reviewed .cursorignore/indexing exclusions.
• A non-sensitive verification fixture and a change-review path for configuration updates.

Instructions

1. Define the intended workspace scope and add exclusions before the first indexing pass.
2. Verify required files can be found and excluded paths cannot be attached or discovered.
3. Reindex only after a reviewed configuration/workspace change and capture a redacted result.
4. Monitor index size/performance and narrow scope rather than weakening data controls.

Output

• A verified index scope with explicit included/excluded paths and an owner for maintenance.

Examples

Index src/ and docs/ for a service while excluding .env*, build output, vendor directories, and customer exports. Verify a sanitized source file is available and an excluded placeholder is not before allowing AI work on the repository.

Set up and optimize Cursor's codebase indexing system. Indexing creates embeddings of your code, enabling @Codebase semantic search and improving AI context awareness across Chat, Composer, and Agent mode.

How Indexing Works

Your Code Files
      │
      ▼
  Syntax Chunking ─── splits files into meaningful code blocks
      │
      ▼
  Embedding Generation ─── converts chunks to vector representations
      │
      ▼
  Vector Storage (Turbopuffer) ─── cloud-hosted nearest-neighbor search
      │
      ▼
  @Codebase Query ─── your question → embedding → similarity search → relevant chunks

Key Architecture Details

• Merkle tree for change detection: only modified files are re-indexed (every 10 minutes)
• No plaintext storage: code is not stored server-side; only embeddings and obfuscated metadata
• Privacy Mode compatible: with Privacy Mode on, embeddings are computed without retaining source code
• Indexing runs in the background; small projects complete in seconds, large projects (50K+ files) may take hours initially

Initial Setup

1. Open your project in Cursor
2. Indexing starts automatically on first open
3. Check status: look at the bottom status bar for "Indexing..." indicator
4. View indexed files: Cursor Settings > Features > Codebase Indexing > View included files

Verify Indexing Status

The status bar shows:

• …

Cursor Common Errors

Overview

Diagnose Cursor startup, authentication, extension, indexing, and workspace errors with reversible, user-scoped steps before resetting local state.

Prerequisites

• A reproduction, Cursor version, affected operating system, and an approved backup location for user settings.
• Authorization to inspect local logs; redact project paths, prompts, and credentials from support evidence.

Instructions

1. Reproduce the issue with extensions disabled or in a disposable profile when possible.
2. Capture the smallest relevant status/log evidence and try the least-destructive documented remedy.
3. Back up settings before clearing caches or resetting state, then validate recovery with a non-sensitive workspace.
4. Escalate persistent issues with a redacted reproduction instead of sharing workspace data.

Output

• A classified issue, reversible remediation, and redacted verification result.

Error Handling

Examples

When Cursor will not start, launch once with extensions disabled, record the version and outcome, then re-enable extensions individually in a disposable profile. Clear only cache folders after backing up settings; do not delete the full profile to diagnose a single extension.

Diagnostic and resolution guide for the most frequent Cursor IDE issues. Organized by error category with specific symptoms, causes, and fixes.

Authentication Errors

"Sign-in failed" / OAuth Loop

Symptoms: Browser opens for auth, redirects back, Cursor still shows "Sign In".

Fix:

1. Clear browser cookies for cursor.com and auth.cursor.com
2. Try incognito/private window for the OAuth flow
3. Check if browser is blocking popups from cursor.com
4. Try a different auth method (GitHub vs Google vs email)

"License not found" / "No active subscription"

Symptoms: Signed in but AI features are disabled.

Fix:

1. Verify subscription at cursor.com/settings
2. Confirm the email address matches your Cursor account
3. Sign out (Cmd+Shift+P > Sign Out) then sign back in
4. If on a team plan, ask admin to verify your seat is assig…

Cursor Compliance Audit

Overview

Assess a Cursor deployment against approved privacy, identity, source-code, and audit controls. This is an evidence-backed configuration review, not legal certification.

Prerequisites

• A named system owner, applicable controls, and authority to inspect tenant settings.
• Read-only admin evidence, current access roster, and redaction rules for audit artifacts.
• Legal/compliance review for regulated data, customer commitments, or PHI/PCI scope.

Instructions

1. Define the tenant, repositories, data classes, and control period in scope.
2. Compare privacy, retention, identity, access review, and .cursorignore settings to the approved baseline.
3. Record findings with evidence, owner, severity, due date, and verification method.
4. Escalate suspected sensitive-code exposure before broad configuration changes.

Compliance and security auditing framework for Cursor IDE usage. Covers SOC 2, GDPR, and HIPAA assessment with audit checklists, evidence collection, and remediation guidance.

Cursor Security Posture

Certifications and Attestations

Data Processing Architecture

Developer Machine
    │
    ├─► Cursor Client ──► Cursor API (US/EU) ──► Model Provider
    │   (local)           (routing + auth)        (OpenAI/Anthropic)
    │                           │
    │                           └─► Zero retention agreement
    │
    ├─► Codebase Index ──► Embedding API ──► Turbopuffer (vectors)
    │                      (no plaintext stored)
    │
    └─► Local Settings (API keys, preferences)
        (never transmitted)

Audit Checklist: SOC 2

CC6.1 — Logical Access Controls

[ ] SSO (SAML/OIDC) configured and enforced
[ ] MFA enabled at Identity Provider level
[ ] RBAC roles assigned: Owner, Admin, Member
[ ] Inactive users deprovisioned (SCIM or manual)
[ ] Access review completed (quarterly)

Evidence:
  - SSO configuration screenshot from admin dashboard
  - IdP MFA policy documentation
  - User list export from Cursor admin
  - SCIM sync logs (if applic…

Cursor Composer Workflows

Overview

Structure Composer work around explicit planning, small reviewed diffs, test evidence, and rollback rather than unattended multi-file generation.

Prerequisites

• A bounded issue, affected-file inventory, repository rules, and test commands.
• A recoverable branch and reviewer for material architectural, security, or data changes.

Instructions

1. Request a plan and non-goals before any edits.
2. Apply one coherent slice at a time, review the diff, and run its focused checks.
3. Keep human decisions for API, security, migration, and dependency changes.
4. Commit validated slices and revert/split failures rather than accepting a broad repair.

Output

• A sequence of small reviewed Composer-assisted changes with validation and rollback evidence.

Error Handling

Examples

Ask Composer to plan a module-local refactor, accept only the first reviewed slice, run its focused test, and commit it. Stop if it proposes a dependency, migration, or unrelated repository change.

Master Cursor Composer (Cmd+I / Ctrl+I) for multi-file code generation, scaffolding, and coordinated refactoring. Composer is the primary tool for changes that span multiple files.

Composer Interface

┌─────────────────────────────────────────────────────────┐
│  Composer                                    [Model ▾]  │
│─────────────────────────────────────────────────────────│
│  Context: [src/api/] [prisma/schema.prisma]             │
│─────────────────────────────────────────────────────────│
│  Create a CRUD API for products with:                   │
│  - Prisma model with id, name, price, category          │
│  - API routes (GET list, GET by id, POST, PUT, DELETE)  │
│  - Zod validation schemas                               │
│  - Unit tests with vitest                               │
│─────────────────────────────────────────────────────────│
│  ┌─ Changes ──────────────────────────────────────────┐ │
│  │  ✅ prisma/schema.prisma          (+12 lines)      │ │
│  │  ✅ src/api/products/route.ts     (new file)       │ │
│  │  ✅ src/api/products/[id]/route.ts (new file)      │ │
│  │  ✅ src/schemas/product.ts        (new file)       │ │
│  │  ✅ tests/api/products.test.ts    (new file)       │ │
│  └────────────────────────────────────────────────────┘ │
│  [Apply All]  [Review Changes]  [Reject]                │
└────────────────────…

Cursor Context Management

Overview

Control what Cursor sees so each conversation has the minimum relevant, policy-permitted context required for a reliable answer or edit.

Prerequisites

• A task scope, approved privacy setting, data classification, and working ignore configuration.
• Relevant files/interfaces that can be shared without credentials, customer data, or unrelated repositories.

Instructions

1. Start with the exact files, symbols, and constraints needed; avoid indiscriminate @Codebase use.
2. Inspect context pills/attachments before submitting and remove stale or sensitive material.
3. Start a new chat when topic or repository boundary changes.
4. Verify generated output against the source and tests; context relevance never replaces validation.

Output

• A minimal documented context set and a scoped result that can be independently reviewed.

Error Handling

Examples

For a bug in one service, attach its handler, interface, and focused test, state the failing behavior, and ask for a minimal fix. If the conversation starts discussing a different service, open a new chat instead of piling on more context.

Optimize how Cursor AI uses context to produce accurate, relevant responses. Context is everything the model sees when generating a response -- managing it well is the single biggest lever for output quality.

Context Sources

Cursor assembles context from multiple sources before each AI request:

┌─ Always Included ─────────────────────────────────────┐
│  System prompt (Cursor internal)                      │
│  Active .cursor/rules/*.mdc with alwaysApply: true    │
│  Current file (for Tab, Inline Edit)                  │
└───────────────────────────────────────────────────────┘
┌─ Conditionally Included ──────────────────────────────┐
│  Selected code (highlighted before Cmd+L/Cmd+K)       │
│  @-mention targets (@Files, @Folders, @Code)          │
│  Glob-matched rules (.mdc with matching globs)        │
│  Conversation history (prior turns in chat)           │
│  Open editor tabs (lightweight reference)             │
└───────────────────────────────────────────────────────┘
┌─ On-Demand (explicit @-mention) ──────────────────────┐
│  @Codebase  → semantic search across indexed files    │
│  @Docs      → crawled external documentation          │
│  @Web       → live web …

Cursor Custom Prompts

Overview

Create reusable prompts that encode approved engineering practice without injecting secrets, bypassing repository controls, or replacing human review.

Prerequisites

• A defined task class, source-of-truth repository rules, and a maintainer for prompt changes.
• A non-sensitive evaluation fixture and review path for any shared prompt.

Instructions

1. State the scope, inputs, constraints, acceptance checks, and explicit non-goals.
2. Keep prompts free of credentials, customer data, and contradictory instructions; reference reviewed rules rather than duplicating them.
3. Evaluate the prompt against a fixture, inspect the diff/output, and version shared prompts through normal review.
4. Retire or revise prompts that produce policy, quality, or security regressions.

Output

• A versioned, scoped reusable prompt with expected checks and a named owner.

Error Handling

Examples

For a test-writing prompt, specify the exact target module, existing test framework, failure behavior, and command to run. Review the generated test diff and reject it if it changes production code or hard-codes secrets.

Create effective prompts for Cursor AI. Covers prompt engineering fundamentals, reusable templates stored in project rules, and advanced techniques for consistent, high-quality code generation.

Prompt Anatomy

A well-structured Cursor prompt has four parts:

1. CONTEXT   → @-mentions pointing to relevant code
2. TASK      → What you want done (specific, actionable)
3. CONSTRAINTS → Rules, patterns, limitations
4. FORMAT    → How the output should look

Example: All Four Parts

@src/api/users/route.ts @src/types/user.ts         ← CONTEXT

Create a new API endpoint for updating user profiles. ← TASK

Constraints:                                         ← CONSTRAINTS
- Follow the same pattern as the users route
- Use Zod for input validation
- Return 400 for invalid input, 404 for missing user
- Only allow updating: name, email, avatarUrl

Return the endpoint code and the Zod schema as       ← FORMAT
separate code blocks.

Prompt Templates

Template: Feature Implementation

@[existing-similar-feature] @[relevant-types]

Implement [feature name] following the pattern in [reference file].
…

Cursor Debug Bundle

Overview

Collect a minimal, redacted reproduction for a Cursor issue involving context, rules, indexing, model behavior, or extensions. Debug material may contain proprietary code or prompts, so scope and retention matter as much as reproducibility.

Prerequisites

• A named issue owner, Cursor version, affected workspace, and approved bug-report destination.
• Permission to inspect logs and settings, plus redaction rules for code, prompts, paths, tokens, and user data.
• A minimal reproducer that does not require customer data or production credentials.

Instructions

1. Start with the smallest reproducible prompt, file set, rule set, and model configuration.
2. Record versions, active context, indexing state, extensions, and redacted console errors.
3. Remove proprietary code, credentials, identifiers, and full prompt/output text before sharing externally.
4. Test the proposed resolution in a non-sensitive workspace and document its result before closing the issue.

Diagnose and fix AI suggestion quality issues in Cursor. Covers why AI generates wrong code, how to improve context, and systematic debugging workflows.

Diagnostic Framework

When AI suggestions are wrong, the cause is almost always one of these:

┌─ Context Problems (80% of issues) ───────────────────────┐
│  1. Missing context: AI doesn't have the relevant code   │
│  2. Wrong context: AI has stale or irrelevant files      │
│  3. Too much context: context window overflow            │
│  4. No project rules: AI doesn't know your conventions   │
└──────────────────────────────────────────────────────────┘
┌─ Model Problems (15% of issues) ─────────────────────────┐
│  5. Wrong model for the task                             │
│  6. Model hallucinating APIs or patterns                 │
└──────────────────────────────────────────────────────────┘
┌─ Prompt Problems (5% of issues) ─────────────────────────┐
│  7. Ambiguous or vague instructions                      │
│  8. Conflicting requirements in prompt                   │
└──────────────────────────────────────────────────────────┘

Debugging by Symptom

AI Uses Wrong API or Library Version

Symptom: Generated code uses React.createClass, old Express syntax, or deprecated patterns.

Root cause: Model training data includes old code. No project rules specifying versions.

Fix:

# .cursor/rules/stack-versions.mdc
---
description: "Tech stack version pinning"
globs: ""
alwaysApply: true
---
# Stack Versions (ALWAYS use these)
- React 19 with Server Components (NOT class components)
- Next.js 15 App Router (NOT Pages Router)
- TypeScript 5.7 strict mode
- Prisma 6 (NOT Sequelize or TypeORM)
- Tailwin…

Cursor Extension Integration

Overview

Add extensions only when their publisher, permissions, data flow, compatibility, and maintenance risk are understood for the target repository.

Prerequisites

• Approved extension source, publisher verification, and workspace/data classification.
• A disposable profile or test workspace and a rollback method for extension settings.

Instructions

1. Review publisher, permissions, license, update history, and network/data behavior.
2. Test one extension in an isolated profile with a non-sensitive workspace.
3. Check conflicts with Cursor, rules, completion providers, and repository tooling.
4. Approve, document, and periodically review the extension; remove it on security or compatibility failure.

Output

• A tested extension decision with owner, version, permission/data assessment, and rollback path.

Error Handling

Examples

Test a formatter extension in a disposable profile against a sample repository, verify it does not transmit code or conflict with existing formatting, and then document the approved version. Remove it rather than disabling security controls if it conflicts.

Integrate VS Code extensions with Cursor IDE. Covers the Open VSX Registry, VSIX installation for Microsoft-exclusive extensions, conflict resolution with AI features, and recommended extension stacks.

Extension Marketplace: Key Difference from VS Code

Cursor uses the Open VSX Registry instead of Microsoft's VS Code Marketplace. This is because Microsoft's marketplace terms restrict access to VS Code products only.

Impact: Most popular extensions are on Open VSX. Some Microsoft-published extensions are not.

Available on Open VSX (works directly)

Cursor Git Integration

Overview

Use Cursor's Git features as a view and drafting aid while preserving repository branch protection, reviews, signed checks, and human ownership of commits/merges.

Prerequisites

• A clean or recoverable working tree, repository contribution rules, and correct remote identity.
• Required checks and reviewer/approval expectations for the target branch.

Instructions

1. Inspect status and diff before staging; stage only reviewed, intended files.
2. Draft but verify commit messages and never include secrets or unrelated changes.
3. Run required local checks, push through the normal branch/PR workflow, and resolve feedback with evidence.
4. Use revert or a new corrective commit for mistakes rather than rewriting shared history.

Output

• A scoped, reviewable Git change with validation evidence and a normal revert path.

Error Handling

Examples

Review a Cursor-generated diff, stage only its intended files, run the focused suite, and push a topic branch for review. If an accidental file is staged, unstage it and recheck the diff before committing.

Leverage Cursor's AI features within Git workflows: AI-generated commit messages, @Git context for code review, merge conflict resolution, and branch management.

Source Control Panel

Access with Cmd+Shift+G / Ctrl+Shift+G:

┌─ SOURCE CONTROL ────────────────────────────────┐
│  main ← current branch                         │
│                                                 │
│  Changes (3)                                    │
│    M  src/api/users.ts                         │
│    A  src/api/products.ts                      │
│    M  prisma/schema.prisma                     │
│                                                 │
│  Commit message: [✨ Generate with AI]          │
│  [Commit]  [Commit & Push]                      │
└─────────────────────────────────────────────────┘

AI-Generated Commit Messages

Click the sparkle/AI icon next to the commit message input. Cursor reads the staged diff and generates a message:

Example output:

feat: add product catalog CRUD API with Prisma model

- Add Product model to Prisma schema with name, price, category fields
- Create GET/POST/PUT/DELETE endpoints in src/api/products.ts
- Add Zod validation for product creat…

Cursor Hello World

Overview

Practice Tab, Chat, Inline Edit, and Composer in a disposable sample project before using them on production code. Every proposed diff remains subject to normal review, tests, security checks, and repository rules.

Instructions

1. Create a non-sensitive example project and enable the approved privacy setting.
2. Use one feature at a time, give clear constraints, and inspect every generated diff before accepting it.
3. Run focused tests/formatting after applying a change; reject or revert unexpected edits.
4. Move to real repositories only after rules, indexing exclusions, and review expectations are configured.

A hands-on 10-minute walkthrough of Cursor's four core AI features: Tab Completion, Chat, Inline Edit, and Composer.

Setup

mkdir cursor-hello && cd cursor-hello
npm init -y
npm install typescript tsx @types/node --save-dev
npx tsc --init

Open the project in Cursor: cursor . (or File > Open Folder).

Exercise 1: Tab Completion

Create src/utils.ts. Start typing and let Tab complete:

// Type this much:
export function formatCurrency(amount: number, currency: string

// Tab suggests:
export function formatCurrency(amount: number, currency: string = 'USD'): string {
  return new Intl.NumberFormat('en-US', {
    style: 'currency',
    currency,
  }).format(amount);
}

Press Tab to accept the full suggestion, or Cmd+Right Arrow to accept word-by-word.

Try These Prompts for Tab

Type a comment describing what you want, then start the function:

// Validate an email address using regex
export function validateEmail(

// Sort an array of objects by a key
export function sortBy<T>(

// Calculate the distance between two lat/lng points in km
export function haversineDistance(

Tab reads your comment and generates the implementation.

Exercise 2: Chat (Cmd+L)

Open Chat with Cmd+L. Try these prompts:

Ask about your code:

@src/utils.ts
What does the formatCurrency function do? Does it handle edge cases
like negative numbers or very large values?

Generate new code:

Write a TypeScript function that converts a nested object
to a flat key-value map with dot-separated keys.
Example: { a: { b: 1 } } → { "a.b": 1 }

Debug a concept:

Explain the difference between Promise.all() and Promise.allSettled()
with code examples showing when to use each.

Chat responds with explanations and code snippets. Click Apply on any code block to insert it into your editor…

Cursor Indexing Issues

Overview

Diagnose missing, stale, slow, or over-broad codebase indexing while keeping sensitive and generated files excluded from AI context.

Prerequisites

• The affected workspace, expected file/path, current ignore configuration, and a non-sensitive reproduction.
• Authority to inspect repository indexing settings without weakening data-exclusion rules.

Instructions

1. Confirm the file is inside an approved workspace root and not intentionally excluded by ignore configuration.
2. Check index status, refresh only the affected workspace, and compare the result against a known expected file.
3. Change ignore/rule configuration through normal review, then verify both inclusion of required files and exclusion of sensitive paths.

Output

• A scoped indexing diagnosis with a verified inclusion/exclusion result.

Error Handling

Examples

When src/service.ts is absent, verify its root and ignore rules, resync indexing, then ask a minimal chat to reference only that file. If a .env file becomes visible during testing, stop and correct the exclusion before continuing.

Diagnose and fix codebase indexing problems. Covers stuck indexing, empty search results, stale results, and performance optimization for large codebases.

Quick Diagnosis

Fix: Stuck Indexing

Step 1: Reduce Scope

Create or update .cursorignore in project root:

# .cursorignore -- exclude non-essential directories

# Build output
dist/
build/
.next/
out/
target/

# Dependencies (always exclude)
node_…

Cursor Install & Auth

Overview

Install Cursor, authenticate through the approved identity flow, and establish privacy settings before opening sensitive repositories. Do not treat local profiles or settings files as a secrets store.

Instructions

1. Download the signed installer from the official site or approved software catalog.
2. Sign in through the organization-approved account or SSO flow and confirm the expected tenant.
3. Enable approved privacy/data controls before opening proprietary code, then import only reviewed settings and extensions.
4. Verify Tab and Chat with a non-sensitive sample project; escalate tenant mismatch to the administrator.

Install Cursor IDE and authenticate your account. Covers all platforms, plan activation, and VS Code migration.

Installation

macOS

# Option 1: Direct download
open https://cursor.com/download

# Option 2: Homebrew
brew install --cask cursor

After install, drag Cursor.app to Applications. First launch may require: System Settings > Privacy & Security > Allow.

Linux

# Download AppImage
curl -fSL https://download.cursor.com/linux/appImage/x64 -o cursor.AppImage
chmod +x cursor.AppImage
./cursor.AppImage

# Or via .deb (Debian/Ubuntu)
curl -fSL https://download.cursor.com/linux/deb/x64 -o cursor.deb
sudo dpkg -i cursor.deb

Add to PATH for terminal launching:

# Add to ~/.bashrc or ~/.zshrc
alias cursor='/path/to/cursor.AppImage'

Windows

Download installer from cursor.com/download. Run the .exe installer. Cursor installs per-user (no admin required by default).

Authentication

First Launch Sign-In

1. Launch Cursor
2. Click Sign In in the welcome screen
3. Choose auth method:

• GitHub (recommended for developers)
• Google
• Email + password

1. Browser opens for OAuth flow
2. Approve the authorization
3. Return to Cursor -- it detects the auth automatically

Plan Activation

After sign-in, your plan is automatically active:

Cursor Keybindings

Overview

Configure keybindings for discoverability and accessibility without masking safety-critical editor commands or creating team-specific ambiguity.

Prerequisites

• Existing team/editor shortcut conventions and a recoverable keybindings backup.
• A non-sensitive test workspace for validating conflicts.

Instructions

1. Search existing bindings before assigning a shortcut and prefer documented Cursor defaults when practical.
2. Use workspace/team conventions for shared documentation; keep personal ergonomics local.
3. Test conflict behavior in a sample workspace and retain an easy reset/revert path.
4. Document custom bindings needed for pair programming, training, or support.

Output

• A tested keybinding change with conflict result and recovery instructions.

Error Handling

Examples

Assign a personal shortcut to a Cursor command only after checking the Keyboard Shortcuts UI for conflicts, test it in a sample project, and retain the previous keybindings entry. Do not overwrite a documented team shortcut without agreement.

Complete keyboard shortcut reference for Cursor IDE. Covers AI-specific shortcuts, standard editor commands, and customization. All shortcuts shown as macOS / Windows-Linux.

AI Feature Shortcuts

Primary AI Shortcuts

Context & Suggestions

Cursor Known Pitfalls

Overview

Use these pitfalls as preflight checks for AI-assisted work: context leakage, over-broad edits, stale rules, unsupported assumptions, and misplaced trust in generated output.

Prerequisites

• Project rules, data classification, and a normal review/test path for the work.
• A non-sensitive reproduction or sample when evaluating a Cursor behavior.

Instructions

1. Identify the relevant pitfall before accepting a suggestion or changing configuration.
2. Narrow context and task scope, then verify the resulting diff and tests.
3. Record recurring failures in reviewed rules or team guidance rather than relying on memory.

Output

• A documented prevention or remediation action tied to a specific Cursor failure mode.

Error Handling

Examples

Before accepting a multi-file refactor, check that it has an explicit file list, does not include secret/generated paths, and has tests. Reject broad changes and split the request when any of those checks fail.

Common Cursor IDE pitfalls and their solutions. Organized by category: AI behavior, security, configuration, performance, and team collaboration.

AI Feature Pitfalls

Pitfall 1: Blindly Applying Composer Changes

Problem: Clicking "Apply All" without reviewing diffs. Composer can generate code with wrong imports, hallucinated APIs, or logic errors.

Solution:

1. Click each file in the Changes panel to review its diff
2. Check imports: are they real packages in your project?
3. Check function calls: do the methods actually exist?
4. Run build after applying: npm run build
5. Run tests: npm test
6. Commit BEFORE running Composer (easy rollback with git checkout .)

Pitfall 2: Context Window Overflow

Problem: Adding too many @Files, @Folders, and @Codebase references. The model silently drops information, leading to:

• Ignoring your instructions
• Repeating itself
• Generating generic instead of project-specific code

Solution:

- Use @Files (specific) over @Folders (broad) over @Codebase (broadest)
- Limit to 3-5 file references per prompt
- Start new chats for new topics
- Remove stale context pills by clicking X

Pitfall 3: Continuing Stale Conver…

Cursor Local Dev Loop

Overview

Use Cursor inside the normal local development loop: small scoped change, inspect diff, run focused checks, commit reviewed work, and retain a rollback path.

Prerequisites

• A clean or recoverable branch, repository instructions, and required local test/format commands.
• Approved privacy settings and exclusion of secrets, production exports, and unrelated repositories.

Instructions

1. Start with a narrow issue and affected-file list, then use Chat/Inline Edit/Composer only for that scope.
2. Inspect every proposed diff and run the narrowest relevant formatter, test, and static check.
3. Commit one reviewed change at a time and use normal pull-request/branch rules for integration.
4. Revert rather than patching around an AI-generated regression when a focused check fails.

Output

• A small reviewed local change with validation evidence and an ordinary git rollback path.

Error Handling

Examples

Ask Inline Edit to update one function, inspect the diff, run that function's focused test, and commit it separately. If the test fails or unrelated files change, reject/revert and restate the task with tighter constraints.

Establish a productive daily development workflow using Cursor's AI features at each stage of the code-write-test-commit cycle.

The AI-Augmented Development Loop

┌─────────────────────────────────────────────────────────────┐
│  1. PLAN        →  Chat (Cmd+L) with @Codebase, @Docs      │
│  2. SCAFFOLD    →  Composer (Cmd+I) for new files           │
│  3. IMPLEMENT   →  Tab completion for line-by-line coding   │
│  4. REFINE      →  Inline Edit (Cmd+K) for targeted fixes  │
│  5. TEST        →  Chat to generate tests, terminal to run  │
│  6. COMMIT      →  AI-generated commit messages             │
│  7. REVIEW      →  @Git for branch diff review              │
└─────────────────────────────────────────────────────────────┘

Stage 1: Plan (Chat)

Start each task by discussing architecture with Chat:

@Codebase @Docs Prisma

I need to add a "favorites" feature where users can bookmark products.
What's the best approach given our current data model and API structure?
Consider: database schema, API endpoints, and frontend hooks.

Chat excels at:

• Architecture decisions before writing code
• Evaluating trade-offs (SQL join table vs JS…

Cursor Model Selection

Overview

Choose models by task risk, reasoning needs, data-handling policy, latency, and approved spend—not by apparent confidence in a single response.

Prerequisites

• The organization's approved model/provider list and data-routing constraints.
• A defined task, budget/latency expectation, and normal human review/test path.

Instructions

1. Use an approved economical model for simple explanations or edits; escalate only for a defined complex task.
2. Confirm the model's data-handling route before attaching proprietary or regulated content.
3. Record material model decisions for high-risk work and independently validate all generated output.
4. Reassess model choice when quality, cost, privacy, or latency exceeds the agreed threshold.

Output

• A model selection tied to task requirements, policy, and a validation plan.

Error Handling

Examples

Use an approved fast model for a localized type annotation with its focused test. For a high-impact architecture proposal, use the approved reasoning model, attach only necessary design documents, and require human reviewers to validate alternatives and rollback implications.

Configure AI models for Chat, Composer, and Agent mode. Cursor supports models from OpenAI, Anthropic, Google, and its own proprietary models. Choosing the right model per task is a major productivity lever.

Available Models

Included with Cursor Subscription

Premium Models (count against fast request quota)

Cursor Multi-Repo

Overview

Configure multi-root workspaces so Cursor sees only repositories and files needed for the task, preserving repository ownership and context boundaries.

Prerequisites

• Explicit authorization for each repository and a data-classification review for shared roots.
• Reviewed rules and ignore files in each root; only necessary filesystem permissions.

Instructions

1. Start with one repository, add another root only for a defined cross-repository task, and remove it afterward.
2. Use repository-specific rules/ignore files and verify indexing scope before asking a cross-repo question.
3. Keep changes separated by repository and use each repository's normal review and test process.

Output

• A deliberately scoped multi-root workspace with documented context and ownership boundaries.

Error Handling

Examples

To change an API contract and its client, open only those two repositories, attach the contract file explicitly, and create separate reviewed commits. Close the client root when the cross-repo validation is complete.

Work with multiple repositories and monorepo structures in Cursor. Covers multi-root workspaces, selective indexing, cross-project context, and rule inheritance patterns.

Multi-Root Workspaces

Open multiple project roots in a single Cursor window:

Creating a Workspace

1. Open first project: File > Open Folder > select project A
2. Add second project: File > Add Folder to Workspace... > select project B
3. Save workspace: File > Save Workspace As... > mywork.code-workspace

Workspace File Structure

// mywork.code-workspace
{
  "folders": [
    { "path": "/home/dev/api-service" },
    { "path": "/home/dev/web-frontend" },
    { "path": "/home/dev/shared-lib" }
  ],
  "settings": {
    "editor.tabSize": 2,
    "files.exclude": {
      "**/node_modules": true,
      "**/dist": true
    }
  }
}

Open workspace: cursor mywork.code-workspace or double-click the file.

How Indexing Works with Multi-Root

Cursor Performance Tuning

Overview

Improve Cursor responsiveness by measuring indexing scope, resource use, extension load, and network conditions while preserving required workspace and data controls.

Prerequisites

• A reproducible performance symptom, baseline measurement, and approved local settings backup.
• A reviewed .cursorignore strategy; do not expose excluded files to gain speed.

Instructions

1. Measure startup, indexing, memory, and request latency for the affected workspace.
2. Reduce unnecessary roots, extensions, and generated-file indexing before clearing caches.
3. Make one reversible change, compare against baseline, and retain the setting only when it improves the agreed metric.
4. Back up settings before cache maintenance and test the restored workspace afterward.

Output

• A measured, reversible performance change with before/after evidence.

Error Handling

Examples

For a slow monorepo, measure indexing time, add generated artifacts to the existing reviewed ignore rules, close inactive workspace roots, and measure again. Keep the change only if it improves the baseline without hiding required source or documentation.

Diagnose and fix Cursor IDE performance issues. Covers editor optimization, indexing tuning, extension auditing, AI feature configuration, and strategies for large codebases.

Performance Diagnostic Workflow

Step 1: Identify bottleneck
         ├── Editor lag? → Step 2 (Editor settings)
         ├── High CPU?   → Step 3 (Extension audit)
         ├── Slow AI?    → Step 4 (AI tuning)
         └── Memory?     → Step 5 (Memory management)

Step 2: Editor settings
         ├── Disable minimap, breadcrumbs
         ├── Reduce file watcher scope
         └── Increase memory limits

Step 3: Extension audit
         ├── Profile running extensions
         ├── Disable heavy extensions
         └── Use workspace-scoped disabling

Step 4: AI feature tuning
         ├── Optimize .cursorignore
         ├── Use faster models
         └── Manage chat history

Step 5: Memory management
         ├── Close unused workspace folders
         ├── Limit open editor tabs
         └── Clear caches

Editor Optimization

settings.json Performance Settings

{
  // Disable vis…

Cursor Privacy Settings

Overview

Configure Cursor data, privacy, and model-routing settings according to the repository's data classification and organization policy before code is added to AI context.

Prerequisites

• A current data-classification decision, tenant owner, and approved provider/model policy.
• Authority to inspect or enforce tenant settings and a process for exceptions/incidents.

Instructions

1. Select the approved privacy/data controls and verify their effective tenant/user state.
2. Configure .cursorignore and workspace trust to prevent secrets, customer data, and generated artifacts entering context.
3. Test the boundary with sanitized fixtures and retain redacted verification evidence.
4. Review settings after tenant, provider, policy, or data-classification changes.

Output

• A verified privacy configuration and context-exclusion boundary for the intended workspace.

Error Handling

Examples

Before opening a production repository, verify the approved privacy mode, add known secret/export paths to reviewed ignore configuration, and test with a sanitized path. If the file can still be attached, stop onboarding the repository until the boundary is fixed.

Configure Cursor's privacy controls to protect your code and data. Covers Privacy Mode, data handling policies, file exclusion, telemetry, and enterprise security settings.

Privacy Mode

What Privacy Mode Does

Enabling Privacy Mode

Individual: Cursor Settings > General > Privacy Mode > ON

Team enforcement (Business/Enterprise): Admin Dashboard > Privacy > "Enforce Privacy Mode for all members"

When team-enforced:

• Individual users canno…

Cursor Production Checklist

Overview

Use this gate before enabling Cursor for a production repository or team workflow. It verifies governance, context controls, review, and incident ownership—not the correctness of any generated code.

Prerequisites

• A named repository/tenant owner, data classification, and approved privacy/model policy.
• Reviewed rules/ignore files, identity controls, and a rollback path for tenant configuration.

Instructions

1. Complete each control with evidence: privacy setting, access model, exclusions, rules, review, tests, and support route.
2. Pilot in a representative non-sensitive repository and verify expected context boundaries.
3. Hold production enablement when any security, identity, data, or ownership gate is unverified.
4. Record the go/no-go decision and schedule periodic access/rule review.

Output

• A production-readiness record with owner, evidence links, exceptions, and verification date.

Error Handling

Examples

Pilot one repository with Privacy Mode, SSO, reviewed .cursorignore, and a pull-request review requirement. Verify a sample sensitive path cannot be added to context before signing off the production checklist.

Comprehensive checklist for configuring Cursor IDE for production use. Covers security hardening, project rules, indexing optimization, privacy settings, and team standardization.

Pre-Flight Checklist

Authentication & Licensing

[ ] All team members authenticated with correct plan (Pro/Business/Enterprise)
[ ] SSO configured (Business/Enterprise) -- see cursor-sso-integration skill
[ ] Privacy Mode enabled (enforced at team level for Business+)
[ ] Verify plan at cursor.com/settings

Project Rules

[ ] .cursor/rules/ directory created and committed to git
[ ] Core project rule with alwaysApply: true (stack, conventions, standards)
[ ] Language-specific rules with glob patterns (*.ts, *.py, etc.)
[ ] Security rule: "Never suggest hardcoded credentials or secrets"
[ ] No sensitive data (API keys, passwords) in any rule file

Minimum viable rule set:

# .cursor/rules/project.mdc
---
description: "Core project context"
globs: ""
alwaysApply: true
---
# Project: [Name]
Stack: [framework, language, database, etc.]
P…

Cursor Reference Architecture

Overview

Organize Cursor rules, ignore files, repository guidance, and workspace boundaries so AI assistance follows architecture rather than inventing it.

Prerequisites

• An approved repository architecture, ownership model, and data-classification policy.
• Maintainers authorized to review .cursor/rules, ignore files, and shared templates.

Instructions

1. Put durable engineering conventions in reviewed rules and keep sensitive/generated paths in ignore files.
2. Scope rules by repository area and avoid contradictory always-on instructions.
3. Test rule and indexing changes in a representative workspace before organization-wide rollout.
4. Review these files through normal pull requests with security and architecture owners when relevant.

Output

• A versioned Cursor configuration that maps rules and context boundaries to real repository ownership.

Error Handling

Examples

For a monorepo, commit a reviewed root rule for shared import conventions and scoped rules for each application. Add secrets, generated artifacts, and customer exports to ignore configuration, then verify a sample chat cannot attach those paths.

Reference architecture patterns for optimizing Cursor IDE project setup. Covers directory structure, rules organization, indexing strategy, and multi-project configuration for maximum AI effectiveness.

Project Layout for Cursor

A well-structured project makes AI features significantly more effective:

my-project/
├── .cursor/
│   └── rules/
│       ├── project.mdc          # alwaysApply: true (stack, conventions)
│       ├── security.mdc         # alwaysApply: true (security constraints)
│       ├── typescript.mdc       # globs: "**/*.ts,**/*.tsx"
│       ├── api-routes.mdc       # globs: "src/api/**/*.ts"
│       ├── database.mdc         # globs: "src/db/**/*.ts,prisma/**"
│       └── testing.mdc          # globs: "**/*.test.ts,**/*.spec.ts"
├── .cursorignore                # Exclude from AI + indexing
├── .cursorindexingignore        # Exclude from indexing only
├── .gitignore
├── src/
│   ├── api/                     # API routes
│   ├── services/                # Business logic
│   ├── db/                      # Database layer
│   ├── types/                   # Shared TypeScript ty…

Cursor Rules Config

Overview

Manage Cursor rules as versioned engineering policy that shapes AI context and behavior; rules must be specific, scoped, reviewed, and consistent with repository source of truth.

Prerequisites

• Repository owner approval, existing engineering/security standards, and a test workspace.
• A reviewed ignore strategy for secrets, generated files, and sensitive data.

Instructions

1. Write one clear rule per concern with scope, priority, and concrete acceptance behavior.
2. Keep shared rules in source control and use path-scoped rules for local conventions.
3. Test new rules on a non-sensitive fixture, inspect resulting behavior, and merge via normal review.
4. Periodically remove stale/conflicting rules and document any intentional exceptions.

Output

• A reviewed, versioned rule set with clear scope and a tested behavior example.

Error Handling

Examples

Add a path-scoped API rule that requires existing validation and tests, then test it on a sanitized fixture. Open a PR for the rule and verify it does not apply to unrelated frontend files before merging.

Configure project-specific AI behavior through Cursor's rules system. The modern approach uses .cursor/rules/*.mdc files; the legacy .cursorrules file is still supported but deprecated.

Rules System Architecture

Modern Project Rules (.cursor/rules/*.mdc)

Each .mdc file contains YAML frontmatter followed by markdown content:

---
description: "Enforce TypeScript strict mode and functional patterns"
globs: "src/**/*.ts,src/**/*.tsx"
alwaysApply: false
---
# TypeScript Standards

- Use `const` over `let`, never `var`
- Prefer pure functions over classes
- All functions must have explicit return types
- Use discriminated unions over enums

Frontmatter fields:

Cursor SSO Integration

Overview

Integrate Cursor with the organization's identity provider through a phased, auditable SSO/SCIM rollout that preserves emergency recovery and least privilege.

Instructions

1. Obtain approved SAML/SCIM values from the identity owner and validate them in a non-production or pilot tenant.
2. Pilot with a limited group, monitor sign-in/provisioning results, and correct attribute/group mappings before enforcement.
3. Enable organization-wide enforcement only after rollback/emergency access and deprovisioning paths are tested.
4. Retain redacted setup evidence and schedule access-review verification through the IdP.

Output

• An audited SSO configuration with scoped role mappings, tested SCIM provisioning, and a documented rollback/emergency-access path.

Examples

Pilot a single IdP group, confirm a new member receives the least-privilege Cursor role and a departed member is deprovisioned, then document the redacted IdP/Cursor audit evidence. If mapping is wrong, disable pilot enforcement and correct the group claim before organization-wide rollout.

Configure Single Sign-On for Cursor using SAML 2.0 or OIDC. Available on Business and Enterprise plans. Supports Okta, Microsoft Entra ID (Azure AD), Google Workspace, and any SAML 2.0 / OIDC compliant IdP.

Prerequisites

• Cursor Business or Enterprise subscription
• Admin access to both Cursor organization and Identity Provider
• Verified company domain in Cursor admin dashboard
• Understanding of SAML 2.0 or OIDC concepts

SSO Configuration: Okta

Step 1: Create SAML Application in Okta

1. Okta Admin Console > Applications > Create App Integration
2. Select SAML 2.0
3. App name: "Cursor IDE"

Step 2: Configure SAML Settings

Single Sign-On URL (ACS URL):
  https://cursor.com/api/auth/saml/callback

Audience URI (Entity ID):
  https://cursor.com/api/auth/saml

Name ID format: EmailAddress
Application username: Email

Attribute Statements:
  email    → user.email       (Required)
  name     → user.firstName + " " + user.lastName  (Optional)

Step 3: Download IdP Metadata

After creating the app in Okta:

1. Go to the app's "Sign On" tab
2. Click "Identity Provider metadata" link
3. Save the XML file

Step 4: Upload to Cursor

1. Cursor Admin Dashboard > SSO
2. Select "SAML 2.0"
3. Upload the IdP metadata XML (or paste the metadata URL)
4. Save configuration

Step 5: Test

1. Open Cursor incognito
2. Sign in with your @company.com email
3. Should redirect to Okta login
4. After auth, return to Cursor authenticated

Cursor Tab Completion

Overview

Use Tab for small, local code completions; it predicts text and does not establish correctness, security, or repository policy compliance.

Prerequisites

• An approved Cursor privacy setting and a workspace that excludes secrets and sensitive paths from context.
• Existing project rules, formatter, and focused tests for the code being changed.

Instructions

1. Write the function signature, types, and a concise intent comment before considering a suggestion.
2. Accept only the scoped portion you understand, then inspect the diff and run the focused check.
3. Reject suggestions that add unrelated behavior, dependencies, credentials, or policy exceptions.

Output

• A small reviewed completion with source-control visibility and test evidence.

Error Handling

Examples

For a CSV parser, write the return type and validation constraints first. Accept only the parser body, inspect the resulting diff, and run its unit test. If Tab adds filesystem access or changes another file, reject it rather than editing around the suggestion.

Master Cursor's AI-powered Tab completion system. Tab uses a specialized Cursor model trained for inline code prediction -- it learns from your accept/reject behavior to improve over time.

How Tab Works

1. You type code in the editor
2. Cursor's model predicts what comes next based on: current file, open tabs, recent edits, project rules
3. Ghost text (gray text) appears inline
4. You decide: Tab to accept, Esc to dismiss

// You type:
function validateEmail(email: string)

// Ghost text appears:
function validateEmail(email: string): boolean {
  const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;    ← gray ghost text
  return emailRegex.test(email);
}

Key Bindings

…

Cursor Team Setup

Overview

Onboard a Cursor team with approved identity, privacy, rules, repository access, and support ownership before broad AI-assisted development begins.

Prerequisites

• A named tenant owner, identity source, approved plan, and data-use policy.
• Reviewed repository templates, ignore rules, and owner for onboarding/offboarding.

Instructions

1. Pilot with a small group using SSO/SCIM or approved identity controls and least-privilege roles.
2. Publish reviewed shared rules and ignore files through source control, not untracked local instructions.
3. Train members on context boundaries, diff review, testing, escalation, and account recovery.
4. Review access, policy enforcement, and adoption evidence before expanding the rollout.

Output

• A governed team rollout with ownership, onboarding evidence, and offboarding/access-review controls.

Error Handling

Examples

Pilot one engineering group, verify SSO and Privacy Mode policy, open a template repository with reviewed rules, and collect a redacted onboarding receipt. Expand only after a new user and a departed user both pass the expected provisioning/deprovisioning checks.

Configure Cursor for teams and organizations. Covers plan selection, member management, shared configurations, Privacy Mode enforcement, and onboarding workflows.

Plan Comparison

Cursor Upgrade & Migration

Overview

Upgrade Cursor or migrate settings through a staged, reversible rollout that preserves policy, extensions, rules, workspace trust, and user recovery.

Prerequisites

• Current/target versions, release-note review, supported-platform confirmation, and a settings backup.
• Pilot users, a named migration owner, and an approved rollback or previous installer.

Instructions

1. Inventory settings, extensions, rules, integrations, and identity/privacy requirements.
2. Test the target version with a pilot using non-sensitive workspaces and required workflows.
3. Document compatibility, performance, and policy results before broader rollout.
4. Roll back or pause on sign-in, privacy, extension, or workflow regression; retain evidence for follow-up.

Output

• A staged upgrade/migration record with pilot evidence, owner, compatibility decision, and rollback instructions.

Error Handling

Examples

Back up a pilot user's settings, install the target version in a test profile, verify SSO, privacy, rules, indexing, and a sample repository, then expand only after the pilot receipt passes. Keep the previous installer until the observation window closes.

Upgrade Cursor IDE versions, migrate from VS Code, and transfer configurations between machines.

Version Upgrades

Auto-Update (Recommended)

Cursor checks for updates automatically. When available:

1. A notification appears: "A new version is available"
2. Click "Restart to Update" or go to Help > Check for Updates
3. Cursor downloads, installs, and restarts

Manual Update

If auto-update fails or is disabled:

# macOS (Homebrew)
brew upgrade --cask cursor

# macOS/Linux/Windows: Download latest from
# https://cursor.com/download

# Linux AppImage: replace the old file
curl -fSL https://download.cursor.com/linux/appImage/x64 -o cursor.AppImage
chmod +x cursor.AppImage

Pre-Upgrade Checklist

[ ] Note current version: Help > About
[ ] Check release notes: changelog.cursor.sh
[ ] Backup settings:
    macOS: cp -r ~/Library/Application\ Support/Cursor/User ~/cursor-settings-backup
    Linux: cp -r ~/.config/Cursor/User ~/cursor-settings-backup
[ ] Expor…

Cursor Usage Analytics

Overview

Use tenant analytics to improve enablement, capacity, and policy compliance with aggregated, purpose-limited data—not to inspect individual prompts or create unapproved employee surveillance.

Prerequisites

• An approved analytics purpose, access role, retention rule, and privacy/HR review where applicable.
• Aggregated reports and a named owner for any action taken from the data.

Instructions

1. Define the decision the metric supports and collect the minimum aggregation needed.
2. Review adoption, spend, model use, and policy signals against an agreed baseline.
3. Share only authorized aggregate findings and document remediation/enablement actions.
4. Reassess access and retention regularly; do not repurpose analytics without approval.

Output

• A purpose-bound aggregate report with owner, time range, access boundary, and action items.

Error Handling

Examples

Review monthly aggregate model spend by team against budget, publish the variance and owner, and adjust approved caps after review. Do not export individual chat content or infer productivity from request counts.

Track and analyze Cursor usage metrics for Business and Enterprise plans. Covers dashboard metrics, cost optimization, adoption tracking, and ROI measurement.

Admin Dashboard Overview

Access: cursor.com/settings > Team > Usage (Business/Enterprise only)

┌─ Dashboard ────────────────────────────────────────────┐
│                                                        │
│  Total Requests This Month:  12,847                    │
│  Fast Requests Remaining:    2,153 / 15,000            │
│  Active Users:               28 / 30 seats             │
│  Most Used Model:            Claude Sonnet (62%)       │
│                                                        │
│  ┌─ Usage Trend ─────────────────────────────────┐     │
│  │  ▆▆▇▇██▇▆▇█▇▇▆▅                              │     │
│  │  Mon Tue Wed Thu Fri Sat Sun                   │     │
│  └───────────────────────────────────────────────┘     │
│                                                        │
│  ┌─ Top Users ───────────────────────────────────┐     │
│  │  alice@co.com     847 requests  (Sonnet)      │     │
│  │  bob@co.com   …