Cursor Setup & Configuration

You installed Cursor, opened a project, typed a prompt, and got mediocre suggestions. You tried agent mode, it asked permission for every terminal command, and you gave up after the fifth confirmation dialog. The AI feels slow, the suggestions feel generic, and you are wondering what all the hype is about. The problem is not Cursor. The problem is that Cursor out of the box is configured for maximum safety, not maximum productivity. These 15 tips fix that.

What You Will Walk Away With

• A Cursor installation that imports your existing VS Code workflow without losing a single keybinding
• Auto-Run configured with a safe Command Allowlist that lets the agent run tests and builds without asking
• Model selection tuned for the right cost-quality tradeoff across different task types
• Project rules that make AI-generated code match your team’s conventions on the first attempt
• Indexing and performance settings that keep Cursor responsive on large codebases

Installation and Migration

Tip 1: Install via Package Manager for Painless Updates

Do not download the .dmg or .exe from the website. Use a package manager so updates are a single command instead of a manual download-and-replace cycle.

macOS

brew install --cask cursor
# Updates: brew upgrade --cask cursor

Windows

winget install Anysphere.Cursor
# Updates: winget upgrade Anysphere.Cursor

Linux

# Download AppImage from cursor.com
chmod +x Cursor-*.AppImage
# For Ubuntu/Debian, FUSE is required:
sudo apt install libfuse2

Tip 2: Import VS Code Settings in One Step

Cursor is a VS Code fork, which means your extensions, keybindings, settings, and snippets transfer directly. On first launch, Cursor offers an import wizard. If you missed it:

1. Open Command Palette: Cmd+Shift+P (macOS) or Ctrl+Shift+P (Windows/Linux)
2. Type “Import VS Code Settings”
3. Select all categories (extensions, keybindings, settings, snippets)
4. Restart Cursor

Your muscle memory stays intact. The only new shortcuts you need to learn are Tab (accept suggestion), Cmd+K (inline edit), and Cmd+I (agent panel).

Tip 3: Install the cursor Shell Command

Without this, you cannot open projects from the terminal — and terminal-driven workflows are a huge part of using Cursor effectively.

# From Command Palette (Cmd+Shift+P):
# "Install 'cursor' command in PATH"

# Now you can:
cursor .                    # Open current directory
cursor src/api/routes.ts    # Open specific file
cursor -g src/app.ts:42     # Jump to line 42
cursor --diff file1 file2   # Compare two files
cursor -a ../shared-lib     # Add folder to current workspace

Quick project switching from terminal

# Add to ~/.zshrc or ~/.bashrc for instant project switching:
alias c="cursor"
alias cn="cursor -n"  # Force new window
alias cr="cursor -r"  # Reuse current window

Unlock Autonomous Workflows

Tip 4: Understand Why Auto-Run Changes Everything

By default, Cursor’s agent asks for permission before running any terminal command. This makes sense for safety, but it destroys the autonomous workflow that makes agent mode powerful. Every npm test, every tsc, every mkdir triggers a confirmation dialog. You end up babysitting the agent instead of letting it work.

Auto-Run (the feature the community still calls “YOLO mode”) removes these interruptions for commands you trust. The agent can now write code, run tests, see failures, fix the code, and re-run tests — all without you clicking “Allow.”

Tip 5: Configure Auto-Run with a Safe Command Allowlist

Go to Settings -> Cursor Settings -> Agents -> Auto-Run. You get three Auto-Run Modes:

• Run in Sandbox (macOS/Linux): commands auto-run inside a sandbox that limits filesystem and network access. This is the safest middle-ground default — the agent stays unblocked, but a bad command cannot touch the rest of your machine.
• Ask Every Time: every tool and command requires approval. This is the default and the slow one.
• Run Everything: the agent runs all tools and commands without asking. Pair this with a tight Command Allowlist and the protection toggles below.

Then shape the boundaries with the Command Allowlist (commands that run automatically outside the sandbox). Add the commands you trust:

Auto-Run Command Allowlist starter set

vitest, jest, pytest, npm test, pnpm test, npm run build, pnpm build, tsc, eslint, prettier, biome, mkdir, touch, cp, git status, git diff

Leave destructive and irreversible commands off the allowlist so they always require approval: rm -rf, sudo, git push, git commit, npm publish, and any deploy script. Cursor also exposes File-Deletion Protection, Dotfile Protection, and External-File Protection toggles on the same screen — keep them on so the agent cannot delete files or edit .gitignore/files outside the workspace without asking.

