Skip to content
explore
Cursor logo

Cursor

Visit Cursor

AI coding agent for building software in your editor, terminal, and IDE.

CodingAgents

How it works / How to use

AI coding agent for building software in your editor, terminal, and IDE. Open a project folder, use Agent (Cmd+I / Ctrl+I) to search the codebase and apply edits, Tab for inline suggestions, and cloud agents at cursor.com/agents when you want work to run outside the editor. Usage limits depend on your plan.

  1. Install Cursor, sign in, and open your project with File > Open Folder.
  2. Press Cmd+I (Mac) or Ctrl+I (Windows/Linux) to open Agent and describe the task in plain language.
  3. Review diffs as Agent edits files; reject anything you do not want before moving on.
  4. Use @ to point Agent at specific files or folders when you already know where the change belongs.

Agent mode: build, refactor, and fix

Open Agent, describe the outcome—not only the implementation—and let Agent search the codebase, edit files, and run terminal commands when needed.

What to provide

  • The feature, bug, or refactor you want
  • Expected behavior and files you know are involved
  • Constraints: libraries, style, tests, or areas not to touch

Details that improve the result

  • Agent can build features, refactor, fix bugs, write tests, and run shell commands
  • Edits appear in the diff view as they happen
  • Start a new chat when switching tasks; modes use separate context

Example prompt

Add a login form to the homepage with email and password fields, client-side validation, and a unit test. Use existing Button and Input components in src/components/ui/. Do not change auth middleware yet.

If the first output is not good

  • “Fix only the validation message copy; keep layout.”
  • “Show the failing test output and patch the minimal fix.”
  • “Revert the API change; keep the UI work.”

Common mistakes

  • Vague requests like “make it better” with no acceptance criteria
  • Letting large diffs land without reading them
  • Mixing unrelated tasks in one Agent session

Ask mode: understand without editing

Switch to Ask mode when you want read-only exploration. Agent answers questions without modifying files.

What to provide

  • The code area or concept you want explained
  • Your familiarity level with the stack
  • Whether you want architecture, data flow, or line-by-line detail

Details that improve the result

  • Ask is read-only—use it to explore before changing code
  • Press Shift+Tab to cycle modes from the Agent input
  • Use @ references to focus on specific files

Example prompt

In Ask mode: explain how authentication flows from src/app/login/page.tsx through the API route to the database. Assume I am new to this codebase.

If the first output is not good

  • “Diagram only the happy path.”
  • “Where would I add OAuth—list files, do not edit.”
  • “Compare this pattern to src/lib/auth.ts.”

Common mistakes

  • Staying in Ask when you actually want edits applied
  • Asking about the whole repo without scoping to a folder
  • Expecting Ask to run terminal commands

Plan mode: review before building

Switch to Plan mode (Shift+Tab). Agent asks clarifying questions, researches the repo, and produces a reviewable plan before writing code.

What to provide

  • A complex feature or multi-file change
  • Requirements, constraints, and open questions
  • Areas of the codebase you suspect are involved

Details that improve the result

  • Plan mode suits unclear requirements and architectural decisions
  • Edit the plan in chat or markdown before clicking build
  • If the build misses the mark, revert and refine the plan instead of long fix-up prompts

Example prompt

Plan mode: add role-based access control for admin vs member users. Include middleware, database changes, and UI gating. List migration risks before implementation.

If the first output is not good

  • “Add explicit file paths to each plan step.”
  • “Split phase 2 into a separate plan for billing hooks.”
  • “Save the plan to the workspace before building.”

Common mistakes

  • Using Plan for a one-line typo fix
  • Building without reading the generated plan
  • Trying to fix a wrong implementation with many follow-ups instead of revising the plan

Tab completion while coding

Type normally; accept gray inline suggestions with Tab, word-by-word with Cmd/Ctrl+Arrow Right, or reject with Escape.

What to provide

  • The file and surrounding code context
  • Recent edits Tab should continue from
  • Linter errors you want addressed inline

Details that improve the result

  • Tab suggests based on recent edits, surrounding code, and linter errors
  • Tab can edit multiple lines, add imports, and suggest cross-file updates
  • After accepting, press Tab again for jump-in-file to the next predicted edit location

Example prompt

Implement a new `formatCurrency` helper in utils.ts; accept Tab suggestions for imports and matching call sites when the portal appears for other files.

If the first output is not good

  • Snooze Tab temporarily from the status indicator if suggestions distract
  • Disable Tab for file types like markdown in settings when not needed
  • Remap Accept Cursor Tab Suggestions in keyboard shortcuts if desired

Common mistakes

  • Accepting multi-line Tab changes without reading them
  • Leaving Tab enabled globally when pairing on sensitive files
  • Ignoring cross-file portal hints when renaming symbols

Debug mode for tricky bugs

Switch to Debug mode for bugs that need runtime evidence. Agent uses debugging workflows to investigate before patching.

What to provide

  • Steps to reproduce and expected vs actual behavior
  • Error logs, stack traces, and environment details
  • What you already tried

