Cursor Tutorial 2026: Beginner Guide to Agent in 15 Minutes

This tutorial shows how to use Cursor if you are opening it for the first time. It follows Cursor's official documentation as of 2026-11-01, when the current release was Cursor IDE 3.27.

A note on method: the NxCode team wrote this guide from those documents and did not run the steps on a fresh install. NxCode is our own product, an AI app builder, and is separate from Cursor. Where the guide says what you should see, that comes from the docs, so your screen may differ in small ways. Where official pages disagree or leave a gap, we say so.

If you have read an older Cursor tutorial, expect some surprises. Composer mode, Cmd+K Inline Edit and the separate Chat mode are all gone from the current docs.

Your 15-Minute Route

Minutes	What you do	What you get
0–3	Install, sign in, open a practice folder	Cursor running on your computer
3–5	Learn the two windows and a few shortcuts	You know where Agent lives
5–10	Run the first task with Ask, then Agent	A small page improved by Agent
10–12	Review the changes and test them	You know what Agent actually did
12–14	Practice restoring a checkpoint	You know how to undo
14–15	Add one project rule	Agent follows your preferences

What Is Cursor?

Cursor is a code editor with an AI agent built in. You describe a task in plain language, and Agent reads your project, edits files and can run commands.

If you have used VS Code, the editor will feel familiar. Regular editing shortcuts are the same, and you can import your extensions, themes, settings and keybindings.

Three things happen inside Cursor on a normal day:

Agent takes on tasks across your project.
Tab predicts what you are about to type while you write code yourself.
Rules tell Agent how your project should be handled.

Cursor suits people who want to work with code, or who want to learn to. Someone who only wants a finished app and has no interest in reading diffs has a different job to do, and we cover that under "When to Use a Different Tool" below. NxCode is one option there.

Install Cursor and Open It for the First Time

Step 1: Download

Go to cursor.com/download and pick your system.

System	Requirement	What to download
macOS	12 or later	`.dmg`, for Apple Silicon or Intel
Windows	10 or later	`.exe`, x64 or ARM64, each with System and User installers
Linux	Debian/Ubuntu or RHEL/Fedora	apt or yum repository first, AppImage also available

On Linux, the official quickstart prefers the apt and yum repositories because they add a desktop icon, automatic updates and the command-line tool.

Step 2: Open Cursor and Sign In

The official order is short: download, open, sign in, choose a folder, start with a small task. You need an account.

Cursor's sign-in can send you to a shared xAI page with Grok or xAI branding. That is expected, because new customers now start on The X Subscription, the subscription Cursor is sold under. Signing in does not merge accounts or change a plan.

Older guides list "choose your AI model" as a first-launch step. The current docs have no such step. You can set a default later in Cursor Settings > Models, or switch during a conversation.

The docs also do not say whether a new user lands in the Agents Window or the editor first. The next section shows how to move between them, so either start is fine.

Step 3: Pick a Plan

Start on Free ($0, limited usage), move to Plus ($8/month) if the limits interrupt your work, and choose Premium ($30/month) only when you need Cloud Agents, third-party models or your own API keys.

Prices exclude tax. Plans above that are Super ($100) and Ultra ($200). For detail, see our Cursor pricing guide or the official pricing page. Buy only through the official site or in-app purchase, since the pricing page says Cursor does "not authorize any resellers or third-party sellers".

Step 4: Optional, Bring Your VS Code Setup

Importing VS Code settings is no longer described as a first-launch step. If you want it, press Cmd+Shift+J (Ctrl+Shift+J on Windows and Linux) to open Cursor Settings, then go to General > Account > VS Code Import > Import.

Extensions in Cursor come from Open VSX, not the VS Code Marketplace, and not every extension is there. If one is missing after import, that is the likely reason.

Check the publisher before you install anything. On October 29, 2026, Cursor warned of a malicious extension posing as Anthropic.claude-code (versions 2.1.312 and 2.1.313) in its marketplace.

Get to Know the Interface

Two Windows: Agents Window and the Editor

Cursor has two main interfaces, and the docs say both stay supported. You can keep them open at the same time.

	Agents Window	Editor (IDE)
Built around	Agents	Your files
Good for	Several repositories, parallel agents, local, cloud and SSH work	Reading and editing code next to Agent
How to get there	Cmd+Shift+P, then Open Agents Window	Cmd+Shift+P, then Open IDE

On Windows and Linux, the command palette is Ctrl+Shift+P.

A few features exist only in the Agents Window, including multiple workspaces, the new diff view, parallel cloud agents and the native Worktrees interface.

