Sign in with Google

How to Use Cursor, the AI Code Editor

Three interaction modes, the context skill underneath them, and how to review an agent's work.

intermediate10 min read
ai-toolscursorcode-editorai-codingdeveloper-tools
Cursor gets installed, the agent gets asked to "add authentication," and four minutes later there are eleven changed files, a new dependency, and a test suite that no longer runs. The tool is genuinely good. What makes it hazardous is the asymmetry: asking for too much costs you nothing, and reviewing what comes back costs you everything. This guide covers the three ways to ask Cursor for an edit, how to feed it the right context, and the habits that stop an agent from quietly wrecking your repository.
iWhat you need
macOS 12 or later, Windows 10 or later, or a Linux machine; about a gigabyte of disk; and a Cursor account. The free Hobby tier includes a limited number of Agent requests, which is enough to learn on. Paid tier names and limits shift regularly, so check Cursor's pricing page rather than trusting a figure quoted elsewhere. Existing VS Code familiarity helps enormously, for reasons the next section explains.
Cursor is not an AI plugin bolted onto an editor. It is a fork of VS Code with AI built into the editing surface itself, and that has two consequences worth understanding before you install anything. First, nothing you already know is wasted — the Command Palette, the Explorer, the integrated terminal, your extensions, your keybindings, your settings.json all work, because it is the same editor underneath. Second, because the AI reaches into your buffers rather than sitting beside them, its output arrives as changes to your files instead of text you copy out of a chat window. That is simultaneously the entire value and the entire risk.
Download from cursor.com, which detects your platform. The migration step in the middle of this list is the one people skip and then regret.
  1. 1macOS ships a .dmg covering both Apple Silicon and Intel. Windows ships an .exe. Linux offers apt and dnf packages plus an AppImage.
  2. 2On Linux, prefer the apt or dnf package over the AppImage — the packaged builds give you a desktop icon, automatic updates, and the CLI tools.
  3. 3Run the first-launch onboarding. It offers to import your VS Code extensions, settings, themes, and keybindings in a single step. Take it.
  4. 4Open a real project rather than a scratch file. Cursor indexes the codebase, and every feature after this point is worse without that index.
  5. 5Confirm the import landed: your theme should look familiar and your usual keybindings should fire.
✓Keep VS Code installed
Cursor moves fast, and occasionally an extension you depend on lags behind the fork. Having the original one click away turns a blocked afternoon into a five-second workaround.
Cursor gives you three interaction modes and they are not interchangeable. Reaching for the wrong one is the most common reason people find the tool frustrating rather than fast.

Match the mode to the size of the change

  1. 1Tab, for edits you are already in the middle of. Tab is Cursor's autocomplete, drawing on your recent edits, the surrounding code, and current linter errors. It proposes multi-line changes, and after you accept one it can jump your cursor to the next place needing the same edit. Tab accepts, Escape rejects, and Cmd+Right Arrow on macOS or Ctrl+Right Arrow elsewhere takes one word at a time.
  2. 2Inline edit, for "change this selection." Select code, press Cmd+K, describe the change in a sentence. The diff appears in place and stays scoped to what you highlighted. This is the safest mode and by a wide margin the most underused.
  3. 3The agent, for work that genuinely spans files. Cmd+I or Cmd+L toggles the side panel, Cmd+T opens a new chat tab, Cmd+E toggles the agent layout. It searches the codebase, edits multiple files, runs terminal commands, and can drive a browser.
  4. 4Plan mode, when you are not confident the agent understands the task. Press Shift+Tab from the chat input to rotate into it, or use the mode picker. It asks clarifying questions and researches your codebase before writing anything — and reading a plan is far cheaper than reading a diff.
!The reflex worth resisting
Reaching for the agent by default is what turns a two-minute change into a twenty-minute review. If the edit lives inside one function, inline edit does it faster and hands you a diff you can actually hold in your head.
Output quality reduces almost entirely to what the model could see. Cursor will go looking on its own if you say nothing, and it is decent at that — but explicitly handing it the right three files beats letting it guess, every single time. You do that with @-mentions in the chat input.

The mentions that earn their keep

  1. 1@ followed by a filename or folder path, like @auth.ts or @src/components/, pulls those straight into context. You will use this one constantly.
  2. 2@Docs searches indexed documentation, including custom sources you add — the fix for a library whose API is newer than the model's training data.
  3. 3@Terminals attaches terminal output, which is how you hand over a stack trace or a failing test run without copy-pasting anything.
  4. 4@Commit (Diff of Working State) supplies your uncommitted changes, and @Branch (Diff with Main) compares against your main branch. Both are excellent for "review what I just wrote."
  5. 5@Past Chats references an earlier conversation, so you stop re-explaining your architecture every session.
  6. 6@Browser attaches context from Cursor's built-in browser.