Details that improve the result

  • Include exact error text and line numbers
  • Say whether the bug is intermittent or consistent
  • Debug mode can edit files after investigation—review diffs carefully

Example prompt

Debug mode: this React component re-renders infinitely in development. Expected fetch once on mount. Actual fetch loops. Component and console output attached via @Component.tsx.

If the first output is not good

  • “Add logging only; no fix yet.”
  • “Propose the smallest fix plus a regression test.”
  • “Explain root cause in two sentences after the patch.”

Common mistakes

  • Pasting only the error string with no code
  • Changing several things at once after the first fix
  • Omitting browser, Node, or OS version when relevant

Context with @ mentions and rules

Type @ in Agent input to attach paths like @auth.ts or @src/components/. Add rules under Cursor Settings > Rules to steer behavior across sessions.

What to provide

  • Files, folders, or docs Agent should prioritize
  • Project rules or conventions (Cursor rules, AGENTS.md)
  • Anything Agent must not modify

Details that improve the result

  • Agent searches automatically, but @ speeds up when you know the locus
  • Rules customize defaults for Agent across the project
  • Combine @ context with explicit “do not edit” paths

Example prompt

@src/lib/db.ts @src/app/api/users/route.ts Add pagination to the users API using existing query helpers. Do not change database schema.

If the first output is not good

  • “Also read @docs/api-conventions.md before editing.”
  • “Limit changes to files under src/features/billing/.”
  • “Follow the test pattern in @src/lib/__tests__/pagination.test.ts.”

Common mistakes

  • Attaching too many @ files and diluting focus
  • Assuming Agent sees uncommitted local secrets you pasted elsewhere
  • Skipping rules for repeated conventions you explain every time

Cloud agents and mobile

Run agents from cursor.com/agents for cloud workflows, or use the Cursor iOS app when documented for your plan. Treat cloud output like local Agent diffs: review before shipping.

What to provide

  • A self-contained task Agent can run in the cloud
  • Repository access and branch expectations
  • Review criteria before merging cloud Agent output

Details that improve the result

  • Cloud agents and automations are listed on paid Individual and Teams plans
  • Hobby includes limited Agent requests
  • Enterprise documents separate SDK and tracking APIs from seat pricing

Example prompt

Cloud agent: add README setup steps for this repo’s dev container, verify commands run, open a PR with only README and devcontainer changes.

If the first output is not good

  • “Re-run with narrower scope: docs only.”
  • “Summarize what changed before I merge.”
  • “Stop if tests fail; do not patch unrelated files.”

Common mistakes

  • Merging cloud Agent changes without local review
  • Assigning vague repo-wide tasks with no stop conditions
  • Assuming unlimited Agent usage on Free/Hobby tiers

Tests, terminal commands, and verification

Tell Agent how to verify work: run tests, lint, or start the dev server. Review terminal commands before they run if your settings require approval.

What to provide

  • Test command or script Agent should run
  • Definition of done for the task
  • Permissions for running commands (approve vs auto-run settings)

Details that improve the result

  • Agent mode can execute shell commands to validate fixes
  • Ask for a regression test when fixing bugs
  • Keep verification steps in the same session as the implementation

Example prompt

Implement the fix, then run npm test -- --testPathPattern=auth and paste failing output if any remain. Do not commit.

If the first output is not good

  • “Add one test that would have caught this bug.”
  • “Run lint on changed files only.”
  • “Stop after tests pass; I will commit manually.”

Common mistakes

  • Declaring done without running tests
  • Allowing broad destructive commands without review
  • Fixing symptoms while skipping reproduction steps

How to prompt

Cursor Agent works best with outcome-focused requests: what should exist, how to verify it, and what not to touch. Use @ for known files, pick the right mode, and review diffs continuously.

Task: add dark mode toggle to settings page.
Context: @src/app/settings/page.tsx @src/components/ui/switch.tsx
Done when: toggle persists in localStorage and existing tests pass.
Do not: change global CSS variables outside settings.

State acceptance criteria

Say what “done” means: tests passing, UI behavior, or files touched. Agent uses this to know when to stop.

Example

