Cursor Tutorial for Beginners: Your First AI-Assisted Project

Cursor is the most popular AI coding assistant for a reason: it understands your entire project, not just the file you are looking at. But the first time you open it, Cursor can feel overwhelming. There are multiple AI features, keyboard shortcuts, and interaction modes, and it is not obvious which to use when.

This tutorial walks you through your first Cursor session, from installation to your first multi-file edit. It assumes you have basic familiarity with code — you know what HTML, CSS, and JavaScript are, even if you do not write them daily. If you have never touched code at all, start with an app builder like Lovable or Bolt.new instead.

Step 1: Install Cursor

Download Cursor from cursor.com. It is available for Mac, Windows, and Linux. The installer is straightforward — run it and Cursor opens like any other application.

When you first launch Cursor, it will ask if you want to import settings from VS Code. If you have used VS Code before, say yes. Cursor is a fork of VS Code, so your extensions, themes, keybindings, and settings carry over. If you have not used VS Code, start fresh — the defaults are fine.

Cursor offers a free trial that gives you limited premium AI requests per day. This is enough to complete this tutorial and decide if Cursor is worth the $20/month Pro subscription. You do not need to enter payment information to start.

Step 2: Open or Create a Project

Cursor works on projects, not individual files. Open a folder that contains code (or where you want to start a new project). You can do this through File > Open Folder or by dragging a folder onto the Cursor window.

For this tutorial, let's create a simple project. Open your terminal (Terminal > New Terminal in Cursor, or Ctrl+` on Windows / Cmd+` on Mac) and create a new folder:

mkdir my-first-cursor-project
cd my-first-cursor-project

Then open this folder in Cursor. You should see an empty file explorer on the left side.

Important: When you open a project for the first time, Cursor will index your codebase. This means it reads and understands the structure of your files so it can give contextual suggestions. For a new project, this is instant. For large existing projects, it can take a minute or two. Let it finish — the indexing is what makes Cursor smarter than a basic AI chatbot.

Step 3: Meet the Three AI Interactions

Cursor has three main ways to interact with AI, and understanding when to use each one is the key to productivity.

Inline Edit (Cmd+K / Ctrl+K)

This is for small, focused changes. Highlight a block of code (or place your cursor where you want new code), press Cmd+K (Mac) or Ctrl+K (Windows), and describe what you want. Cursor rewrites the selected code or generates new code at your cursor position.

Use this when you know exactly where the change should happen and can describe it in one sentence. Examples: "make this button blue instead of green," "add error handling to this function," "convert this to TypeScript."

Chat (Cmd+L / Ctrl+L)

This is for asking questions and getting explanations. Press Cmd+L (Mac) or Ctrl+L (Windows) to open the chat panel. You can ask about your code, request explanations, or discuss implementation approaches before making changes.

Use this when you are not sure what to do, need to understand existing code, or want to discuss options before committing to a change. Examples: "explain what this useEffect hook does," "what is the best way to add authentication to this project," "why is this component re-rendering?"

Composer (Cmd+I / Ctrl+I)

This is for large, multi-file changes. Press Cmd+I (Mac) or Ctrl+I (Windows) to open Composer. Describe a feature or change, and Cursor will generate edits across multiple files, showing you a diff for each file that you can accept or reject individually.

Use this when a change touches more than one file, or when you want to create a new feature that requires new files. Examples: "add a settings page with a form for updating the user's name and email," "create a blog section with a list page and individual article pages," "refactor the auth logic into a separate module."

Step 4: Build Something — A Personal Dashboard

Let's build a simple personal dashboard with Cursor. This exercise will use all three interaction modes.

Start with Composer. Press Cmd+I (or Ctrl+I) and type:

"Create a personal dashboard web page with HTML, CSS, and JavaScript. Include a greeting section that shows the current time and date, a to-do list where items can be added and removed, and a section showing the current weather (use a placeholder for now). Make it responsive and use a clean, modern design with a dark theme."

Cursor will generate three files: index.html, style.css, and script.js. Review the diff for each file. Look at the code — you do not need to understand every line, but skim it to confirm it looks reasonable. Accept all three files.

Test it. Right-click index.html in the file explorer and choose "Open with Live Server" (if you have the Live Server extension) or simply open the file in your browser. You should see a working dashboard.

Refine with inline edit. Maybe the color scheme is not quite right. Open style.css, highlight the color variables at the top, press Cmd+K, and type: "change the accent color to a warm orange and make the background slightly lighter." Accept the change and refresh your browser.

Ask a question with chat. Open chat (Cmd+L) and ask: "How would I connect the weather section to a real weather API? What are the best free options?" Cursor will explain the options — OpenWeatherMap, WeatherAPI, etc. — and suggest implementation approaches. When you are ready, use Composer to implement the one you choose.