For your first day, use the editor. You can see the file and the conversation side by side, which makes it easier to follow what Agent is doing.

The Agent Panel

In the editor, press Cmd+I (Ctrl+I) to open the panel on the side. The docs call it the "Agent panel", and the shortcut table calls it the "Sidepanel". They are the same thing.

Inside the panel you will use:

The input box for your request. Drag or paste images into it, or use the microphone for voice.
The mode dropdown, which switches between Agent, Ask, Plan and Debug.
The model picker at the top of the input box.
@ to point at something specific, and / to call skills and commands.

The current official @ list is short: a file or folder such as @index.html or @src/components/, @Terminals, @Chats, @Commit (Diff of Working State), @Branch (Diff with Main) and @Browser. If you are not sure which file matters, skip @. The docs say Agent finds relevant files through its own search.

Older tutorials teach @codebase, @docs and @web. These are not in the current list, and we could not confirm whether they still work.

The sidebar also has a Customize page, which collects plugins, skills, MCP, subagents, rules, commands and hooks in one place. You will use it later.

Terms to Know: What the Names Mean Now

Many Cursor names changed. This table shows what each one means today.

Term	What it means now	If an old tutorial says
Composer	Cursor's own model, currently Composer 2.5, described as fast and cost-efficient	"Composer mode": no longer in the docs, use Agent
Agent	The default mode and the main way to work	"Switch to Agent in Composer": no switch needed
Chat	Not a separate mode. Docs write "Agent (Chat)"	"Open Chat to ask questions": use Ask, the read-only mode
Inline Edit	Retired; see below	"Select code and press Cmd+K to edit in place": select code, press Cmd+K or Cmd+L, and it goes to Agent
Tab	Autocomplete, name unchanged	"Supermaven": the word does not appear in the official docs we read
Free	The $0 plan for new customers	"Hobby": a legacy plan kept for existing users
`.mdc` rule	The required file type for project rules	"`.cursorrules`": legacy and due to be deprecated

Cursor's help page says Cmd+K "used to open inline edit, which has been replaced by this workflow". A Cursor staff post on the official forum gives the date, 2026-10-26, and says this includes generating commands with Cmd+K in the terminal. The suggested replacement is Cmd+I and asking Agent. One help page, on the terminal, still mentions generating commands with natural language, so the docs are not fully consistent here. This guide follows the staff post.

Shortcuts for Your First Day

Cursor's reference table lists Mac keys only, and help pages add some Windows and Linux keys. Where nothing is listed, we say so rather than guess. For those, check the shortcut settings in the app (Cmd+R then Cmd+S, or Ctrl+R then Ctrl+S).

Action	Mac	Windows / Linux
Open or close the Agent panel	Cmd+I, Cmd+L or Cmd+K	Ctrl+I, Ctrl+L or Ctrl+K
Send selected code to a new chat	Cmd+L or Cmd+K	Ctrl+L or Ctrl+K
Add selected code to the current chat	Cmd+Shift+L	Not listed, check the app
Cycle modes	Shift+Tab	Shift+Tab
Open the mode menu	Cmd+.	Ctrl+.
Cycle models	Cmd+/	Ctrl+/
Accept a Tab suggestion	Tab	Tab
Accept Tab word by word	Cmd+→	Ctrl+→
Reject a Tab suggestion	Escape, or keep typing	Escape, or keep typing
Accept all changes	Cmd+Return	Not listed, check the app
Reject all changes	Cmd+Shift+Backspace	Not listed, check the app
Cursor Settings	Cmd+Shift+J	Ctrl+Shift+J
Command palette	Cmd+Shift+P	Ctrl+Shift+P

Two keys depend on where you are. Cmd+K opens the panel in the editor, but in the Agents Window it opens a command palette. Cmd+Return also has several meanings depending on context, as the keyboard shortcut reference shows. Cmd+Shift+Backspace is also listed for cancelling a response in progress, so press it with care.

First Task Walkthrough: Improve a Small Project With Agent

This example uses a single web page, so you need no tools beyond Cursor and a browser. You will ask questions first, then let Agent make changes.

Step 1: Create the Practice Project

Make an empty folder called cursor-practice, then choose it as your folder in Cursor. Create a file named index.html and paste this in:

<!doctype html>
<html>
  <head><meta charset="utf-8"><title>Tip calculator</title></head>
  <body>
    <h1>Tip calculator</h1>
    <label>Bill <input id="bill" type="number"></label>
    <button onclick="calculate()">Calculate 15% tip</button>
    <p id="result"></p>
    <script>
      function calculate() {
        const bill = Number(document.getElementById("bill").value);
        document.getElementById("result").textContent = "Tip: " + (bill * 0.15);
      }
    </script>
  </body>