The failure pattern is asking a vague question with nothing attached and then blaming the model for a vague answer. "Why is login broken?" on its own is an invitation to guess. The same question with @auth.ts, @Terminals carrying the real error, and one sentence about what you expected instead usually resolves on the first try.
Cursor cannot honor standards you never wrote down. Project rules solve that: they live in .cursor/rules as .mdc files, they are version-controlled alongside your code, and they get pulled into requests automatically. Each carries frontmatter — description explains the rule's purpose, globs attaches it to matching paths, and alwaysApply forces it into every request regardless of what you are editing.
markdown
---
description: "Conventions for FastAPI route handlers"
globs: app/routes/**/*.py
alwaysApply: false
---

- Every route is `async def` and takes an injected session dependency
- Request and response models are Pydantic classes defined in the same file
- Never query the database from a route — call the service layer
- Raise HTTPException with an explicit status code; never return a bare error dict

.cursor/rules/api-conventions.mdc

!Frontmatter is not optional
A plain .md file dropped into .cursor/rules is ignored, because the rules system keys off the frontmatter. If a rule appears to do nothing, check the file extension and the frontmatter before rewriting the rule itself.
This is where people get hurt. An agent run touching nine files produces a diff nobody reads past file three, and the moment you accept it you own code you have never seen. Cursor gives you two independent safety nets, and they cover different failures, so use both.
  1. 1Checkpoints. The agent automatically snapshots every modified file before significant changes. Click any checkpoint in the chat timeline to preview that state and restore it. Checkpoints are stored locally and are entirely separate from Git.
  2. 2Git. Commit before every agent run, without exception. Checkpoints undo the agent; Git is the permanent record, and it is what survives a crash, a bad restore, or a week away from the project.
  3. 3Read the diff file by file rather than as one blob. If it is too long to read, the request was too large — restore the checkpoint and ask for a third of it.
  4. 4Hunt specifically for changes you did not request: an added dependency, a reformatted file, a deleted test, a loosened type. Those are the ones that cost you a day next month.
✗The 400-line diff you did not read
If you cannot describe what a diff does, you have not gained a feature. You have merged an unreviewed pull request from a stranger straight into your main branch. Restore the checkpoint and ask for something smaller.
Cursor lets you choose which model handles a request, and the picker is not decoration. Composer is Cursor's own model and is what the free Hobby tier runs on; paid tiers add access to third-party frontier models along with higher agent limits, and the team plans layer on pooled administration and agentic code review. Names and quotas move around, so treat the pricing page as the authority and build habits that are cheap under any of them.

Spending sensibly

  1. 1Use a fast, cheap model for mechanical work: renames, boilerplate, test scaffolding, mechanical refactors.
  2. 2Save the strongest model for tasks where being wrong is expensive — architecture decisions, tricky concurrency, anything touching money or authentication.
  3. 3Scope requests tightly. A vague request burns the same quota as a precise one and gives you less back.
  4. 4Check your usage in Cursor's settings periodically, so you find the wall before it finds you mid-task.

Symptom, cause, fix

  1. 1The agent edits the wrong file. It guessed at context. Mention the exact files with @ and run it again.
  2. 2It keeps using a pattern you abandoned months ago. The old code is still in the repo and looks authoritative. Delete the dead code, or write a rule naming the current pattern explicitly.
  3. 3It ignores a convention you have stated in chat five times. Chat context does not persist across sessions. Move the convention into a .cursor/rules file where it does.
  4. 4An extension you rely on does not work. Cursor is a fork and sometimes trails the upstream marketplace. Look for a compatible build, or open that one file in VS Code.
  5. 5You accepted a bad agent run and cannot remember what changed. Restore the checkpoint from the chat timeline. If you committed first, git diff tells you exactly what moved.
  6. 6You hit your agent limit halfway through a task. Lower tiers cap requests. Switch to inline edit and Tab, which accomplish far more per request than an agent loop does.
  7. 7Tab suggestions feel worse than yesterday. You are likely in a file the index has not caught up with, or sitting on a lot of unsaved churn. Save, then give it a moment.
Cursor sits at one point on a spectrum of how much control you hand over. How to Use GitHub Copilot is the conservative end — suggestions you accept one at a time — and it is worth knowing if you work on teams that standardize on it. How to Use Claude Code goes the other direction, dropping the editor entirely for a terminal agent. Every safety net described here rests on version control, so if committing before an agent run is not yet automatic, How to Use Git is the prerequisite you skipped, and How to Write Better AI Prompts sharpens the context habit that makes all three tools work. The Leveraging AI roadmap puts them in an order that builds.