This gives you an agent that can iterate on code autonomously while keeping destructive operations gated behind manual approval.

Tip 6: Set Up Multi-Root Workspaces for Full-Stack Projects

If your project spans multiple repositories (frontend, backend, shared types), open them as a single workspace so the agent can edit across all of them.

// myproject.code-workspace
{
  "folders": [
    { "path": "frontend", "name": "Frontend (Next.js)" },
    { "path": "backend", "name": "Backend (Express)" },
    { "path": "shared", "name": "Shared Types" }
  ]
}

Open it with cursor myproject.code-workspace. Now when you tell the agent “add a new API endpoint and update the frontend to call it,” it can edit files in both repos within a single conversation.

Model Selection

Tip 7: Pick the Right Model for the Right Task

Cursor lets you switch models per conversation. Use this strategically instead of defaulting to the most expensive option.

Task Type	Recommended Model	Why
Hardest refactors, building from scratch, long-running tasks	Claude Fable 5	Anthropic’s highest-capability model; exceeds Opus 4.8 on complex multi-file work ($10/$50 per 1M tokens — see model comparison)
Complex architecture, difficult bugs	Claude Opus 4.8	Strong agentic reasoning, good accuracy on multi-step tasks at half the cost of Fable 5
Everyday coding, feature implementation	Claude Sonnet 4.6	Strong performance at lower cost, fast responses
Large context analysis (10k+ lines)	Gemini 3.1 Pro	1M-token context window
Quick iterations, simple edits	GPT-5.5	Fast responses, good for rapid prototyping

Switch models mid-session using the model picker in the bottom-left of the agent panel.

Tip 8: Use Max Mode Only When Context Demands It

Max Mode gives you extended context windows but burns through your quota faster. Enable it manually (not auto) and use it for:

• Analyzing files over 5,000 lines
• Cross-repository refactoring where the agent needs to hold multiple large files in context
• Understanding complex dependency chains across a monorepo

For everything else, standard context is sufficient and significantly cheaper.

Project Rules

Tip 9: Create a Project Rule (or AGENTS.md) for Every Project

This is the single highest-ROI configuration you can make. A rule that tells the AI your tech stack, conventions, and constraints stops it from guessing — and guessing wrong often enough to be annoying. Cursor’s current mechanism is Project Rules in .cursor/rules/*.mdc. For a single, simple set of instructions, a plain AGENTS.md in your project root is the lighter alternative.

Create .cursor/rules/project.mdc with alwaysApply: true so it loads in every session:

Copy-paste .cursor/rules/project.mdc for a TypeScript web project

---
description: Project-wide stack and conventions
alwaysApply: true
---

This project is a TypeScript web application using Next.js App Router with React Server Components.

Tech stack:
- Next.js 15 with App Router
- TypeScript in strict mode
- Tailwind CSS for styling
- Drizzle ORM with PostgreSQL
- Vitest for testing
- pnpm as package manager

Code conventions:
- Use named exports, not default exports
- Prefer functional components with hooks
- Use server components by default, add "use client" only when client state is needed
- Error handling: always use try-catch for async operations with typed error responses
- Use zod for all input validation

When running commands, use pnpm instead of npm.
When searching the codebase, do at least 3 semantic searches and 3 grep searches.
Do not modify package.json dependencies directly -- ask first.

`.cursorrules` is legacy

The old root .cursorrules file still works, but Cursor’s docs explicitly mark it as legacy and state it “will be deprecated.” If you have one, migrate its contents into a .cursor/rules/*.mdc rule (or AGENTS.md) — do not start a new project on it.

Tip 10: Split Rules into Focused Files for Larger Projects

For projects with more than a few conventions, split your rules into focused .mdc files instead of one giant rule:

mkdir -p .cursor/rules

Create separate files for different concerns:

• .cursor/rules/architecture.mdc — Layer boundaries, dependency rules, file organization
• .cursor/rules/testing.mdc — Test framework, coverage expectations, test file conventions
• .cursor/rules/api-conventions.mdc — Request/response patterns, error formats, auth requirements
• .cursor/rules/styling.mdc — Component patterns, CSS conventions, accessibility requirements

Keep each rule under ~500 lines and reference canonical files (@service-template.ts) rather than pasting code, so rules stay short and do not go stale.

Tip 11: Auto-Attach Rules with globs Frontmatter

To apply a rule automatically when you touch matching files, set the rule type to “Apply to Specific Files” — which writes a globs list into the rule’s frontmatter. There is no config.json; the file-matching lives inside each .mdc rule. The AI then gets different instructions when editing test files versus component files versus API routes:

---
description: Testing conventions
globs:
  - "**/*.test.ts"
  - "**/*.test.tsx"