</html>

Save the file and open it in your browser. Press the button with an empty bill and you get "Tip: 0". That is the small problem you will fix.

Step 2: Ask Before You Change Anything

Press Cmd+I (Ctrl+I). Open the mode dropdown and choose Ask, or press Shift+Tab until it shows. Type:

Explain what index.html does in plain language.
Then list the problems a user could run into.

What you should see: a written answer in the panel. Your file does not change, because Ask is read-only. The answer will probably mention the empty bill. Exact wording varies between runs, so do not expect a fixed reply.

Step 3: Give Agent a Specific Task

Switch back to Agent. Changing modes opens a new context window, so write the request so it stands on its own:

In @index.html, improve the tip calculator:
1. If the bill is empty, zero or negative, show "Enter a bill above 0".
2. Show the tip with two decimal places.
3. Add a dropdown for 10%, 15% and 20%, with 15% selected by default.
Keep everything in this one file. Do not add libraries.

What you should see: Agent reads the file and starts editing. The important point for beginners is that edits are applied as Agent works. You are not approving each change in advance. You review the result in a diff view afterwards.

Agent may also want to run a command. How that is handled depends on the run mode, set in Cursor Settings > Agents > Approvals & Execution. The options are Auto-review (the default), Allowlist and Run Everything. Leave it on the default for now.

Step 4: Review the Diff

Cursor shows the edits in a diff view. The docs do not name the exact button, so look for it around the edited file and the Agent panel. Read it line by line. A diff shows removed lines and added lines, so you can see exactly what changed. For this task, look for:

a check on the bill value
a dropdown with three percentages
a tip rounded to two decimals
nothing unrelated, such as a new file you did not ask for

Reject anything you do not want. To accept or reject everything at once on a Mac, use Cmd+Return or Cmd+Shift+Backspace. For Windows and Linux, check the app, as noted above.

Step 5: Test It Yourself

Reload the page in your browser and try these cases:

Input	Expected result
Empty bill	The "Enter a bill above 0" message
-5	The same message
100 at 15%	Tip: 15.00, or similar
100 at 20%	Tip: 20.00, or similar

If one fails, tell Agent exactly what happened: "With a bill of -5 the page shows Tip: -0.75. It should show the message." This works much better than "it's broken".

Step 6: Practice Undoing

Now make a change you plan to throw away:

Change the page background to bright green and make all text 40px.

Reload the browser to see it. Then scroll up in the conversation and click Restore Checkpoint on that request. One help page calls this button Revert. Reload again and the green should be gone. If it is not, restore from the request before it. Agent creates checkpoints before significant changes, so if you see no button for a change this small, reject it in the diff instead. Your messages stay in the conversation, because a restore only reverts files.

That is the whole daily loop: ask, instruct, review, test, undo if needed. If reading diffs is the part you never want to do, that is useful to learn early. It may be a sign that NxCode, our own app builder, fits you better than an editor does.

When to Use Agent, Ask, Plan and Debug

There are four modes. Switch with Shift+Tab or the dropdown in the Agent panel.

Mode	Use it when	Can it change files?	Example prompt
Agent	You want something built, refactored or fixed. This is the default	Yes	"Add a reset button and clear the result when it is pressed."
Ask	You want to understand code	No, read-only	"How does the tip get calculated here?"
Plan	The task is large or unclear and you want to check the approach first	After you approve	"Plan how to split this page into separate HTML, CSS and JS files."
Debug	A bug needs evidence from the running program	Yes	"The tip is wrong after I change the percentage. Find the cause."

A simple way to choose:

Do not understand it yet? Ask.
Know what you want and the change is small? Agent.
Touches many files, or you are unsure of the approach? Plan.
A bug you cannot explain by reading the code? Debug.

In Plan mode, Agent asks clarifying questions, researches your code and writes a plan. Nothing is built until you click Build. Plans are saved in your home directory by default, and Save to workspace moves one into your project. Cursor may also suggest Plan when your request looks complex.

In Debug mode, Agent forms hypotheses, adds logging and uses the runtime information to find the cause.

Review and Undo Changes

Review Checklist

Use this before you keep any Agent change:

Read the whole diff, not just the summary.
Every changed file relates to the task.
You can explain each change. If you cannot, ask in Ask mode.
Nothing was deleted that should have stayed.
No passwords, keys or other secrets appear in the code.
You tested it yourself, including one bad input.

