Cursor setup — install, .cursorrules, MCP, and how to split work with Claude Code

Cursor is a VS Code fork with deep AI integration — currently the fastest path to "I use AI inside my editor as a daily tool". It overlaps with Claude Code but they're complementary: Cursor is an in-editor pair programmer, Claude Code is a terminal-side agent. The point isn't to pick one; it's to split work between them.

This guide is macOS/Linux/Windows-agnostic: install → core use → .cursorrules → MCP → split with Claude Code.

TL;DR

1. Install: cursor.com → auto-imports VS Code extensions/keymap/settings
2. Model: Claude Sonnet/Opus · GPT-4.1 · Cursor Composer. Default recommendation: Claude Sonnet
3. Four shortcuts: Tab autocomplete · ⌘K inline edit · ⌘L side chat · ⌘I Composer
4. .cursorrules: project rules injected as a system prompt on every call
5. Split with Claude Code: Cursor = edits + instant feedback; Claude Code = multi-file + autonomous + CLI

Prerequisites

• macOS 12+ / Windows 10+ / Linux (Ubuntu 22.04+)
• Internet + an account (Cursor or GitHub OAuth)
• VS Code users: the import is automatic

1. Install

macOS

brew install --cask cursor

Windows

winget install -e --id Anysphere.Cursor

Linux

cursor.com/downloads for AppImage or .deb.

On first run, Cursor imports your VS Code extensions, keymap, and theme in one click. New users can keep accepting defaults.

2. Pick a model

Cursor → Settings → Models. Recommendations:

• Claude Sonnet 4 — daily editing and refactoring. Fast.
• Claude Opus 4 — hard debugging and architecture. Slower / pricier, more accurate.
• Composer (Cursor's own) — multi-file, agentic. Beta territory.
• GPT-4.1 / o1 — useful for fallback / comparison.

Cursor Pro has per-model request quotas. Sonnet has a generous limit and is fast — make it your default; reach for Opus only when stuck.

3. Four shortcuts to learn

Tab autocomplete

• Fills signatures, repeats patterns, auto-imports
• Don't trust blindly — hallucinated APIs are common. Press Esc to reject often.
• Setting: Features → Cursor Tab → "Disable preview" reduces noise.

⌘K inline edit

// selection: entire function
// ⌘K: "add error handling and zod input validation"

Changes only the selection. Not for big jobs. Fastest "intent → result" loop.

⌘L side chat

• @filename to attach a specific file
• @Codebase to search across the repo (embedding-based, beta quality)
• @Web for fresh info (Cursor performs the search)

⌘I Composer

Multi-file work ("refactor the entire auth flow"). With agent mode it edits files directly. Don't accept the whole result at once — review diff by diff.

4. .cursorrules — project rules

A .cursorrules file at the repo root is auto-injected as a system prompt on every chat, edit, or Composer call. Spell out code style, stack, and prohibitions once, and you'll stop re-typing them.

4.1 Template

For Next.js + TypeScript projects:

# Mac/Linux
curl -fsSL https://devalice.jaceclub.com/assets/ai-agents/cursor-setup/cursorrules-nextjs.txt -o .cursorrules
shasum -a 256 .cursorrules
# expected: 7f1ef76397375cae008ece09b46ddf91aa098dff5edaacebcd7e7e4dec92a21d

# Windows
Invoke-WebRequest -Uri https://devalice.jaceclub.com/assets/ai-agents/cursor-setup/cursorrules-nextjs.txt -OutFile .cursorrules

4.2 Key sections (in the template)

• Project context — stack · package manager · language versions
• Code style — strict TS · file-name conventions · path aliases
• Routing/data — App Router patterns · ISR · env separation
• Security — no secrets · input validation · SQL bindings
• Scope — no refactoring outside the request
• Output format — diff style · one alternative with tradeoffs

4.3 What it changes

Without vs with .cursorrules:

❌ "make me a React component here" → class component, JS, random extra deps ✅ "make me a React component here" → strict TS Server Component, @/* alias, Tailwind

A good rules file removes 3–4 lines of context-setting from every prompt.

5. .cursorignore

Same syntax as .gitignore. Marks files the AI should not pull into context.

# deps / build
node_modules
.next
dist

# huge fixtures
fixtures/large/

# generated code
src/generated/

Skipping this lets @Codebase search drag build outputs into results — quality drops.

6. MCP (Model Context Protocol)

Cursor 0.42+ supports MCP. Same standard as Claude Code, so server definitions are portable.

Settings → Features → MCP → Add Server:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/me/projects"]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": { "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_..." }
    }
  }
}

7. Privacy mode

Settings → General → Privacy Mode:

• OFF (default) — Cursor may use logs/requests to improve models
• ON — no learning use. Mandatory for company code.

With Privacy ON some features (indexing) stay local-only. Performance impact is small.

8. Splitting work with Claude Code

Strongest setup: use both. Roles:

Practical patterns

1. Small edit → Cursor ⌘K — change fits in one function. Accept right away.

2. Multi-file → Claude Code — "add ISR to four routes". Run the change and the build verification from the CLI.

3. Debugging → both — Cursor for quick hypotheses; Claude Code when you need deeper context and autonomous execution.

4. PR creation → Claude Code — automate through gh pr create.

5. Review → Cursor ⌘L — read diffs inline and ask one line at a time.

Verification

1. Open Cursor on an empty index.tsx and let Tab propose a React component skeleton
2. Select a function → ⌘K "add error handling" → see try/catch added
3. ⌘L side chat with @package.json attached → ask a dependency question
4. Drop .cursorrules at repo root → new chat → behavior shifts according to rules
5. Settings → Privacy → ON → confirm normal operation

Troubleshooting

Tab autocomplete is too noisy

Settings → Features → Cursor Tab → "Trigger more accurately", or temporarily disable. If you reject often, just turn it off.

@Codebase results are off

Add build outputs and generated code to .cursorignore. Trigger a codebase re-index (Settings → Indexing).

Cursor's own model hallucinates often

Force Claude Sonnet as default. Settings → Models → Default Model = Claude Sonnet.

.cursorrules seems to be ignored

• File name is exact: .cursorrules, leading dot, no extension
• Must be at repo root (not in a subfolder)
• Verify in a new chat (existing chats accumulate context and may mask changes)

Pro quota burns fast

You're overusing Composer. Use ⌘K for small edits; reserve Composer for real multi-file work.

Keymap conflict with Claude Code

Cursor is in the IDE, Claude Code is in a terminal — physical collisions are rare, but both use ⌘L in some setups. Remap one side.

References

• Claude Code setup — terminal agent setup goes well with Cursor
• Multi-agent workflow — combining several tools
• Cursor docs
• Cursor MCP guide

Changelog

• 2026-05-12 — Initial English translation (devAlice M2 i18n seed)