AI for Coding

Cursor — The Complete Guide

Cursor is an AI-native code editor that reads your entire codebase and edits your actual files — not just a chat window you copy-paste from. Built on VS Code, it adds Tab completion, multi-file editing and autonomous agent mode on top of the editor you may already know. Over 2 million developers use it. 1 million pay for it. $2 billion in annual revenue as of early 2026.

AI Code Editor Free tier available Pro: $20/month Windows · macOS · Linux Last reviewed: April 2026

What is Cursor?

Cursor is a code editor — the application you write software in. It looks and works exactly like Visual Studio Code, which is already the most widely used code editor in the world. The difference is that Cursor has artificial intelligence built directly into the core of the editor, not bolted on as an add-on or extension.

When you use Cursor, the AI can see every file in your project. It reads your code the way a colleague would — understanding how the pieces connect, where functions are defined, what your variable names mean in context. When you ask it to do something, it does not just write code into a chat window for you to copy. It opens your actual files and edits them directly.

That distinction — AI that writes into your files versus AI that writes into a chat window — is the entire reason Cursor exists and why it grew from nothing to $2 billion in annual revenue in about two years.

What Cursor actually does

Cursor has four main AI features, each doing a different thing:

Tab completion — As you type, Cursor predicts the next line (or several lines) of code and offers to complete it. Press Tab to accept. This is faster than traditional autocomplete because it understands context from your whole project, not just the current line. It is always running in the background. It uses a fast, lightweight model specifically optimised for this task.

Chat — A conversation panel where you can ask questions about your code, request explanations or ask for specific changes. You can reference files, functions and documentation using the @ symbol. Unlike asking ChatGPT, the chat has full context of your project and can apply changes directly without you copying and pasting anything.

Composer / inline editing — You highlight a block of code, describe what you want changed and Cursor rewrites it. Or you open a new file and describe what you want built. Changes appear as a diff — green for additions, red for removals — so you can review exactly what the AI changed before accepting.

Agent mode — You describe a task in plain English ("Add user authentication to this API", "Write tests for every function in this file") and Cursor works through it autonomously — opening files, making changes, running terminal commands, checking its own output, and correcting mistakes. It works on its own while you do something else. You review the result when it is done.

Who Cursor is for

Cursor is used by professional software developers, but you do not have to be a professional developer to benefit from it. The range of users is wide:

Working developers who want to spend less time on routine code — tests, boilerplate, documentation, refactoring — and more time on the hard problems that actually require human judgment.

Founders and solo builders who have some coding ability but want to ship faster without hiring a full development team. Cursor compresses the distance between "I have an idea" and "it works".

Designers and product people who want to turn their prototypes into real code, or make small changes to an existing codebase without needing a developer for every minor edit.

Students learning to code who want to understand code as they write it — Cursor explains what things do and why, not just what to type.

Experienced engineers at companies including Stripe, Salesforce (where over 90% of developers use it), NVIDIA and Shopify — who use it to compress hours of routine implementation work into minutes.

What Cursor is not good for

Cursor does not replace the need to understand what you are building. If you accept AI-generated code without reading it, bugs accumulate silently and become expensive to fix later. The developers who get the most from Cursor are those who stay in the loop — reviewing changes before accepting, understanding the structure of what gets built.

Cursor is also not a good fit if you work exclusively in JetBrains IDEs (IntelliJ, PyCharm, WebStorm) or Vim. It only works as a standalone editor. If your team is locked into a specific IDE, Cursor is not an option — look at GitHub Copilot, which works as an extension inside almost any editor.

It is not a magic code generator that builds finished applications from a description. For that, look at Bolt.new or Replit Agent. Cursor is an editor that makes you significantly faster — it is not a replacement for the developer.

Why not just use ChatGPT for code?

This is the right question. ChatGPT can write code. The practical difference comes down to context and integration.

When you paste code into ChatGPT, you give it a fragment. ChatGPT does not know what the rest of your project looks like — what other files exist, what variables are already defined, what patterns the codebase follows. It generates code that may look correct but introduces inconsistencies with the rest of your project that you then have to fix manually.

Cursor has indexed your entire project. When you ask it to add a feature, it reads the relevant files automatically, follows your naming conventions, imports correctly, and applies the change in place. You do not copy anything. You review a diff and press Accept. The result is coherent with your codebase because the AI saw your codebase.

The second difference is speed. The round trip of describing a change, copying code out of a chat window, opening your editor, finding the right place, pasting it in, and adjusting for context takes several minutes per change. In Cursor, that round trip is seconds.