Beyond your own review, Cursor has Agent Review, started with /agent-review or from the Source Control tab.

How Checkpoints Work

Agent creates a checkpoint automatically before significant changes. Checkpoints are stored locally and are separate from Git.

There are three ways to restore:

Click a checkpoint in the chat timeline to preview it, then restore.
Click Restore Checkpoint on an earlier request.
Hover over a message and click the + button.

Restoring reverts files but does not delete messages. To shorten the conversation as well, fork from an earlier message.

The official pages disagree on one name here. The Agent docs call the button Restore Checkpoint, while the Plan help page calls it Revert, followed by Confirm. Look for either label.

Use Git for Anything You Want to Keep

Cursor's own advice is to "use Git for permanent version control". Checkpoints are a quick undo, and Git is your long-term history. Before a bigger Agent task, save a working state:

git init
git add .
git commit -m "Working version before Agent task"

You only need git init once per project.

Add Rules to Your Project

Rules are standing instructions, so you do not have to repeat yourself. Add one to the practice project. There are three ways to create a project rule:

Type /create-rule in the chat.
Go to Customize > Rules > Add Rule.
Run New Cursor Rule from the command palette.

Or create the file yourself at .cursor/rules/practice.mdc:

---
description: Conventions for this practice project
globs:
alwaysApply: true
---

- Keep everything in index.html unless asked otherwise.
- Do not add libraries.
- Use clear variable names and short comments.

Now ask Agent for another small change. It should follow these rules without being told.

Four things to know:

The extension must be .mdc. Files ending in .md are ignored by the rules system in that folder.
AGENTS.md is the simpler option. It is plain Markdown, placed in the project root or a subfolder. Cursor reads CLAUDE.md the same way.
Rules apply to Agent only. They do not affect Tab or Bugbot.
Keep them short. Cursor suggests under 500 lines per rule.

Rules have four types: Always Apply, Apply Intelligently, Apply to Specific Files and Apply Manually (with an @ mention). Precedence is Team, then Project, then User. .cursorrules is legacy and will be deprecated, so do not start a new project with it.

MCP, Skills, Subagents and Cloud Agents at a Glance

You do not need any of these on day one. This is just so you recognize the names.

MCP connects Agent to outside tools and services. Install from Customize > MCPs > Add to Cursor, or configure .cursor/mcp.json in a project or ~/.cursor/mcp.json globally. If both define the same name, the project wins. Our Cursor MCP guide goes further.
Skills are folders with a SKILL.md file that teach Agent a procedure. Agent uses them when relevant, or you call one with /. Built-in examples include /create-rule, /review and /shell.
Subagents have their own context and can run in parallel. The built-in ones are Explore and Browser. Custom ones go in .cursor/agents/.
Cloud Agents run in isolated cloud machines, so they do not depend on your computer staying online. Choose Cloud from the dropdown on the agent input box. An admin must first connect GitHub, GitLab, Bitbucket or Azure DevOps, and you need read and write access to the repository. They are not available on Free or Plus.

The Command Line: `agent`

Cursor also has a CLI, and the command is agent. Install it with:

# macOS, Linux, WSL
curl https://cursor.com/install -fsS | bash

# Windows PowerShell
irm 'https://cursor.com/install?win32=true' | iex

Check it with agent --version and sign in with agent login. Then run agent in a project folder for an interactive session, or agent -p "your request" for a single non-interactive run. It reads the same .cursor/rules, AGENTS.md and CLAUDE.md files as the editor. Beginners can leave this until later.

Common Mistakes

Following an old tutorial. If a guide says to open Composer mode, press Cmd+K to edit in place, or pick a model at first launch, it describes an older Cursor.

Assuming nothing changed until you accept. Agent's edits are already applied while it works. Check the diff before moving on, and do not run the code on trust alone.

Writing vague requests. "Fix this" gives Agent little to work with. Say what happens, what should happen and where: "When the bill is empty, the page shows Tip: 0. It should show a message instead."

Starting too big. Do not begin with a complete app. Use small tasks first, and use Plan mode for anything larger.

Treating checkpoints as backups. They are local and separate from Git. Commit anything you care about.

Saving a rule as .md. It looks correct and does nothing. Use .mdc, or use AGENTS.md in the project root.

Changing the run mode on day one. Leave the default until you understand what Agent runs on your computer and what permission each option grants.

Picking a third-party model without checking the cost. On Premium and above, third-party models charge prepaid credits at API list price from the first request. They do not use your weekly pool.

Accepting code you cannot explain. Ask mode exists for this. Ask "what does this change do, step by step?" before you keep it.

Troubleshooting

