Cursor Setup

Requirements

• macOS 12 or later, Windows 10 or later, or a supported Linux package/AppImage.
• Git and the project's language toolchain installed on the machine.
• A Cursor account for AI features.
• A repository small enough to verify indexing and review one first change before broader delegation.

Quick setup

Install, verify, and open a project

https://cursor.com/download

cd path/to/your-project
cursor .

Explain this codebase's entry points, key modules, and test commands. Do not edit files.

Step 1

Install the desktop build for your platform

Cursor publishes native macOS and Windows installers plus deb, RPM, and AppImage builds for Linux. Use the current download page instead of copying a version-specific file URL.

1. On macOS, choose Apple Silicon, Intel, or Universal for the machine you use.
2. On Windows, choose x64 or ARM64 and a User install unless your organization requires a System install.
3. On Linux, prefer the deb or RPM package when supported because those builds integrate updates and CLI tools.

Step 2

Sign in and import only the settings you need

Cursor is based on the VS Code work surface, but importing every extension and setting can also import conflicts and unnecessary context.

1. Sign in to enable AI features.
2. Import the VS Code profile if you already rely on its keybindings, themes, and extensions.
3. Disable duplicate AI extensions and verify the integrated terminal uses the expected shell.
4. Install the `cursor` shell command before relying on `cursor .` from a terminal.

Step 3

Open the repository and verify indexing

Indexing starts when a project opens. Do not judge context quality or add large manual context until the initial index has completed.

1. Open the repository root rather than one nested source folder.
2. Check indexing status in Cursor settings if the agent cannot find known files.
3. Review .gitignore and Cursor ignore rules for directories that should or should not be indexed.
4. Ask for entry points and test commands, then compare the answer with the repository itself.

Step 4

Add rules for repository-specific knowledge

Rules are most useful for facts a new collaborator would need: commands, architecture, conventions, and boundaries.

1. Document the real package manager and validation commands.
2. Use file globs only when a rule genuinely applies to those files.
3. Point to an existing implementation when new code should follow a repository pattern.
4. Keep rules short enough that contradictions are visible during review.

Step 5

Make one small change and review the diff

Cursor's current quickstart recommends understanding the repository first, choosing a low-risk edit, then reviewing the generated diff and running project checks.

1. Choose a task that does not touch authentication, payments, migrations, or production secrets.
2. Inspect every hunk in the diff view.
3. Run tests, type checking, linting, or a local build appropriate to the change.
4. Use Plan Mode for larger multi-file work and approve the plan before implementation.

Suggest three small, safe improvements. Explain the tradeoffs and wait for me to choose one.

Step 6

Review privacy before adding MCP or cloud agents

Indexing, external tools, and cloud execution expand the data and systems involved in a task. Configure them deliberately after the local editor workflow is sound.

1. Choose the Cursor privacy setting appropriate for the repository and organization.
2. Do not place secrets in rules, prompts, or committed MCP configuration.
3. Add one MCP server at a time and verify its visible tools and access scope.
4. Keep production credentials out of the first setup and test with non-sensitive data.

Common setup errors