Is Cursor free?

Yes. The Hobby plan is free with no credit card required and no time limit. It includes 2,000 Tab completions per month and 50 premium model requests. That is enough to evaluate whether Cursor works for you, but not enough for full professional daily use.

Pro is $20 per month ($16 billed annually). This gives you unlimited Tab completions, unlimited Auto mode, and a $20 monthly credit pool for premium AI models including Claude Sonnet 4.6 and GPT-5.4. This is what most working developers use.

Students with a verified university email address get one year of Pro free.

The higher tiers — Pro+ ($60/month), Ultra ($200/month) — exist for developers who run background agents constantly and burn through the $20 credit pool regularly. Most developers on Pro never exhaust their credits if they use Auto mode for routine tasks and save premium models for complex work.

Getting started in 15 minutes

Step 1 — Download and install

Go to cursor.com and download the installer for your operating system. Cursor runs on macOS (12 Monterey or later), Windows (10 version 1903 or later, 64-bit) and Linux (Ubuntu 20.04+, Debian 10+, Fedora 36+ and Arch). Apple Silicon (M1 through M4) is natively supported with a dedicated ARM build.

Step 2 — Import your VS Code settings

On first launch, Cursor offers to import your existing VS Code settings, extensions, themes and keybindings in one click. If you use VS Code, accept this. You will have your complete familiar environment immediately with no setup required. If you do not use VS Code, the defaults are sensible.

Step 3 — Open your project

Open your project folder the same way you would in any code editor. Cursor will index your codebase in the background — this takes a few minutes for large projects. The indexing is what allows the AI to understand your entire project and give contextually accurate suggestions rather than generic code.

Step 4 — Try Tab completion

Start typing any function and watch the grey ghost text appear. This is Tab completion predicting what you are about to write. Press Tab to accept the full suggestion, or keep typing to ignore it. You can accept word-by-word with Ctrl+Right. This runs constantly at no additional cost on paid plans — it uses Cursor's own fast autocomplete model, not a premium frontier model.

Step 5 — Open the AI panel and try your first prompt

Press Ctrl+L (or Cmd+L on Mac) to open the Chat panel. Type a question about your code — "what does this function do?" or "are there any obvious bugs in this file?" Type @filename to reference a specific file. The AI has full context of your project but you can focus it with @ references.

Step 6 — Try an inline edit

Select a block of code. Press Ctrl+K (Cmd+K). Describe what you want changed — "add error handling", "convert this to async/await", "add JSDoc comments to every function". The diff appears inline. Green lines are additions, red lines are removals. Press Accept to apply or Reject to discard.

Step 7 — Try Agent mode

Press Ctrl+Shift+P and type "new agent" to open the Agents panel. Describe a task — something real that would take you 30 minutes. Agent mode will open files, make changes, run terminal commands and iterate. Watch what it does. Review the result before accepting. This is where Cursor's value compounds most.

The .cursorrules file — the most underused feature

Create a file called .cursorrules in the root of your project. This is a plain text file where you write instructions for how the AI should behave in this specific project. Cursor reads it automatically for every request.

Examples of what to put in .cursorrules:

  • The programming language, framework and version you are using
  • Naming conventions your team follows (camelCase, snake_case, file naming patterns)
  • Libraries to prefer or avoid
  • Testing framework and how tests should be structured
  • Error handling patterns your codebase uses
  • Any context about the project that helps the AI understand what it is building

A .cursorrules file transforms generic AI output into code that matches your codebase. Without it, the AI guesses at conventions. With it, every suggestion is consistent with how your project is already built. This is the single change that most improves output quality.

20 prompts and tasks for Cursor

Understanding and explaining code

Explain this codebase to me
Starting with the entry point, explain how this application works. Describe the main modules, how data flows through them, and what the key design decisions appear to be. Reference specific files as you go. I want to understand the architecture before making changes.
Explain a specific function
Explain what @filename.js does in plain English. Focus on what it is for, what arguments it expects, what it returns, and any side effects. Include any potential issues you notice.
Find where something is defined
Where is [function/variable/class name] defined in this codebase? List every place it is used and note which uses look correct versus potentially problematic.

Writing and editing code

Refactor a function
Refactor this function to be more readable without changing what it does. Extract any complex logic into well-named helper functions. Add a brief JSDoc comment explaining what it does and what each parameter is for.
Add error handling
Add proper error handling to this function. Use try/catch for any operations that could fail. Return appropriate error objects rather than throwing exceptions. Match the error handling pattern used elsewhere in this codebase.
Convert to async/await
Convert this Promise chain to async/await syntax. Preserve all existing error handling logic. Make sure the function signature and return type remain compatible with how it is called.
Add TypeScript types
Add TypeScript type annotations to this file. Create interfaces for any object shapes that appear more than once. Use the strictest types that are accurate — avoid using 'any' unless there is no better option. Check how the functions are called to infer the correct types.

