Configure BYOK API keys for OpenAI, Anthropic, Google, Azure, and custom models in Cursor.
ReadWriteEditBash(cmd:*)
Cursor API Key Management
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
| Provider |
Key Format |
Models Available |
| OpenAI |
sk-proj-... or sk-... |
GPT-4o, GPT-4o-mini, o1, o3, GPT-5 |
| Anthropic |
sk-ant-api03-... |
Claude Sonnet, Claude Opus, Claude Haiku |
| Google |
AIzaSy... |
Gemini 2.5 Pro, Gemini Flash |
| Azure OpenAI |
Azure portal key |
Any deployed Azure OpenAI model |
| AWS Bedrock |
IAM credentials |
Claude, Titan, Llama models |
| OpenAI-compatible |
Varies |
Ollama, LM Studio, Together AI, etc. |
Configuration Steps
OpenAI
- Go to platform.openai.com/api-keys
- Create a new API key (project-scoped recommended)
- In Cursor:
Cursor Settings > Models > check Use own API key
- Paste key in the OpenAI API Key field
- Select model from dropdown (e.g.,
gpt-4o)
Anthropic
- Go to console.anthropic.com/settings/keys
- Create a new API key
- In Cursor:
Cursor Settings > Models > check Use own API key
- Paste key in the Anthropic API Key field
- Select Claude model from dropdown
Google (Gemini)
- Go to aistudio.google.com/apikey
- Create API key
- In Cursor:
Cursor Settings > Models > check Use own API key
- Paste key in the Google API Key field
Azure OpenAI
Azure requires additional configuration beyond a simple API key:
- In Azure Portal: create an Azure OpenAI resource
- Deploy your desired model (e.g.,
gpt-4o)
- Note the Endpoint URL and API Key from the resource
- In Cursor:
Cursor Settings > Models:
Azure Configuration:
API Key: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Endpoint: https://your-instance.openai.azure.com
Deployment: your-gpt4o-deployment-name
API Version: 2024-10-21
Custom OpenAI-Compatible Endpoints
For self-hosted models (Ollama, vLLM) or third-party providers:
Cursor Settings > Models > Add Model- Model name: e
Set up and optimize Cursor codebase indexing for semantic code search and @Codebase queries.
ReadWriteEditBash(cmd:*)
Cursor Codebase Indexing
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
- Open your project in Cursor
- Indexing starts automatically on first open
- Check status: look at the bottom status bar for "Indexing..." indicator
- View indexed files:
Cursor Settings > Features > Codebase Indexing > View included files
Verify Indexing Status
The status bar shows:
- "Indexing..." with progress indicator -- initial indexing in progress
- "Indexed" -- indexing complete,
@Codebase queries are available
- No indicator -- indexing may be disabled or not started
Configuration
.cursorignore
Exclude files from indexing and AI features. Place in project root. Uses .gitignore syntax:
# .cursorignore
# Build artifacts (large, not useful for AI context)
dist/
build/
out/
.next/
target/
# Dependencies
node_modules/
vendor/
venv/
.venv/
# Generated files
*.min.js
*.min.css
*.bundle.js
*.map
*.lock
# Large data files
*.csv
*.sql
*.sqlite
*.parquet
fixtures/
seed-data/
# Secrets (defense in depth -- also use .gitignore)
.env*
**/secrets/
**/credentials/
.cursorindexingignore
Exclude files from indexing only but keep them accessible to AI features when explicitly referenced:
# .cursorindexingignore
# Large test fixtures -- don't index, but allow @Files reference
tests/fixtures/
e2e/recordings/
# Documentation build output
docs/.vitepress/dist/
Difference: .cursorignore hides files from both indexing and AI features. .cursorindexingignore
Troubleshoot common Cursor IDE errors: authentication, completion, indexing, API, and performance issues.
ReadWriteEditBash(cmd:*)
Cursor Common Errors
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:
- Clear browser cookies for
cursor.com and auth.cursor.com
- Try incognito/private window for the OAuth flow
- Check if browser is blocking popups from cursor.com
- 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:
- Verify subscription at cursor.com/settings
- Confirm the email address matches your Cursor account
- Sign out (
Cmd+Shift+P > Sign Out) then sign back in
- If on a team plan, ask admin to verify your seat is assigned
"Session expired"
Symptoms: Features stop working mid-session.
Fix: Cmd+Shift+P > Cursor: Sign Out > Sign back in. This refreshes the auth token.
AI Completion Errors
Tab Suggestions Not Appearing
Symptoms: No ghost text while typing.
Causes and fixes:
| Cause |
Fix |
| Tab completion disabled |
Cursor Settings > Tab > enable |
| Conflicting extension (Copilot/TabNine) |
Disable other completion extensions |
| File type not supported |
Check file is a recognized language |
| Rate limited (Free plan) |
Wait or upgrade to Pro |
| Large file (>10K lines) |
Split file or use Cmd+K for specific sections |
"Request failed" / "Model unavailable"
Symptoms: Chat or Composer returns an error instead of a response.
Fix:
- Check status.cursor.com for outages
- Switch to a different model (model dropdown in Chat/Composer)
- If using BYOK, verify API key is valid and has credits
- Try a shorter prompt (may have hit context limit)
Poor Quality Suggestions
Symptoms: AI generates irrelevant, outdated, or incorrect code.
Fix:
- Add context: use
@Files to reference relevant code
- Add project rules: create
.cursor/rules/*.mdc with your patterns
- Switch model: try Claude Opus or GPT-5 for complex tasks
- Start a new chat: long conversation
Compliance and security auditing for Cursor IDE usage: SOC 2, GDPR, HIPAA assessment, evidence collection, and remediation.
ReadWriteEditBash(cmd:*)
Cursor Compliance Audit
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
| Certification |
Status |
Notes |
| SOC 2 Type II |
Certified |
Annual audit, report available on request |
| Penetration testing |
Annual |
Results shared under NDA (Enterprise) |
| Encryption at rest |
AES-256 |
All stored data |
| Encryption in transit |
TLS 1.2+ |
All API communications |
| Zero data retention |
Available |
Via Privacy Mode |
| GDPR compliance |
Yes |
EU data processing supported |
| HIPAA BAA |
Not available (as of early 2026) |
See HIPAA section |
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 applicable)
CC6.6 — System Boundaries
[ ] Privacy Mode enforced at team level
[ ] .cursorignore configured for sensitive files
[ ] Data classification aligned with .cursorignore patterns
[ ] Model provider data retention agreements documented
[ ] BYOK configuration documented (if applicable)
Evidence:
- Privacy Mode enforcement screenshot
- .cursorignore file contents (committed to git)
- Cursor data use policy acceptance
- API key provider agreements
CC6.7 — Data Transmission Security
[ ] All Cursor API calls use TLS 1.2+
[ ] Corporate proxy configured with valid certificates
[ ] No self-signed certificates or TLS bypasses
[ ] Network firewall rules documented
Evidence:
- Network architecture diagram showing Cursor data flows
- Firewall rules for cursor.com domains
- Proxy configuration settings
CC7.2 — Monitoring
[ ] Admin das
Master Cursor Composer for multi-file AI editing, scaffolding, and refactoring.
ReadWriteEditBash(cmd:*)
Cursor Composer Workflows
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] │
└─────────────────────────────────────────────────────────┘
Core Workflow Patterns
1. Feature Scaffolding
Generate a complete feature across multiple files:
@src/api/users/route.ts @prisma/schema.prisma
Create a complete "orders" feature following the same patterns as users:
1. Prisma model: Order (id, userId, items, total, status, createdAt)
2. OrderItem model: (id, orderId, productId, quantity, price)
3. API routes: GET /api/orders, GET /api/orders/[id], POST /api/orders
4. Zod validation schemas matching the Prisma models
5. Service layer with createOrder, getOrders, getOrderById
Composer reads the referenced files to replicate the existing pattern.
2. Cross-File Refactoring
Rename, restructure, or migrate patterns across the codebase:
@src/services/ @src/api/
Refactor all service functions to use a Result type instead of throwing errors.
Current pattern:
async function getUser(id: string): Promise<User> { throw new NotFoundError(); }
Target pattern:
async function getUser(id: string): Promise<Result<User, NotFoundError>> { ... }
Update all callers in the API routes to handle the Result type.
3. Test Generation
Generate tests that match existing test patterns:
@tests/api/users.test.ts @src/api/products/route.ts
Generate vitest tests for the products API following the same patterns
as users.test.ts. Cover:
- GET /api/products returns list with pagination
- GET /api/products/[id] returns 404 for mi
Optimize context window usage in Cursor with @-mentions, context pills, and conversation strategy.
ReadWriteEditBash(cmd:*)
Cursor Context Management
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 search results │
│ @Git → uncommitted diff or branch diff │
│ @Lint Errors → current file lint diagnostics │
└───────────────────────────────────────────────────────┘
Context Pills
Active context appears as pills at the top of the Chat/Composer panel:
[main.ts] [src/utils/] [@Web: next.js 15] [Rule: typescript-standards]
- Click a pill to expand and see its contents
- Click
x on a pill to remove it from context
- Adding too many pills fills the context window, degrading response quality
@-Mention Strategy by Task
Code Understanding
@src/auth/middleware.ts @src/types/user.ts
Explain how the JWT validation works and what happens when a token expires.
Use @Files for specific files. Avoid @Folders unless you need the full directory -- it consumes a lot of context.
Bug Investigation
@src/hooks/useCart.ts @Lint Errors @Recent Changes
The cart total is NaN after the latest changes. What broke?
@Recent Changes + @Lint Errors gives the model forensic context.
Architecture Questions
@Codebase where are database queries made?
@Codebase triggers semantic search across the indexed codebase. Good for discovery when you do not know which files are relevant. Costs more context than targeted @Files mentions.
Using External Knowledge
@Docs Prisma @Web prisma client extensions 2025
How do I add soft-delete as a Prisma Client extension?
@D
Create effective custom prompts for Cursor AI using project rules, prompt engineering patterns, and reusable templates.
ReadWriteEditBash(cmd:*)
Cursor Custom Prompts
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].
Requirements:
- [requirement 1]
- [requirement 2]
- [requirement 3]
Constraints:
- Same error handling pattern as [reference]
- Same file structure as [reference]
- Include TypeScript types for all public interfaces
Template: Bug Fix
@[buggy-file] @Lint Errors
Bug: [describe the incorrect behavior]
Expected: [describe correct behavior]
Steps to reproduce: [1, 2, 3]
The error message is: [paste error]
Find the root cause and suggest a fix. Do not change
the public API surface.
Template: Code Review
@[file-to-review]
Review this code for:
1. Logic errors or edge cases
2. Security vulnerabilities (injection, XSS, auth bypass)
3. Performance issues (N+1 queries, unnecessary re-renders)
4. TypeScript type safety (any casts, missing generics)
5. Naming and readability
List issues as: [severity] [line/area] [description] [suggestion]
Template: Test Generation
@[source-file] @[existing-test-file]
Generate tests for [function/class name] covering:
- Happy path with valid inputs
- Edge cases: empty input, null, undefined, max values
- Error cases: invalid input, missing required fields
- Async behavior: success and failure scenarios
Follow the same test structure as [existing-test-file].
Use [vitest/jest/pytest] assertions.
Template: Refactoring
@[file-to-refactor]
Refactor this code to [goal]:
- [specific change 1]
- [specific change 2]
Do NOT change:
- The public API (function signatures, return types)
- The test behavior (existing tests must still pass)
- External imports
Storing Prompts as Project Rules
Convert frequently used prompts into .cursor/rules/
Debug AI suggestion quality, context issues, and code generation problems in Cursor.
ReadWriteEditBash(cmd:*)
Cursor Debug Bundle
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)
- Tailwind CSS 4 (NOT styled-components)
- Node.js 22 (ESM, NOT CommonJS require())
AI Generates Code That Doesn't Match Your Patterns
Symptom: Generated code uses different naming, structure, or patterns than your codebase.
Root cause: AI does not have your existing code as context.
Fix: Reference your existing patterns explicitly:
@src/api/users/route.ts
Create src/api/products/route.ts following the EXACT same patterns:
same error handling, same response format, same validation approach.
AI Hallucinates Non-Existent Functions
Symptom: AI calls functions or uses imports that do not exist in your project or in the library.
Root cause: Model confuses similar libraries or invents plausible-sounding APIs.
Fix:
- Add
@Docs context: @Docs Prisma gives the AI real API documentation
- Verify generated imports: run
npm run build immediately
Integrate VS Code extensions with Cursor IDE: compatibility, Open VSX registry, VSIX installation, conflict resolution, and essential extensions.
ReadWriteEditBash(cmd:*)
Cursor Extension Integration
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)
| Extension |
Category |
| ESLint |
Linting |
| Prettier |
Formatting |
| GitLens |
Git visualization |
| Docker |
Container management |
| Python |
Python language support |
| Pylance |
Python analysis (community build) |
| Go |
Go language support |
| Rust Analyzer |
Rust language support |
| Tailwind CSS IntelliSense |
CSS utilities |
| Auto Rename Tag |
HTML/JSX editing |
| Error Lens |
Inline error display |
| TODO Highlight |
Comment highlighting |
| Thunder Client |
API testing |
NOT Available on Open VSX (need manual install)
| Extension |
Reason |
Workaround |
| GitHub Copilot |
Microsoft exclusive |
Use Cursor's built-in AI (better integration) |
| Live Share |
Microsoft exclusive |
Use other collaboration tools |
| Remote - SSH |
Microsoft exclusive |
Install via VSIX |
| C# Dev Kit |
Microsoft exclusive |
Install via VSIX |
| IntelliCode |
Microsoft exclusive |
Cursor's Tab replaces this |
Installing Extensions
From Open VSX (In-App)
Cmd+Shift+X → search extension name → Install
From VSIX (Manual)
For extensions not on Open VSX:
- Go to the VS Code Marketplace website: marketplace.visualstudio.com
- Find the extension page
- Click "Download Extension" (downloads
.vsix file)
- In Cursor:
Cmd+Shift+P > Extensions: Install from VSIX...
- Select the downloaded
.vsix file
From Command Line
# Install from Open VSX
cursor --install-extension dbaeumer.vscode-eslint
# Install from VSIX file
cursor --install-extension ~/Downloads/extension.vsix
# List install
Integrate Git workflows with Cursor IDE: AI commit messages, @Git context, diff review, and conflict resolution.
ReadWriteEditBash(cmd:*)
Cursor Git Integration
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 creation and update inputs
Tips for better commit messages:
- Stage related changes together (not unrelated edits)
- The AI reads the diff, so clean diffs produce better messages
- Edit the generated message before committing if needed
- Configure Conventional Commits in project rules:
# .cursor/rules/git-conventions.mdc
---
description: "Git commit conventions"
globs: ""
alwaysApply: true
---
Use Conventional Commits format:
- feat: new feature
- fix: bug fix
- refactor: code restructure without behavior change
- docs: documentation only
- test: adding or updating tests
- chore: maintenance tasks
Keep subject line under 72 characters.
Body explains WHY, not WHAT (the diff shows what).
@Git Context in Chat
Use @Git in Chat or Composer to include git context:
@Git (Working State)
@Git
Review my uncommitted changes. Check for:
- Any debugging code left in (console.log, debugger)
- Missing error handling
- Type safety issues
- Potential performance problems
@Git includes the diff of all uncommitted changes (staged + unstaged).
@Git (Branch Diff)
@Git
Summarize all changes in this branch compared to main.
What features/fixes were implemented?
Are there any breaking changes?
When on a feature branch, @Git shows the cumulative diff between your branch and main.
Merge Conflict Resolution
When a merge conflict occurs, use Chat for AI assistance:
Create your first project using Cursor AI features: Tab, Chat, Composer, and Inline Edit.
ReadWriteEditBash(cmd:*)
Cursor Hello World
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.
Exercise 3: Inline Edit (Cmd+K)
Open src/utils.ts. Select the formatCurrency function body. Press Cmd+K.
Type your instruction:
Add support for locale parameter with default 'en-US'.
Handle NaN input by returning '$0.00'.
Cursor shows the diff inline:
- Green = added lines
- Red = removed lines
Press Cmd+Y to accept, Esc to reject.
Inline Edit Quick Tasks
Select any code and press Cmd+K with instructions like:
"Add TypeScript types""Refactor to use early
Troubleshoot Cursor codebase indexing: stuck indexing, empty search, @codebase failures, and performance issues.
ReadWriteEditBash(cmd:*)
Cursor Indexing Issues
Diagnose and fix codebase indexing problems. Covers stuck indexing, empty search results, stale results, and performance optimization for large codebases.
Quick Diagnosis
| Symptom |
Likely Cause |
Quick Fix |
| Status bar stuck on "Indexing..." |
Large codebase or network issue |
Add .cursorignore, resync |
| @Codebase returns nothing |
Index not built or file excluded |
Wait for index, check ignore files |
| @Codebase finds wrong code |
Stale index |
Resync index |
| Indexing crashes / restarts |
Memory or file watcher limits |
Increase limits, reduce scope |
| "Unable to index" error |
Network blocked or auth expired |
Check proxy/firewall, re-auth |
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_modules/
vendor/
.venv/
venv/
# Generated / large files
*.min.js
*.min.css
*.bundle.js
*.map
*.lock
package-lock.json
yarn.lock
pnpm-lock.yaml
# Data files
*.csv
*.sql
*.sqlite
*.parquet
*.json.gz
fixtures/
# Media
*.png
*.jpg
*.gif
*.svg
*.mp4
*.woff2
Step 2: Resync Index
Cmd+Shift+P > Cursor: Resync Index
Step 3: Clear Cache (if resync fails)
# macOS
rm -rf ~/Library/Application\ Support/Cursor/Cache/
rm -rf ~/Library/Application\ Support/Cursor/CachedData/
# Linux
rm -rf ~/.config/Cursor/Cache/
rm -rf ~/.config/Cursor/CachedData/
# Windows (PowerShell)
Remove-Item -Recurse "$env:APPDATA\Cursor\Cache"
Remove-Item -Recurse "$env:APPDATA\Cursor\CachedData"
Restart Cursor after clearing cache. Full re-index begins automatically.
Fix: @Codebase Returns No Results
Check 1: Is Indexing Complete?
Look at the bottom status bar. If it says "Indexing...", wait for it to finish. For projects with 10K+ files, initial indexing can take 10-30 minutes.
Check 2: Is the File Excluded?
A file might be excluded by:
.gitignore (Cursor respects this by default).cursorignore (explicit exclusion).cursorindexingignore (excluded from index but not from AI features)
Verify: Cursor Settings > Features > Codebase Indexing > View included files
This opens a text file listing all indexed paths. Search for the file you expect to find.
Check 3: Network Connectivity
Indexing requires network access to Cursor's embedding
Install Cursor IDE and configure authentication across macOS, Linux, and Windows.
ReadWriteEditBash(cmd:*)
Cursor Install & Auth
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
- Launch Cursor
- Click Sign In in the welcome screen
- Choose auth method:
- GitHub (recommended for developers)
- Google
- Email + password
- Browser opens for OAuth flow
- Approve the authorization
- Return to Cursor -- it detects the auth automatically
Plan Activation
After sign-in, your plan is automatically active:
| Plan |
Price |
Includes |
| Free |
$0/mo |
50 slow premium requests/month, Tab completions (limited) |
| Pro |
$20/mo |
500 fast premium requests/month, unlimited Tab, all models |
| Business |
$40/user/mo |
Pro features + Privacy Mode enforced, SSO, admin dashboard |
| Enterprise |
Custom |
Business + SCIM, SLA, dedicated support |
Upgrade at: cursor.com/settings
VS Code Migration
On first launch, Cursor detects existing VS Code installations and offers one-click import:
What Migrates Automatically
- Settings:
settings.json preferences
- Keybindings: Custom keyboard shortcuts
- Extensions: Re-installs compatible extensions from Open VSX Registry
- Themes: Color themes and icon packs
- Snippets: User-defined code snippets
What Does NOT Migrate
Master Cursor keyboard shortcuts and customize keybindings for AI features and editor commands.
ReadWriteEditBash(cmd:*)
Cursor Keybindings
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
| Action |
macOS |
Windows/Linux |
Notes |
| Chat panel |
Cmd+L |
Ctrl+L |
Open/focus AI chat sidebar |
| Inline Edit |
Cmd+K |
Ctrl+K |
Edit selected code with AI |
| Composer |
Cmd+I |
Ctrl+I |
Multi-file AI editing |
| Full Composer |
Cmd+Shift+I |
Ctrl+Shift+I |
Expanded composer view |
Context & Suggestions
| Action |
macOS |
Windows/Linux |
Notes |
| Add to Chat context |
Cmd+Shift+L |
Ctrl+Shift+L |
Add selected code to existing chat |
| Accept Tab suggestion |
Tab |
Tab |
Accept full ghost text |
| Accept word-by-word |
Cmd+→ |
Ctrl+→ |
Partial Tab acceptance |
| Dismiss suggestion |
Esc |
Esc |
Reject ghost text |
| Force trigger completion |
Ctrl+Space |
Ctrl+Space |
Manually trigger Tab |
| Accept inline edit |
Cmd+Y |
Ctrl+Y |
Accept Cmd+K changes |
| Reject inline edit |
Esc |
Esc |
Dismiss Cmd+K changes |
Chat Management
| Action |
macOS |
Windows/Linux |
Notes |
| New chat |
Cmd+N (in chat) |
Ctrl+N |
Start fresh conversation |
| Toggle chat panel |
Cmd+L |
Ctrl+L |
Show/hide chat sidebar |
Essential Editor Shortcuts
Navigation
| Action |
macOS |
Windows/Linux |
| Command Palette |
Cmd+Shift+P |
Ctrl+Shift+P |
| Quick Open file |
Cmd+P |
Ctrl+P |
| Go to Symbol |
Cmd+Shift+O
Avoid common Cursor IDE pitfalls: AI feature mistakes, security gotchas, configuration errors, and team workflow issues.
ReadWriteEditBash(cmd:*)
Cursor Known Pitfalls
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 Conversations
Problem: Reusing a 20+ turn conversation for a new task. The conversation history fills context, leaving no room for your new request.
Solution: Cmd+N to start a new chat for each distinct task.
Pitfall 4: AI Generates Deprecated Patterns
Problem: AI uses old APIs (React class components, Express 4 syntax, CommonJS require).
Solution: Pin versions in project rules:
# .cursor/rules/stack.mdc
---
description: "Tech stack versions"
globs: ""
alwaysApply: true
---
ALWAYS use these versions:
- React 19 with Server Components (NOT class components)
- Next.js 15 App Router (NOT Pages Router)
- TypeScript 5.7 strict (NOT any casts)
- ESM imports (NOT CommonJS require)
Pitfall 5: Tab Completion Fighting Manual Input
Problem: Tab suggests text you do not want, and you accidentally accept it while pressing Tab for indentation.
Solution:
- Use
Esc to dismiss before pressing Tab for indentation
- Remap Tab acceptance:
Cmd+K Cmd+S > search acceptCursorTabSuggestion > assign different key
- Or temporarily disable Tab completion for specific tasks
Security Pitfalls
Pitfall 6: Pasting Secrets into Chat
Problem: Copying an error message that includes an API key, database URL, or token and past
Optimize daily development workflow with Cursor IDE using Chat, Composer, Tab, and Git integration.
ReadWriteEditBash(cmd:*)
Cursor Local Dev Loop
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 JSON array, REST vs GraphQL)
- Understanding existing patterns via
@Codebase
Stage 2: Scaffold (Composer)
Once the plan is clear, use Composer for multi-file generation:
@src/api/users/route.ts @prisma/schema.prisma
Create the favorites feature:
1. prisma/schema.prisma: Favorite model (userId, productId, createdAt)
2. src/api/favorites/route.ts: GET (list user favorites), POST (add), DELETE (remove)
3. src/services/favorite.service.ts: FavoriteService with Prisma operations
4. src/hooks/useFavorites.ts: React hook with optimistic updates
Follow existing patterns from the users API.
Tip: Reference existing files with @ so Composer replicates your patterns instead of inventing new ones.
Stage 3: Implement (Tab Completion)
With scaffolded files open, use Tab for implementation details:
// Open favorite.service.ts and start typing:
async toggleFavorite(userId: string, productId: string
// Tab completes the full method:
async toggleFavorite(userId: string, productId: string): Promise<Favorite | null> {
const existing = await this.prisma.favorite.findUnique({
where: { userId_productId: { userId, productId } },
});
if (existing) {
await this.prisma.favorite.delete({ where: { id: existing.id } });
return null;
}
return this.prisma.favorite.create({ data: { userId, productId } });
}
Workflow tips for Tab:
- Open related files in tabs (service, types, API route) -- Tab reads open tabs for context
- Write type signatures first -- Tab generates bette
Configure and select AI models in Cursor for Chat, Composer, and Agent mode.
ReadWriteEditBash(cmd:*)
Cursor Model Selection
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
| Model |
Provider |
Best For |
Context |
| GPT-4o |
OpenAI |
General coding, fast responses |
128K |
| GPT-4o-mini |
OpenAI |
Simple tasks, cost-efficient |
128K |
| Claude Sonnet |
Anthropic |
Code quality, detailed explanations |
200K |
| Claude Haiku |
Anthropic |
Fast simple tasks |
200K |
| cursor-small |
Cursor |
Quick completions, simple edits |
8K |
| Auto |
Cursor |
Automatic model selection per query |
Varies |
Premium Models (count against fast request quota)
| Model |
Provider |
Best For |
Context |
| Claude Opus |
Anthropic |
Complex architecture, hard bugs |
200K |
| GPT-5 |
OpenAI |
Advanced reasoning, complex code |
128K+ |
| o1 / o3 |
OpenAI |
Deep reasoning, mathematical logic |
128K |
| Gemini 2.5 Pro |
Google |
Design, large context analysis |
1M |
Model Selection by Task
Quick Reference
Bug fix in one file → GPT-4o or Claude Sonnet
Multi-file refactoring → Claude Sonnet or Opus
Architecture planning → Claude Opus or GPT-5
Test generation → GPT-4o (fast + good patterns)
Complex algorithm design → o1/o3 reasoning models
Large codebase analysis → Gemini 2.5 Pro (1M context)
Simple autocomplete → cursor-small (automatic via Tab)
"I don't know" → Auto mode
How to Switch Models
Per conversation: Click the model name in the top-right of Chat or Composer panel.
Default model: Cursor Settings > Models > set default for Chat and Composer separately.
Auto mode: Select "Auto" as the model. Cursor picks the best model per query based on complexity and current server load.
Bring Your Own Key (BYOK)
Use your own API keys to bypass Cursor's quota system. You pay the provider directly at their rates.
Configuration
Cursor Settings > Models > enable Use own API
Work with multiple repositories in Cursor: multi-root workspaces, monorepo patterns, selective indexing, and cross-project context.
ReadWriteEditBash(cmd:*)
Cursor Multi-Repo
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
- Open first project:
File > Open Folder > select project A
- Add second project:
File > Add Folder to Workspace... > select project B
- 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
- Each folder root is indexed independently
@Codebase searches across all open roots@Files paths include the root name: @api-service/src/routes/users.ts- Closing a folder removes it from the index
Monorepo Patterns
Opening Full Monorepo
cursor /path/to/monorepo
Pros: @Codebase searches everything, cross-package references work naturally
Cons: Slow indexing on large monorepos, lots of irrelevant search results
Focused Opening (Recommended)
# Open just the package you're working on
cursor /path/to/monorepo/packages/api
Pros: Fast indexing, focused search results
Cons: No automatic cross-package context
Hybrid: Focused + Selective .cursorignore
# Open the monorepo root but exclude what you don't need
cursor /path/to/monorepo
# .cursorignore at monorepo root
# Only index packages you're actively working on
# Exclude everything in packages/
packages/*/
# Except the ones you want indexed:
!packages/api/
!packages/shared/
# Always exclude
node_modules/
dist/
build/
.turbo/
This indexes only packages/api/ and packages/shared/, keeping search focused.
Cross-Project Context
Referencing Files Across Roots
In a multi-root workspace, use the root folder name as prefix:
@api-service/src/types/user.ts @web-frontend/src
Optimize Cursor IDE performance: reduce memory usage, speed up indexing, tune AI features, and manage extensions for large codebases.
ReadWriteEditBash(cmd:*)
Cursor Performance Tuning
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 visual features for speed
"editor.minimap.enabled": false,
"editor.renderWhitespace": "none",
"editor.guides.bracketPairs": false,
"breadcrumbs.enabled": false,
"editor.occurrencesHighlight": "off",
"editor.matchBrackets": "never",
"editor.folding": false,
"editor.glyphMargin": false,
// Reduce file watching scope
"files.watcherExclude": {
"**/node_modules/**": true,
"**/.git/objects/**": true,
"**/.git/subtree-cache/**": true,
"**/dist/**": true,
"**/build/**": true,
"**/coverage/**": true,
"**/.next/**": true,
"**/target/**": true
},
// Exclude from search and explorer
"files.exclude": {
"**/node_modules": true,
"**/.git": true,
"**/dist": true,
"**/build": true
},
// Memory limits
"files.maxMemoryForLargeFilesMB": 4096,
// Reduce auto-save overhead
"files.autoSave": "onFocusChange",
// Limit search results
"search.maxResults": 5000
}
Disable Animations
{
"workbench.list.smoothScrolling": false,
"editor.smoothScrolling": false,
"editor.cursorSmoothCaretAnimation": "off",
"terminal.integrated.smoothScrolling": false
}
Extension Audit
Profile Running Extensions
Cmd+Shift+P > Developer: Show Running Extensions
This shows:
- Extension name
- Activation time (ms)
- Profile CPU time
Sort by activation t
Configure Cursor privacy mode, data handling, telemetry, and sensitive file exclusion.
ReadWriteEditBash(cmd:*)
Cursor Privacy Settings
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
| With Privacy Mode ON |
With Privacy Mode OFF |
| Zero data retention at model providers |
Providers may retain data per their policies |
| Code not used for training (Cursor or providers) |
Code may be used to improve AI models |
| Embeddings computed without storing source |
Same embedding behavior |
| Telemetry: anonymous usage only |
Telemetry may include code snippets |
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 cannot disable Privacy Mode
- Client pings server every 5 minutes to verify enforcement
- New members automatically have Privacy Mode enabled
Verifying Privacy Mode
Cursor Settings > General -- check Privacy Mode toggle- cursor.com/settings -- shows account-level status
- For teams: Admin Dashboard shows enforcement status per member
Data Flow: Where Your Code Goes
Your Code in Editor
│
├─► Tab Completion ──► Cursor's proprietary model server
│ (zero retention with Privacy Mode)
│
├─► Chat/Composer ──► Model provider (OpenAI/Anthropic/Google)
│ (zero retention agreements in place)
│
├─► Codebase Index ─► Cursor embedding API ─► Turbopuffer (vector DB)
│ (embeddings only, no plaintext code)
│
└─► BYOK ───────────► Your API provider directly
(your provider's data policy applies)
What IS Stored
| Data |
Stored Where |
Retention |
| Embeddings (vectors) |
Turbopuffer (cloud) |
Until project re-indexed |
| Obfuscated file metadata |
Cursor servers |
Active session only |
| Anonymous telemetry |
Cursor analytics |
Aggregated, no PII |
| Account info |
Cursor auth servers |
While account active |
What Is NOT Stored (Privacy Mode ON)
- Plaintext source code
- Chat prompts and responses
- File contents sent for completion
- Code snippets from
Production readiness checklist for Cursor IDE setup: security, rules, indexing, privacy, and team standards.
ReadWriteEditBash(cmd:*)
Cursor 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.]
Package manager: [npm/pnpm/yarn]
## Conventions
- [your team conventions here]
- Never commit console.log statements
- All functions require TypeScript return types
- Use Conventional Commits format
# .cursor/rules/security.mdc
---
description: "Security constraints for AI-generated code"
globs: ""
alwaysApply: true
---
# Security Rules
- NEVER hardcode API keys, passwords, or secrets in code
- NEVER disable HTTPS/TLS verification
- ALWAYS use parameterized queries (no string concatenation for SQL)
- ALWAYS validate and sanitize user input
- Use environment variables for all configuration values
Indexing Configuration
[ ] .cursorignore created at project root
[ ] Excluded: node_modules/, dist/, build/, .next/, vendor/
[ ] Excluded: *.min.js, *.map, *.lock, *.sqlite
[ ] Excluded: .env*, secrets/, credentials/
[ ] .cursorindexingignore created for large-but-useful files
[ ] Verified indexing completes (status bar shows "Indexed")
[ ] Tested @Codebase queries return relevant results
Privacy & Security
[ ] Privacy Mode: ON (Cursor Settings > General > Privacy Mode)
[ ] Verified: cursor.com/settings shows "Privacy Mode: Enabled"
[ ] .cursorignore covers all files with PII or regulated data
[ ] API keys (if BYOK) stored in Cursor settings, NOT in project files
[ ] Team members briefed: AI output is a draft, not production-ready code
AI Configuration
[ ] Default model set (Cursor Settings > Models)
[ ] BYOK configured if required by team (see cursor-api-key-management skill)
[ ] Auto mode evaluated vs fixed model selection
[ ] Tab completion enabled and test
Reference architecture for Cursor IDE projects: directory structure, rules organization, indexing strategy, and team configuration patterns.
ReadWriteEditBash(cmd:*)
Cursor Reference Architecture
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 types
│ ├── utils/ # Utility functions
│ └── components/ # UI components
├── tests/
├── prisma/
├── docs/ # Architecture docs (good for @Docs)
└── package.json
Why This Structure Helps Cursor
- Glob patterns work predictably:
src/api/*/.ts cleanly scopes API rules
- @Files references are intuitive:
@src/types/user.ts is discoverable
- Indexing is focused: clear separation of code vs build output vs data
- Rules inheritance: project-level always-on + directory-scoped rules
Rules Architecture
Layer 1: Always-On Global Rules
# .cursor/rules/project.mdc
---
description: "Core project context and conventions"
globs: ""
alwaysApply: true
---
# SaaS Dashboard Application
Stack: Next.js 15 (App Router), TypeScript 5.7, PostgreSQL 16, Prisma 6
Auth: NextAuth.js v5 with GitHub OAuth
Styling: Tailwind CSS 4
Testing: Vitest + Playwright
Package manager: pnpm
## Architecture Decisions
- Server Components by default, "use client" only when needed
- Repository pattern for database access
- Zod schemas for all external input validation
- Result types for error handling (never throw from services)
Layer 2: Security (Always-On)
# .cursor/rules/security.mdc
---
description: "Security constraints for all AI-generated code"
globs: ""
alwaysApply: true
---
# Security Requirements
- NEVER hardcode secrets, API keys, or passwords
- ALWAYS use parameterized queries (no string interpolation in SQL)
- ALWAYS validate
Configure Cursor project rules using .
ReadWriteEditBash(cmd:*)
Cursor Rules Config
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:
| Field |
Type |
Purpose |
description |
string |
Concise rule purpose (shown in Cursor UI) |
globs |
string |
Gitignore-style patterns for auto-attachment |
alwaysApply |
boolean |
true = always active; false = only when matching files referenced |
Rule Types by alwaysApply + globs Combination
| alwaysApply |
globs |
Behavior |
true |
empty |
Always injected into every prompt |
false |
set |
Auto-attached when matching files are in context |
false |
empty |
Manual only -- reference with @Cursor Rules in chat |
File Naming Convention
Use kebab-case with .mdc extension. Names should describe the rule's scope:
.cursor/rules/
typescript-standards.mdc
react-component-patterns.mdc
api-error-handling.mdc
testing-conventions.mdc
database-migrations.mdc
security-requirements.mdc
Create new rules via: Cmd+Shift+P > New Cursor Rule
Complete Project Rules Example
.cursor/rules/project-context.mdc (always-on):
---
description: "Core project context and conventions"
globs: ""
alwaysApply: true
---
# Project: E-Commerce Platform
Tech stack: Next.js 15, TypeScript 5.7, Prisma ORM, PostgreSQL, Tailwind CSS 4.
Package manager: pnpm. Monorepo with turborepo.
## Conventions
- API routes in `app/api/` using Route Handlers
- Server Components by default, `"use client"` only when needed
- Error boundaries at layout level
- All monetary values stored as integers (cents)
- Dates stored as UTC, displayed in user timezone
Configure SAML 2.
ReadWriteEditBash(cmd:*)
Cursor SSO Integration
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
- Okta Admin Console > Applications > Create App Integration
- Select SAML 2.0
- 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:
- Go to the app's "Sign On" tab
- Click "Identity Provider metadata" link
- Save the XML file
Step 4: Upload to Cursor
- Cursor Admin Dashboard > SSO
- Select "SAML 2.0"
- Upload the IdP metadata XML (or paste the metadata URL)
- Save configuration
Step 5: Test
- Open Cursor incognito
- Sign in with your
@company.com email
- Should redirect to Okta login
- After auth, return to Cursor authenticated
SSO Configuration: Microsoft Entra ID
Step 1: Register Enterprise Application
- Azure Portal > Entra ID > Enterprise applications > New application
- Create your own application > "Cursor IDE"
- Select "Integrate any other application you don't find in the gallery (Non-gallery)"
Step 2: Configure SAML
In the enterprise app > Single sign-on > SAML:
Basic SAML Configuration:
Identifier (Entity ID): https://cursor.com/api/auth/saml
Reply URL (ACS URL): https://cursor.com/api/auth/saml/callback
Sign-on URL: https://cursor.com
Attributes & Claims:
Unique User Identifier: user.mail
email: user.mail
name: user.displayname
Step 3: Download Federation Metadata XML
In Entra ID app > SAML Signing Certificate > Download "Federation Metadata XML"
Step 4: Upload to Cursor
Same as Okta Step 4: Admin Dashboard > SSO > Upload metadata.
SSO Configuration: Google Workspace
Step 1: Create SAML App
- Google Admin Console > Apps > Web and mobile apps > Add app > Add custom SAML app
- App name:
Master Cursor Tab autocomplete, ghost text, and AI code suggestions.
ReadWriteEditBash(cmd:*)
Cursor Tab Completion
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
- You type code in the editor
- Cursor's model predicts what comes next based on: current file, open tabs, recent edits, project rules
- Ghost text (gray text) appears inline
- 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
| Action |
macOS |
Windows/Linux |
| Accept full suggestion |
Tab |
Tab |
| Accept word-by-word |
Cmd+→ |
Ctrl+→ |
| Dismiss suggestion |
Esc |
Esc |
| Force trigger |
Ctrl+Space |
Ctrl+Space |
Word-by-word acceptance (Cmd+→) is powerful for partial suggestions. If the AI suggests a complete function but you only want the signature, accept word-by-word until you have what you need, then type your own body.
Tab Completion Settings
Access via Cursor Settings > Tab:
| Setting |
Purpose |
Recommendation |
| Tab Completion |
Master on/off toggle |
Keep enabled |
| Trigger in comments |
Generate comment text |
Disable for less noise |
| Accept suggestion keybinding |
Remap Tab to another key |
Default (Tab) works best |
| Suggestion delay |
Time before ghost text appears |
Lower = faster but more flicker |
Disabling Tab for Comments
If Tab suggestions in comments are distracting:
Cursor Settings > Tab Completion > uncheck Trigger in comments
Context That Improves Completions
Tab quality depends heavily on available context:
- Current file: The model reads the full file you are editing
- Open editor tabs: Files open in other tabs provide pattern context
- Recent edits: Changes you have made in the last few minutes
- Project rules:
.cursor/rules/*.mdc or .cursorrules content
- Codebase index: If indexed, the model uses semantic code search
Tips for Be
Set up Cursor for teams: plan selection, member management, shared rules, admin dashboard, and onboarding.
ReadWriteEditBash(cmd:*)
Cursor Team Setup
Configure Cursor for teams and organizations. Covers plan selection, member management, shared configurations, Privacy Mode enforcement, and onboarding workflows.
Plan Comparison
| Feature |
Pro ($20/user/mo) |
Business ($40/user/mo) |
Enterprise (custom) |
| Fast requests |
500/mo |
500/mo/seat |
Custom |
| Tab completion |
Unlimited |
Unlimited |
Unlimited |
| Privacy Mode |
Optional |
Enforced by default |
Enforced |
| SSO (SAML/OIDC) |
No |
Yes |
Yes |
| SCIM provisioning |
No |
No |
Yes |
| Admin dashboard |
No |
Yes |
Yes |
| Usage analytics |
No |
Yes |
Yes (advanced) |
| Priority support |
No |
No |
Yes |
| Dedicated account mgr |
No |
No |
Yes |
| SLA |
No |
No |
Yes |
| SOC 2 report access |
No |
Request |
Included |
Team Setup Workflow
Step 1: Create Organization
- Go to cursor.com/settings
- Click "Create Team" or "Create Organization"
- Enter organization name and billing details
- Select plan (Business or Enterprise)
Step 2: Configure Team Settings
Admin Dashboard (Business/Enterprise):
Dashboard Sections:
├── Members → Invite, remove, assign roles
├── Usage → Request counts, model usage, costs
├── Privacy → Privacy Mode enforcement
├── Models → Restrict available models
├── SSO → SAML/OIDC configuration
└── Billing → Plan, invoices, seat management
Step 3: Invite Members
Methods:
1. Email invitation: Admin dashboard > Members > Invite by email
2. Domain auto-join: Allow anyone with @company.com to join
3. SSO provisioning: Users auto-join when they sign in via SSO
4. SCIM (Enterprise): Automatic sync from identity provider
Roles:
| Role |
Permissions |
| Owner |
Full admin, billing, delete org |
| Admin |
Manage members, settings, SSO |
| Member |
Use Cursor with team settings |
Step 4: Enforce Privacy Mode
For Business and Enterprise plans:
- Admin Dashboard > Privacy
- Enable "Enforce Privacy Mode for all members"
- Team members cannot disable Privacy Mode locally
- Verification: each client pings server every 5 minutes to check enforcement
P
Upgrade Cursor versions, migrate from VS Code, and transfer settings between machines.
ReadWriteEditBash(cmd:*)
Cursor Upgrade & Migration
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:
- A notification appears: "A new version is available"
- Click "Restart to Update" or go to
Help > Check for Updates
- 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
[ ] Export extension list:
cursor --list-extensions > extensions-backup.txt
[ ] Commit any unsaved work to git
[ ] Note any custom keybindings (keybindings.json)
Post-Upgrade Verification
[ ] Cursor launches without errors
[ ] Sign-in still active (check top-right user icon)
[ ] AI features work: try Cmd+L, type a question
[ ] Tab completion works: type code, see ghost text
[ ] Extensions loaded: Cmd+Shift+X, verify list
[ ] Custom keybindings preserved: test your shortcuts
[ ] Project rules still load: @Cursor Rules in chat
[ ] Indexing status: check status bar
VS Code to Cursor Migration
Automatic Import (First Launch)
On first launch, Cursor detects VS Code and offers one-click import:
What migrates:
✅ settings.json (editor preferences)
✅ keybindings.json (custom shortcuts)
✅ User snippets
✅ Color themes
✅ Compatible extensions (from Open VSX Registry)
What does NOT migrate:
❌ Microsoft-exclusive extensions (Copilot, Live Share, Remote-SSH)
❌ Extension login states / databases
❌ Workspace trust settings
❌ Task configurations (.vscode/tasks.json -- copies but may need adjustment)
Manual Migration
If you skipped the auto-import:
# Copy settings (macOS example)
cp ~/Library/Application\ Support/Code/User/settings.json \
~/Library/Application\ Support/Cursor/User/settings.json
# Copy keybindings
cp ~/Library/Application\ Support/Code/User/keybindings.json \
~/Library/Application\ Support/Cursor/User/keybindings.json
# Copy snippets
cp -r ~/Library/Application\ Support/Code/User/snippets/ \
~/Library/Application\ Support/Cursor/User/snippets/
# Reinstall extensions (from backup list)
while read ext; do cursor --install-extension &quo
Track and analyze Cursor usage metrics via admin dashboard: requests, model usage, team productivity, and cost optimization.
ReadWriteEditBash(cmd:*)
Cursor Usage Analytics
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 623 requests (GPT-4o) │ │
│ │ carol@co.com 591 requests (Auto) │ │
│ └───────────────────────────────────────────────┘ │
│ │
└────────────────────────────────────────────────────────┘
Key Metrics
Request Metrics
| Metric |
What It Measures |
Target |
| Total requests |
All AI interactions (Chat, Composer, Inline Edit) |
Growing month-over-month |
| Fast requests |
Premium model uses (count against quota) |
Stay under monthly limit |
| Slow requests |
Queued requests after quota exceeded |
Minimize (upgrade if high) |
| Tab acceptances |
How often Tab suggestions are accepted |
30-50% acceptance rate is healthy |
User Adoption Metrics
| Metric |
Healthy |
Needs Attention |
| Weekly active users |
80%+ of seats |
Below 50% of seats |
| Requests per user/day |
5-20 |
Below 3 (underutilization) |
| Users with 0 requests (30d) |
0-10% of seats |
Above 20% (wasted seats) |
| Model diversity |
2-3 models used |
Single model only |
Cost Metrics
| Metric |
Calculation |
| Cost per seat |
Plan price / active users |
| Cost per request |
Total spend / total requests |
| BYOK costs |
Sum of API provider invoices |
Total AI
Ready to use cursor-pack?
|
|
|