Add export to CSV on the reports table. Done when unit test in reports.test.ts passes and only src/features/reports/* changes.

Scope with @ references

Point Agent at the exact files or folders to read first when you already know where work belongs.

Example

@src/server/auth/ Implement refresh token rotation using the pattern in @src/server/auth/session.ts.

Pick the mode for the job

Agent for edits, Ask for exploration, Plan for large features, Debug for runtime bugs. Shift+Tab cycles modes.

Example

Plan mode first: outline database migration for multi-tenant billing, then build after I approve the plan.

Protect areas explicitly

List directories, APIs, or behaviors that must not change to prevent drive-by refactors.

Example

Fix the checkout bug in @src/cart/ only. Do not modify payment provider SDK code or pricing tables.

Review diffs incrementally

Reject bad hunks early. Smaller follow-ups beat letting Agent stack unrelated fixes.

Example

Keep the API change; revert the unrelated formatting edits in utils.ts.

Best output tips

Install and sign in first

Download from cursor.com/download, install for your OS, sign in, then use File > Open Folder so Agent indexes the project you care about.

Open Agent with Cmd+I or Ctrl+I

The Agent panel is the main surface for multi-file edits, terminal commands, and autonomous exploration.

Choose the right mode

Agent edits files. Ask is read-only. Plan drafts an implementation plan for approval. Debug targets bugs needing runtime evidence. Shift+Tab cycles modes.

Use @ to steer context

Agent searches automatically, but @file or @folder references focus attention when you already know the relevant code.

Write acceptance criteria

Include how to verify success—tests, commands, UI behavior—so Agent knows when the task is complete.

Review diffs continuously

Agent applies edits as it works. Reject incorrect hunks immediately instead of fixing forward through a messy branch.

Start fresh chats for new tasks

Each mode uses its own context. A new chat after finishing a feature keeps prompts focused and reduces confusion.

Use Plan for complex features

When requirements are fuzzy or many files are involved, Plan mode produces a reviewable approach before code lands.

Revert and replan when needed

If Agent built the wrong thing, revert, tighten the plan, and run again—often faster than lengthy fix-up threads.

Leverage Tab for flow state

Tab completes inline from recent edits and linter signals. Accept with Tab, words with Cmd/Ctrl+Arrow Right, reject with Escape.

Follow cross-file portal hints

When Tab suggests updates in another file, use the portal window instead of manually hunting related call sites.

Add project rules once

Cursor Rules encode conventions—testing commands, style, architecture—so you do not repeat them in every prompt.

Run verification commands

Ask Agent to run tests or lint after changes. Confirm commands match your repo scripts before approving execution.

Use cloud agents when appropriate

Paid plans document cloud agents at cursor.com/agents for work outside the local editor. Review output like any other Agent session.

Know plan limits

Hobby has limited Agent requests; Pro and higher expand included model usage. Cloud agents and automations vary by Individual and Teams plans.

  • Open the project folder first—Agent needs the codebase on disk.
  • Use Cmd+I / Ctrl+I for Agent; Shift+Tab to switch Ask, Plan, Debug, or Agent.
  • Type @ to attach files or folders when you know where to work.
  • Describe outcomes and verification steps, not only implementation guesses.
  • Review every diff; reject hunks you do not understand before continuing.
  • Start a new Agent chat when switching to an unrelated task.
  • Use Tab for inline completions; accept word-by-word when only part of a suggestion fits.
  • Check your plan for Agent, cloud agent, and model usage limits before long sessions.

Try this AI

Try Cursor

Product Details

Pricing, features, limits and latest updates

Cursor

AI coding agent for building software in your editor, terminal, and IDE.

Free / Paid · Free

Pricing Plans

Hobby

Free

Pro

$20/ Monthly

Pro+

$60/ Monthly

Ultra

$200/ Monthly

Teams Standard

$40/ Monthly

Teams Standard

$384/ Yearly

Teams Premium

$120/ Monthly

Teams Premium

$1,152/ Yearly

Enterprise

Custom

Key Features

Chat

Agent chat with @ mentions, project rules, and codebase context; cloud agents and automations are plan-gated (Cursor Help Center).

API

Cloud agents and the Cursor SDK are documented separately from seat pricing; Enterprise lists an AI code tracking API.

Automation

Cloud agents and automations are listed on paid Individual and Teams plans.

Agents

In-editor Agent and cloud agents are included; Hobby has limited Agent requests.

Limits

  • Pro Other Models pool: 20 USD/month. Included third-party model usage on Pro, reset monthly with billing cycle (Cursor pricing docs).
  • Rules scope: Project and user rules apply to Agent modes; Tab completion does not use rules (Cursor Help Center).

Ideas / Prompt experiences

Share a prompt that worked for you. Username and email are shown with your submission. External links are not allowed.

Example prompt

Agent task with file context

Prompt

Goal: Fix the failing auth test in src/lib/auth.test.ts. Constraints: - Do not change public API signatures - Run npm test -- --testPathPattern=auth after edits Start by reading the test file and the module it imports.

Short explanation

Cursor Agent works best with a single goal, explicit constraints, and @ mentions to the files that should change.

Example prompt

Refactor with plan first

Prompt

Plan mode: Propose a minimal refactor to extract duplicate validation logic from src/components/checkout-form.tsx and src/app/api/checkout/route.ts into one shared helper. List files to touch before editing.

Variation

Implement step 1 only. Keep behavior identical and add one usage example.

Short explanation

Ask/Plan modes are useful when you want a reviewable plan before the agent edits multiple files.

Share your experience

Required fields are marked. Variation, result, and explanation are optional.

You may also like

AutoGPT logo

AutoGPT

Explore

Platform for building and running AI agents with visual Agent Builder, AutoPilot chat, scheduling, and 200+ integration blocks; self-host open source or use hosted Pro/Max plans.

CodingFree / Paid

Hugging Face logo

Hugging Face

Explore

Models, datasets, and inference for open machine learning.

CodingFree / Paid

v0 logo

v0

Explore

Build full-stack web apps from prompts with AI-generated code, preview, and deploy.

CodingFree / Paid

Back to Explore