Testing

Write tests for a file
Write comprehensive unit tests for every function in @filename. Use [Jest/Vitest/pytest — specify yours]. Cover: the happy path for each function, edge cases (empty inputs, nulls, boundary values), and error conditions. Follow the testing patterns already established in the existing test files.
Write tests for a specific function
Write unit tests for the [function name] function in @filename. I want tests that cover: the basic expected case, what happens with empty or null inputs, what happens at boundary values, and any error states the function should handle. The tests should actually catch real bugs, not just check that the function runs.
Fix a failing test
This test is failing with the error: [paste error message]. Here is the test: @test-file. Here is the function it is testing: @source-file. Identify the root cause — is it a bug in the function, an incorrect assumption in the test, or a missing edge case? Fix whichever one is wrong and explain why.

Debugging

Debug an error
I am getting this error: [paste full error message including stack trace]. This happens when [describe what triggers it]. Look at @relevant-file and explain: what is causing this error, where exactly it originates, and what the fix should be. Then apply the fix.
Review code for bugs
Review @filename for potential bugs and issues. Look for: logic errors, edge cases that are not handled, potential null pointer exceptions, performance problems, and security concerns. List each issue you find with the line number, what the problem is, and how to fix it.

Agent mode tasks (describe these in the Agents panel)

Add a complete feature
Add [feature description] to this application. The feature should: [list 3-5 specific requirements]. Follow the patterns already used in this codebase for [routing/state management/API calls — specify which]. Write tests for the new code. Update any documentation files that reference the affected areas.
Refactor a module
Refactor the @module-name module to [describe the goal — improve performance, reduce duplication, separate concerns, etc.]. Do not change external behaviour — all existing tests must still pass. Start by analysing the current structure and explain your approach before making changes.
Write tests for an entire module
Write unit tests for every public function in @module-name. Check the existing test files to understand what framework and patterns this project uses. Aim for meaningful coverage — tests that would actually catch a regression if the function changed, not just coverage theatre.
Migrate to a new pattern
Migrate all instances of [old pattern — e.g. class components to functional components, callbacks to async/await, require() to import] in this codebase. Make the changes incrementally file by file, run the test suite after each file to catch regressions. Report which files were changed and any issues encountered.

Tips that are not obvious from the homepage

Use Auto mode by default. Auto mode lets Cursor pick the best model for the task automatically without drawing from your credit pool. Only switch to a specific premium model when you have a task that genuinely requires the highest reasoning quality — complex algorithmic problems, security audits, architecture decisions. For most routine coding tasks, Auto mode is as good or better.

@ references are your most powerful tool. Type @ in the chat to reference specific files, folders, documentation URLs, GitHub issues or even web pages. The more precise your context, the better the output. Instead of saying "fix the login issue", say "@auth.js @login-route.js fix the session handling bug that causes logout on page refresh."

Review every diff before accepting. Cursor shows you exactly what it changed in a diff view. Read it. The AI is right most of the time but wrong sometimes. Accepting changes without reading them is how subtle bugs accumulate. The review step is fast — 30 seconds — and catches problems that would take an hour to find later.

Create .cursorrules immediately. Before you do anything else on a project, create a .cursorrules file. Even five lines — language, framework, naming convention, testing library — transforms the quality of every subsequent output. The difference is significant and the investment is two minutes.

Background agents for long tasks. For tasks that will take more than a few minutes — writing a full test suite, refactoring a large module, implementing a feature — use background agents (Pro+ and above). The agent works independently in a cloned version of your repository. You come back to a pull request to review. You are not blocked while it works.

Index your documentation. Use @docs in the chat to add your framework's official documentation as context. For example, @docs:https://nextjs.org/docs gives Cursor access to Next.js documentation when answering questions about Next.js. This dramatically reduces hallucination on framework-specific questions.

Cursor vs GitHub Copilot — which one?

This is the most common comparison developers make. The short version: GitHub Copilot is better if you need to stay in your existing IDE (especially JetBrains). Cursor is better if you want the full AI coding experience and are willing to use a standalone editor.

GitHub Copilot costs $10 per month for individuals versus $20 for Cursor Pro. Copilot works as an extension inside VS Code, JetBrains IDEs, Neovim and others. Cursor is a standalone editor only.