Interface and Setup

What you see	Likely reason	What to do
No Composer mode anywhere	It no longer exists as a mode	Use Agent with Cmd+I (Ctrl+I)
Cmd+K does not edit in place	Inline Edit was retired	Select code, press Cmd+K, then describe the change in Agent
Cmd+K opens a command palette	You are in the Agents Window	Use Cmd+Shift+P, then Open IDE to return to the editor
A Grok or xAI login page appears	Shared sign-in	This is expected. Signing in does not merge accounts
An extension is missing	It may not be on Open VSX	Look for an alternative in Open VSX
A rule is ignored	Wrong extension, or wrong location	Use `.cursor/rules/name.mdc`, and check its type
Agent forgets earlier context	You switched modes	Each switch opens a new context window, so restate the key points
A shortcut does nothing on Windows	It may differ from the Mac key	Check the shortcut settings with Ctrl+R then Ctrl+S

Models, Plans and the CLI

What you see	Likely reason	What to do
Claude or GPT is missing	Plan or region	Free and Plus exclude third-party models. Some models are also hidden in certain regions
Cloud Agents are unavailable	Plan or repository setup	Needs Premium or higher, a connected Git provider and repository access
You hit a usage limit	Plan limit reached	Check Usage at grok.com/dashboard. On paid plans, wait for the weekly reset, use prepaid credits or upgrade
Cannot find billing	Billing moved	The X Subscription uses grok.com/dashboard/billing. Legacy plans use cursor.com/dashboard/spending
`agent: command not found`	`~/.local/bin` is not in your PATH	Add it to your PATH, then open a new terminal

When to Use a Different Tool

Cursor is a tool for working with code. These scenarios may point elsewhere:

You do not want to write or review code at all. You want a working app from a description. That is what NxCode, our own product, is for. We make it, so weigh that when reading this, and see our comparison with Cursor and Copilot.
You live in the terminal. Try Cursor's agent command first, or compare it with the workflow in our Claude Code tutorial.
You use JetBrains. You may not need to switch editors, because Cursor's agent connects to JetBrains through ACP.
You are still comparing tools. Our ranking of AI coding tools sets out the options.

Trying Cursor on Free costs nothing, so a small real task is a reasonable way to decide. If the workflow above felt natural, stay. If the code itself got in the way, the first scenario probably fits you.

FAQ

How do I start using Cursor for the first time?

Download Cursor from cursor.com/download, open it, sign in and choose a folder. Then press Cmd+I (Ctrl+I on Windows and Linux) to open Agent and ask it to explain the code. Cursor's quickstart recommends starting with a small task like this.

What happened to Composer mode in Cursor?

Composer mode is not in Cursor's current documentation. Composer is now the name of Cursor's own model, currently Composer 2.5. The four modes are Agent, Ask, Plan and Debug. For the multi-file work older tutorials did in Composer mode, use Agent.

What happened to Cmd+K inline edit in Cursor?

Inline Edit was retired. A Cursor staff post on the official forum dates this to 2026-10-26. In the editor, select code and press Cmd+K or Cmd+L (Ctrl+K or Ctrl+L on Windows and Linux) to bring the selection into Agent, then describe the change there.

Is Cursor free?

Yes, there is a Free plan at $0 with limited Agent, Chat and Tab usage. Cursor does not publish a number for those limits. The current pricing page does not say whether a credit card is needed, so check when you sign up. Paid plans start at Plus for $8 a month before tax.

Which AI models can I use in Cursor?

Cursor's own models are Grok 4.7, which it calls its flagship model, Grok 4.6, Grok 4.5 and Composer 2.5. Third-party models such as Claude, GPT and Gemini need Premium or higher and are charged at API list price from prepaid credits. Free and Plus do not include them.

Does Cursor Agent change my files before I approve?

Yes. Agent applies edits as it works, and you review them afterwards in a diff view, where you can reject what you do not want. Agent also creates checkpoints before significant changes, so you can restore earlier file states.

Do I need to know how to code to use Cursor?

You can try it without much experience because Ask mode explains code in plain language, but you still have to read diffs and judge the result. If you would rather describe an app and not work with code at all, NxCode, our own product, is built for that.

Where can I buy Cursor, and can I subscribe from mainland China?

Cursor says subscriptions are sold only through its official website or in-app purchase, and it does not authorize resellers. iOS in-app purchase covers App Store regions except mainland China. Whether web subscriptions are restricted in mainland China could not be verified from official pages.

Sources

All pages were checked on 2026-11-01. Shortcuts, plans and names can change, so treat the app and the official pages as final.