Cursor Tutorial: Your First Agent Session

By the end of this tutorial you will have Cursor installed, one agent session finished on a real project, a change reviewed in the diff view, and a rules file that keeps the next session on track. The shortest path is: install and sign in, open a folder, press Cmd+I, ask for an explanation, ask for one small change, review the diff, and run your project's checks. Allow thirty minutes. Facts checked 31 October 2026.

What you will have at the end

• Cursor installed and signed in on a plan you chose on purpose
• A first agent session that explained a codebase and changed one thing
• A reviewed diff and a passing test, lint or build run
• A Plan Mode run for a bigger task
• A project rules file or AGENTS.md
• A run mode picked deliberately, not by default

Cursor is an editor with an agent built in. If you prefer a terminal agent, our Claude Code first-run guide covers that route, and Cursor vs Claude Code compares them. For a full product page, see Cursor.

Prerequisites

• A computer running macOS 12 or later, Windows 10 or later, or Linux
• A project folder you can afford to experiment in, under git, with a clean working tree
• A Cursor account. The Free plan is enough to try the agent.
• A test, lint or build command that works in the project

Run git status before you start. If the tree is clean, the diff you review later is only the agent's work.

Step 1: Install and sign in

Download Cursor from cursor.com, install it, open the app and sign in. macOS and Windows use native installers. On Linux, the docs recommend the apt or yum packages over the portable AppImage, because the packages give you desktop icons, automatic updates and command-line tools.

On Debian or Ubuntu, the docs give this sequence:

curl -fsSL https://downloads.cursor.com/keys/anysphere.asc | gpg --dearmor | sudo tee /etc/apt/keyrings/cursor.gpg > /dev/null
echo "deb [arch=amd64,arm64 signed-by=/etc/apt/keyrings/cursor.gpg] https://downloads.cursor.com/aptrepo stable main" | sudo tee /etc/apt/sources.list.d/cursor.list > /dev/null
sudo apt update
sudo apt install cursor

If you use the AppImage instead, run chmod +x Cursor-*.AppImage and start it with ./Cursor-*.AppImage.

Then pick a folder. Cursor opens it as the workspace.

Step 2: Open Agent and ask for an explanation

Open the agent side pane with Cmd+I on macOS. Start with a question, not a change:

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

Cursor searches your repo, reads the relevant files and summarizes how the project fits together. This checks whether the agent understood the project, and it costs little if the answer is wrong.

Point it at the right files

Type @ in the chat input to attach context. The prompting docs list the main kinds:

The docs say to use @ when you know which files matter, and to skip it when you do not, because the agent finds relevant files through its own search. You can also attach images for UI work and error screenshots.

Step 3: Make one small change

Ask for options first, then choose:

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

Pick one that is low risk, such as a copy fix or a small UI tweak, and say so:

Do the second one. Keep the change as small as possible and do not touch other files.

If you already know what you want, ask for it directly and describe the result. A prompt that names the file, the symptom and the expected result saves a round of corrections.

Step 4: Review the diff, then run the checks

Watch the agent work. The diff view shows each change it makes. When it finishes, read every changed line, the way you would review a colleague's pull request. Then ask it to run what the project already uses:

Run the tests and the linter. If anything fails, fix it and run them again. Show me the commands and their output.

Do the check yourself in a terminal too, at least the first few times:

npm test
git diff --stat

The quickstart suggests the same loop: review the diff, then verify with the checks your project already has. The agent can also use a built-in browser tool to take screenshots and test an app, which helps for UI changes.

Undo with checkpoints, keep history in git

Cursor creates checkpoints automatically before significant changes. To go back, click a checkpoint in the chat timeline, preview your files at that point, and restore. Restoring reverts files only. It does not remove messages from the conversation. The docs state that checkpoints are stored locally and are separate from Git, and that you should use them only for undoing agent changes. Commit your accepted work:

git add -A
git commit -m "fix: small copy change from first agent session"

Step 5: Use Plan Mode for a bigger task

For work that spans several files, needs research or needs your approval first, press Shift+Tab in the agent input to switch to Plan Mode. The docs describe the flow:

1. The agent asks clarifying questions about your requirements.
2. It researches your codebase for the relevant files.
3. It writes a detailed implementation plan.
4. You review and edit the plan, in chat or as a markdown file.
5. You click to build when you are ready.