On autocomplete quality, most developer surveys and independent tests in 2026 rate Cursor's Tab completion as the best available. On agent mode, Cursor's background agents — which work autonomously on a cloned repo and return a pull request — have no direct equivalent in Copilot.

If you only need autocomplete and basic chat, the $10 Copilot plan is a reasonable choice. If you want agent mode, multi-file editing with full codebase context and the ability to delegate entire features to an autonomous AI, Cursor is the current market standard.

Architecture — how Cursor works under the hood

Cursor is a fork of Visual Studio Code maintained by Anysphere, a San Francisco startup founded in 2022 and backed by Y Combinator. It received a $2.3 billion Series D funding round in November 2025 at a valuation of $29.3 billion, according to Wikipedia's documentation of the company.

The fork maintains compatibility with the VS Code extension marketplace, keybinding system and theme engine while replacing the underlying AI integration with Cursor's own infrastructure. Extensions, themes and settings from VS Code work without modification.

Codebase indexing and retrieval

When you open a project, Cursor indexes your codebase using an embedding model. Each file is converted to a high-dimensional vector representation. When you make an AI request, Cursor performs semantic search across these embeddings to retrieve the most relevant files and code sections — a system Cursor calls "codebase embedding". According to Cursor's official product documentation, "Cursor's codebase embedding model gives Agent deep understanding and recall."

File paths are encrypted using client-generated keys during indexing and plaintext code is discarded after embeddings are computed. This is documented in Cursor's official security documentation.

Multi-model architecture

Cursor does not use a single AI model. It uses different models for different tasks:

  • Tab completion — a proprietary fast autocomplete model built by Cursor specifically for low-latency inline suggestions
  • Auto mode — Cursor's routing system selects the most cost-efficient model appropriate for the complexity of each request
  • Premium model selection — Claude Sonnet 4.6, Claude Opus 4.6, GPT-5.4, Gemini 3 Pro, Grok Code and others, selectable per request and billed from the monthly credit pool

As of April 2026, Cursor's feature page lists supported models including GPT-5.2, Claude Sonnet 4.5, Claude Opus 4.5, Gemini 3 Pro and Grok Code, with Auto mode as the default.

Agent architecture — Composer 2

Cursor 3.0 introduced Composer 2, described in Cursor's official research blog as a "technical report on Composer 2" published March 2026. The agent architecture allows autonomous multi-step task execution including:

  • Reading and writing files across the project
  • Running terminal commands and observing output
  • Opening and interacting with a built-in browser for local web applications
  • Running up to 8 background agents in parallel on cloud infrastructure
  • Using an Await tool that allows agents to wait for background shell commands to complete or specific output to appear

Background agents clone the repository to cloud infrastructure, work independently and return pull requests for human review — documented in Cursor's official changelog.

MCP support

Cursor supports the Model Context Protocol (MCP), an open standard for connecting AI models to external tools and data sources. MCP connections allow Cursor agents to interact with databases, APIs, internal tools and third-party services without exposing sensitive credentials in prompts. As of the April 8 2026 changelog, MCP Apps support structured content enabling richer tool outputs.

Security and enterprise compliance

Cursor is SOC 2 certified, documented on Cursor's official security page. Privacy Mode, when enabled by a user or team administrator, guarantees that no code data is stored by model providers or used for training. The platform supports SAML-based SSO and SCIM provisioning for enterprise deployments. Enterprise plans add AI code audit logs, pooled usage and detailed admin controls.

Pricing model — credit system (since June 2025)

Cursor changed its pricing model in June 2025 from request-based to credit-based. Each paid plan includes a monthly credit pool equal to the plan price in US dollars. Credits deplete at different rates depending on which AI model is selected. Auto mode is unlimited and does not draw from the credit pool. The practical implication, documented across multiple independent analyses, is approximately 225 Claude Sonnet requests or 550 Gemini requests from the $20 Pro credit pool per month.

Pricing tiers as of April 2026 per cursor.com/pricing:

  • Hobby: Free, no credit card, 2,000 Tab completions, 50 slow premium requests
  • Pro: $20/month ($16 annual), unlimited Tab, unlimited Auto, $20 monthly credit pool
  • Pro+: $60/month, 3× credits
  • Ultra: $200/month, 20× credits, priority access to new features
  • Teams: $40/user/month, Pro-equivalent plus centralised billing, SSO, admin controls
  • Enterprise: Custom pricing, pooled usage, SCIM, audit logs, priority support

Official sources

Primary sources cited in this guide