Step 5: Handle Bad Suggestions

Cursor will give you bad suggestions. This is guaranteed. Knowing how to handle them is a skill you need to develop.

When Composer generates wrong code: Do not accept it. Click "Reject" on the diff. Then refine your prompt — be more specific about what you want. If Cursor generated a to-do list that saves to localStorage but you wanted one that saves to a database, say that explicitly. The AI cannot read your mind, only your words.

When inline edit breaks something: Press Cmd+Z (Ctrl+Z) to undo. Cursor's edits are regular edits — they can be undone like any other change. Then try again with a more specific prompt or a different approach.

When the AI is confidently wrong: This happens when Cursor generates code that looks correct but has subtle bugs. The best defense is to test every change immediately. Do not accept five Composer edits in a row without checking each one. Build incrementally: make a change, test it, make the next change. For more on writing effective prompts, see our guide to prompts for AI coding tools.

When you are stuck in a loop: If you have asked Cursor to fix the same bug three times and it keeps introducing new issues, stop. Copy the error message, open chat, and ask: "I keep getting this error after trying to fix X. Can you explain what is causing it and suggest a different approach?" Sometimes the fix requires restructuring the code, not patching the existing approach.

Step 6: Use Context Effectively

Cursor's superpower is context — its ability to understand your entire project. But you need to help it use context effectively.

Use @file references. In Composer or Chat, you can type @filename to explicitly include a file in the AI's context. If you are asking Cursor to add a feature that should match the style of an existing component, reference that component: "Add a settings page that follows the same layout pattern as @ProfilePage.tsx."

Use @codebase for broad questions. When you want Cursor to search your entire project for relevant context, use @codebase in your prompt. This triggers a search across all indexed files. Use it for questions like "where is the authentication logic handled in @codebase?" or "find all places where we make API calls @codebase."

Keep related code together. Cursor understands files that are open in your editor better than files that are closed. If you are working on a feature that spans three files, open all three before starting a Composer session. This gives Cursor better context for generating coherent cross-file changes.

Step 7: Your First Multi-File Edit

This is where Cursor's real value shows. Let's extend the dashboard with a feature that requires changes across multiple files.

Open Composer (Cmd+I) and type:

"Add a bookmarks section to the dashboard. Users should be able to add a bookmark with a title and URL, see their bookmarks in a grid layout with favicons, and delete bookmarks. Save bookmarks to localStorage. Add the bookmarks section below the to-do list and style it consistently with the existing design."

Cursor will propose changes to index.html (new HTML for the bookmarks section), style.css (new styles), and script.js (bookmark add/delete logic and localStorage persistence). Review each file's diff carefully. The changes should be consistent with the existing code patterns.

Accept the changes, test in your browser, and iterate. Maybe the favicon loading is slow or the grid spacing is off — use inline edit for these small refinements.

Essential Keyboard Shortcuts

Common Beginner Mistakes

Prompts that are too vague. "Make the app better" will give you random changes. "Add form validation to the sign-up form: email must be valid format, password must be at least 8 characters with one number, show error messages below each field" will give you exactly what you want. Specificity is the single most important prompting skill. See our prompting techniques guide for more.

Accepting changes without testing. Every Composer edit should be followed by a test. Open your browser, click through the feature, try edge cases. AI-generated code often works for the expected input but breaks for unexpected input.

Not using version control. Before making large changes with Composer, commit your current working state with Git. If the changes go wrong, you can revert to the last working version. git init, git add ., git commit -m "working dashboard" takes ten seconds and saves hours of frustration.

Fighting the AI instead of guiding it. If Cursor's approach to a feature is different from what you imagined, consider whether its approach might actually be better. AI tools have seen millions of implementations. Sometimes the "wrong" approach is actually a better pattern you were not aware of. Ask Chat to explain why it chose a particular approach before rejecting it.

What to Build Next

Now that you have the basics, here are good next projects for building your Cursor skills, in order of increasing complexity:

• A portfolio site — Static HTML/CSS, multiple pages, responsive design. Good practice for Composer multi-file edits.
• A habit tracker — Adds localStorage persistence and dynamic UI updates. Introduces more complex JavaScript.
• A simple API integration — Fetch data from a public API (weather, news, quotes) and display it. Introduces async JavaScript and API calls.
• A full-stack app with Supabase — User authentication, database storage, real backend. Follow our Build Your First App guide for this progression.

Each project teaches you new interactions with Cursor and builds your intuition for when to use inline edit, Chat, or Composer. The goal is not to memorize keyboard shortcuts — it is to develop a feel for working with AI as a collaborator.

---