Try it with a real task:

Add a "last updated" date to the footer, read from the git history at build time. Ask me what you need to know first.

Plans are saved in your home directory by default. Choose "Save to workspace" to keep one in the repo for your team. The docs also give a useful rule: if the agent built something you did not want, do not patch it with follow-up prompts. Revert the changes, make the plan more specific, and run it again. It is often faster and cleaner. Skip Plan Mode for quick changes you have done many times.

Step 6: Steer a running agent

While the agent works, you have choices.

Use the queue for follow-ups, and send-now for corrections ("stop, use the existing helper"). Do not wait out a task that has clearly gone the wrong way. The docs also describe /goal for a long-lived objective, such as /goal fix all flaky tests and make CI green, and say it is rolling out, so try it in a new chat if you do not see it.

Step 7: Write project rules

The agent does not remember earlier sessions. Rules give it persistent instructions at the start of every prompt. Cursor supports four kinds: Project Rules in .cursor/rules, User Rules for your own environment, Team Rules from the dashboard on Team and Enterprise plans, and AGENTS.md.

For most projects, start with the simplest option. Put an AGENTS.md in the project root, as plain markdown:

# Commands
- Test: npm test
- Lint: npm run lint

# Conventions
- Use the existing helpers in src/lib/, do not add new dependencies
- Never edit files under dist/ or build/

# Gotchas
- Integration tests need DATABASE_URL, see .env.example

When you need rules that apply only to certain files, use a project rule. Files in .cursor/rules must end in .mdc. A plain .md file there is ignored, because it has no frontmatter. This is a common reason a rule seems not to work.

---
description: React component conventions
globs: src/components/**/*.tsx
alwaysApply: false
---
- Use function components and hooks
- Put styles next to the component

The docs explain how the three fields combine:

Keep rules short and about things the agent cannot work out from the code, such as commands and traps. For the equivalent in Claude Code, see our CLAUDE.md guide and AGENTS.md guide.

Step 8: Choose a run mode on purpose

Run Modes decide how much the agent can do without asking, for shell commands, MCP tools and Fetch calls. Find them in Settings, under Agents, then Approvals & Execution.

The docs call Auto-review the safest useful setup for most people, and say it is not a security boundary. The classifier can make mistakes in either direction. For a first week, Auto-review or Allowlist is a sound choice. Do not use Run Everything on a machine that holds credentials you care about.

What it costs, and which models you can pick

What you can pick depends on your plan. From Cursor's pricing documentation, checked 31 October 2026. Prices exclude tax.

Annual billing is $80 a year for Plus, $300 for Premium, $1,000 for Super and $2,000 for Ultra. Paid plans include a weekly pool of usage for Cursor's own models, shared across Agent, the CLI, Cloud Agents and Grok features, and it refreshes weekly. Plus runs Cursor's own models (Grok 4.7, Grok 4.6, Grok 4.5 and Composer 2.5) at fixed settings. Claude, GPT and Gemini models are not part of the included pool: on Premium and above you pay their API list price from prepaid credit.

Read that twice before you plan around a favorite model. The docs say the plan is sold as part of The X Subscription. Older plans (Pro, Pro+, Ultra legacy, Start, and Teams Standard and Premium) keep working for existing customers with two monthly usage pools. Premium suits new Agent users, according to the docs, Super suits daily users and Ultra suits power users. See Cursor pricing and AI coding agent pricing compared.

What can go wrong

Privacy

Cursor sends your prompts and the code it reads to model providers to produce a reply. Which data is stored, and whether it is used for training, depends on your plan and privacy settings. Before you use Cursor on client or proprietary code, read those terms, set the privacy options your team requires, and keep secrets out of the repo and out of @ mentions. The run-modes docs also say the Auto-review classifier runs on Cursor's backend and can read files such as a script a command runs, so factor that in for sensitive repos.

Checklist

• Plan chosen on purpose, and third-party model needs checked against it
• Clean git tree before the first prompt
• First prompt was a question, not a change
• One small change, with the diff read line by line
• Tests and lint run, by the agent and by you
• Work committed to git, not left only in checkpoints
• Plan Mode used for anything touching many files
• AGENTS.md or a .mdc rule written with commands and traps only
• Run mode set to Auto-review or Allowlist
• Privacy settings checked before using private code

What this guide uses