Free guide · Cursor

Getting started with Cursor

Level · Start here

From download to a first useful change: install on your OS, sign in, open a real project, learn the four ways to talk to Cursor, and — the part most guides skip — undo confidently when it does something you did not want.

Coming from VS Code or Copilot?

Cursor is a VS Code fork, so the editor is familiar. Import your old setup from Cursor Settings — but note extensions come from Open VSX, not the VS Code Marketplace — importing your setup.
The big difference from Copilot is Agent: it edits multiple files and runs terminal commands, rather than completing the line you are on — the four ways in.
It has four modes — Agent, Ask, Plan, Debug. Shift + Tab cycles them. Learning these early is the whole game — modes.
Checkpoints let you roll files back without touching git — undoing its work.

Never used an AI editor at all? Ignore the box and start below.

Never used an AI editor? Start here

What Cursor actually is

Cursor is a code editor built on top of VS Code, with an AI assistant wired deeply into it. If you have used VS Code, the editing, the file tree and most keyboard shortcuts are the same. What is new is that there is a model sitting alongside you that can read your project, suggest edits, and — if you let it — make them.

The mental shift that takes people a few days: this is not autocomplete with a bigger vocabulary. Cursor’s Agent can work across several files at once and run commands in your terminal. That is genuinely more useful and genuinely more capable of making a mess, which is why the section on undoing things is as important as the section on prompting.

Before anything else: work in a project with git initialised, and commit before you let an agent loose. Not because Cursor is reckless, but because “I can throw that away in one command” is what makes you willing to experiment — and experimenting is how you actually learn this.

Install and sign in

Download from cursor.com/download (the same destination the official quickstart links). Current documented baselines:

OS	Requirement	Installer
macOS	macOS 12 (Monterey) or later	Native `.dmg` — Apple Silicon and Intel
Windows	Windows 10 or later	Native `.exe`
Linux	Debian/Ubuntu apt, RHEL/Fedora yum/dnf, or AppImage	Prefer the apt/yum packages over AppImage — desktop icons, updates, and CLI tooling. Exact repo commands live on the official quickstart; they change less often than blog mirrors.

Install the build for your OS and open the app.
Sign in with a Cursor account (email or the SSO path your team uses).
You do not need to configure rules, MCP, or models before the first session. Get a project open first.

First run — explain, then one small change

Open a real project with File > Open Folder. Cursor works from the folder you have open — a single loose file gives it almost nothing to reason about. Prefer a repo with git already initialised.
Open the agent panel with Cmd + I on Mac or Ctrl + I on Windows and Linux. Paste the officially recommended orientation prompt:

Explain this codebase. Point me to the main entry points, key modules, and anything I should read before making changes.

That costs nothing, breaks nothing, and shows you immediately how much context it has. Then ask for a short menu of safe improvements and pick one:

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

Official guidance for that first edit: keep it low risk — copywriting or a small UI fix — then review the diff and run whatever checks your project already uses. Bigger work belongs in Plan mode once you are comfortable.

The detail

The four ways you interact with it

Surface	What it is for	How to open it
`Tab`	Autocomplete. Suggestions appear as grey text ahead of your cursor.	Just type. `Tab` accepts, `Escape` rejects.
`Inline edit`	A quick, in-place change to the code in front of you, without opening a conversation.	`Cmd + K` / `Ctrl + K`
`Agent`	The main event. Completes multi-step tasks, edits across files, runs terminal commands.	`Cmd + I` / `Ctrl + I`
`Agents Window`	A separate newer interface for working with agents, alongside the classic editor.	Its own window

Tab does more than finish your line — it can make multi-line and cross-file edits, and after accepting one you can press Tab again to jump to the next place it wants to edit. If you only want part of a suggestion, Cmd + → (or Ctrl + →) accepts it one word at a time.

Two naming traps, because older tutorials are full of them. “Composer” is no longer a panel you open — in current documentation it is the name of a model. And the Agents Window arrived with Cursor 3 in April 2026, so screenshots older than that will not match what you are looking at. If a tutorial tells you to “open Composer,” it predates the interface you have.

The four agent modes

This is the highest-value thing on this page for a beginner. Most early frustration comes from using the editing mode when you wanted the reading mode.