alwaysApply: false
---

- Use vitest with descriptive test names
- Cover happy path, edge cases, and error cases
- Mock external services, never hit the network in unit tests

When a file matching those globs is in scope, Cursor attaches this rule automatically. Write globs as a YAML list as shown — brace-expansion shorthand like **/*.test.{ts,tsx} can fail to match silently, so list each pattern on its own line.

Indexing and Performance

Tip 12: Configure File Exclusions Before First Index

Cursor indexes your codebase for semantic search. Without exclusions, it wastes time and memory indexing node_modules, build artifacts, and generated files.

Add to your workspace settings:

{
  "search.exclude": {
    "**/node_modules": true,
    "**/dist": true,
    "**/build": true,
    "**/.next": true,
    "**/coverage": true,
    "**/*.min.js": true,
    "**/package-lock.json": true,
    "**/pnpm-lock.yaml": true
  }
}

Tip 13: Prioritize Core Source Files for Indexing

Tell Cursor which files matter most by structuring your workspace so source code is prominent. If you have a monorepo, open the specific packages you are working on rather than the root:

# Instead of this:
cursor ~/projects/big-monorepo

# Do this:
cursor ~/projects/big-monorepo/packages/web ~/projects/big-monorepo/packages/api

Check indexing status in Settings > Indexing and Docs. A healthy project indexes in 1-5 minutes. If it takes longer than 15, your exclusions are too loose.

Tip 14: Enable Privacy Mode for Proprietary Code

If you work on code that cannot leave your machine, enable Privacy Mode before opening the project:

Settings > Privacy > Enable Privacy Mode

With Privacy Mode on:

• No code is stored or used for model training
• Processing happens in real-time without retention
• Logs are not sent to Cursor’s servers

This is a hard requirement for many enterprise teams and should be configured before any proprietary code is opened.

Tip 15: Set Global User Rules for Personal Preferences

Global User Rules apply across all projects. Use them for personal preferences that are not project-specific:

Settings > Cursor Settings > Rules > User Rules

Copy-paste global user rules

Prefer functional code over imperative where possible.
Use async/await instead of .then() chains.
When writing TypeScript, use strict types -- avoid 'any'.
For network requests, use fetch instead of axios.
Always handle errors explicitly, never silently swallow them.
When I ask you to fix something, explain what was wrong before showing the fix.

These rules sit at IDE level and vary per developer, so they should not replace project-level rules for team conventions. Think of them as your personal coding preferences that apply regardless of which project you open.

When This Breaks

Auto-Run executes a destructive command: This is why you keep destructive commands off the allowlist (and Run Everything paired with the protection toggles). If you accidentally approve something dangerous, use Cmd+Z in the terminal or git checkout . to restore files. For extra safety, prefer Run in Sandbox and always commit before starting a large agent session.

Indexing is stuck or extremely slow: Usually caused by a missing exclusion pattern. Check if Cursor is trying to index node_modules, large binary files, or generated code. Clear the index cache via Settings > Advanced > Clear Index Cache and re-index with proper exclusions.

AI ignores your rules: A Project Rule only auto-applies if its type is set correctly — alwaysApply: true for every session, or a matching globs list for “Apply to Specific Files.” Check that the .mdc file lives in .cursor/rules/, is not empty, and has valid frontmatter. Also verify you are in Agent mode — Ask mode sometimes ignores project rules. (If you are still on a legacy .cursorrules file, migrate it to .cursor/rules/.)

Model responses are slow or timing out: Switch to a faster model (Sonnet 4.6 instead of Opus 4.8) for routine tasks. If all models are slow, check your network connection and Cursor’s status page.

What is Next

With your environment properly configured, move to Core Features (Tips 16-30) to learn the shortcuts and navigation patterns that make daily coding faster. The setup you just completed is the foundation that makes every subsequent tip more effective.