Mode	What it does
`Agent`	Builds, refactors and fixes. Edits your files.
`Ask`	Read-only. For understanding the codebase without any edits being made.
`Plan`	Writes a detailed implementation plan first, and only edits after you approve it.
`Debug`	For hard-to-reproduce bugs: forms a hypothesis, adds instrumentation, reproduces, analyses, fixes.

Cycle between them with Shift + Tab, or pick from the mode dropdown. Two habits worth forming immediately: use Ask whenever you are exploring rather than changing something, and use Plan for anything touching more than one file. Cursor’s own quickstart recommends exactly that once you are comfortable, and it is the difference between reviewing a plan you understand and reviewing a diff you do not.

Giving it the right context

The single biggest lever on output quality is what the model can see. Type @ in the input to attach something specific:

Files and folders — @auth.ts, @src/components/. Type / after a folder to go deeper.
@Terminals — your terminal output, which saves pasting a stack trace.
@Chats — an earlier conversation.
@Commit (Diff of Working State) and @Branch (Diff with Main) — excellent for “review what I just did.”
@Browser — browser context.

Note for anyone following an older tutorial: @Docs is not in the current list, and web search is not an @ mention either — it is a built-in agent tool that generates search queries and searches the web when it needs to.

Reviewing and undoing its work

Everything an agent changes appears in a diff view. Read it. The failure mode for new users is not the agent making a bad edit — it is accepting fifteen good-looking edits without reading any of them, then having no idea which one broke the build.

When you do need to go back, the feature is Checkpoints. Cursor creates one automatically before making significant changes. Click a checkpoint in the chat timeline to preview it, then Restore Checkpoint to revert.

Two properties of checkpoints worth memorising. They restore files only — your conversation stays intact, so you can roll back the code and keep discussing what went wrong. And they are stored locally, entirely separate from git. They are an undo button, not a backup, and not a substitute for committing.

Importing your VS Code setup

Open Cursor Settings with Cmd + Shift + J or Ctrl + Shift + J, then General > Account, then VS Code Import. It brings across extensions, themes, settings and keybindings.

One caveat that catches people: Cursor uses the Open VSX registry rather than the VS Code Marketplace. Most things are there; some proprietary Microsoft extensions are not. If a favourite extension fails to appear, that is why, and it is not something you have misconfigured.

A sensible first week

Day one — read, don’t write. Use Ask on a codebase you already know. You will calibrate quickly on where it is reliable and where it confidently invents things.
Then one small, low-risk change. Copywriting, a minor UI fix. Review the diff properly and run whatever checks your project already has. This is the officially recommended on-ramp and it is genuinely the right size of first task.
Add Tab to your muscle memory. It is the feature you will use a thousand times a day, and the one that needs no trust.
Move to Plan for real work. Anything spanning multiple files. Read the plan, correct it, then let it run.
Only then write rules. Once you have caught yourself giving the same correction twice, that correction belongs in a rule rather than in your next message.

Beginner mistakes worth skipping

Working without commits. Checkpoints are local and not a backup. Commit before anything ambitious.
Vague prompts with no context. “Fix the bug” with nothing attached makes the model guess. Attach the file and the terminal output.
Using Agent for questions. If you only want to understand something, Ask cannot accidentally edit your code.
Accepting diffs unread. The reviewing is the job now.
Following stale tutorials. Cursor renames things — “Composer” as a panel and @Docs are both gone. If instructions do not match your screen, suspect the tutorial’s age before your own competence.

A note on the shortcuts above: Cursor’s documentation publishes some of them only for Mac — including “add selection to chat” and the accept-all and reject-all actions. Rather than guess at the Windows and Linux equivalents, open the keyboard shortcuts settings with Cmd R then Cmd S (or Ctrl R then Ctrl S) and read the current bindings for your machine. You can remap them there too.

What to read next

When you are ready to make your setup durable — where configuration lives, and how to keep it through updates — read Cursor setup that survives updates. When you start writing rules, go to the rules guide. If you use Claude Code as well, start with Getting started with Claude Code, then Using Claude with Cursor for which tool owns what. Grok Bot is a different product again — named teammates on a persistent cloud computer, not the Grok model in the picker — see Grok Bot: info, FAQ, and examples.