What Is Cursor AI and Why Use It in 2026?

Cursor AI is an AI-native code editor built by Anysphere as a direct fork of VS Code, meaning it looks and feels like the editor you already know but replaces every edit surface with AI capabilities. As of 2026, Cursor has crossed 1 million users and 360,000 paying customers — including teams at over 50% of Fortune 500 companies — making it the fastest-adopted developer tool since GitHub Copilot. Version 3.0 shipped Background Agents, Cloud Agents for Business teams, and Composer 2.0, which can coordinate changes across dozens of files in a single guided session. The editor supports macOS 12+, Windows 10+, and Linux, and costs $0 on the free tier (2,000 AI completions/month) or $20/month for Pro with unlimited fast requests. The core value proposition: instead of switching between your editor and a chat window, every interaction — completion, refactoring, debugging, testing — happens inline without context-switching.

System Requirements and Prerequisites

Before downloading, confirm your environment meets the minimum spec. Cursor v3.0 requires macOS 12 Monterey or later, Windows 10 (64-bit) or later, or a modern Linux distribution with a supported desktop environment. On RAM, 8 GB is the bare minimum but 16 GB is strongly recommended — Agent Mode and Background Agents spawn sub-processes that hold model context, which adds memory pressure. An SSD is de facto required; Cursor indexes your codebase on first open and reads from that index on every @ mention in Chat. You do not need to install VS Code first — Cursor ships its own Electron runtime. You do need a Cursor account (free to create at cursor.com) to activate the free tier. Teams evaluating the Business tier ($40/user/month) should also check IT policy around privacy mode, which prevents code from being stored in Anysphere’s infrastructure.

Step 1: Download and Install Cursor

Cursor’s installation follows the same pattern as any desktop app, and the full process takes under five minutes from download to first file open. Navigate to cursor.com, click Download, and the site auto-detects your OS and serves the right binary. The macOS installer is a standard .dmg; drag Cursor.app to Applications. On Windows, run the .exe installer with default options — Cursor adds itself to PATH automatically so you can launch it with cursor . from any terminal. On Linux, download the .AppImage, run chmod +x cursor-*.AppImage, and execute it directly; no root access or system-level install is needed, which makes it portable across machines. After first launch, Cursor prompts you to sign in or create a free account at cursor.com — the sign-up takes about 60 seconds. The free tier activates immediately with no credit card required: you get 2,000 fast AI completions and 50 slow requests per month, which is enough to evaluate all the core features. Once authenticated, you land in the welcome flow, which offers to import your VS Code settings and extensions. Accept this step — it’s covered in detail in Step 2. You’ll configure the AI model selection in Step 3.

Step 2: Import VS Code Settings and Extensions

Cursor reads your VS Code configuration directly from disk, so the transition is near-instant. In the welcome modal, click “Import VS Code Settings.” Cursor locates your VS Code settings.json, keybindings.json, and installed extensions and copies them into its own profile directory. Extensions that depend on the VS Code extension API work unchanged — language servers, linters, formatters, Git integrations, theme packs. Extensions that call VS Code-proprietary APIs (a small minority) may not load; Cursor logs these in the Output panel under “Extensions.” After import, open any project you were working on in VS Code and the experience should be identical — same file tree, same color scheme, same shortcuts — plus the new AI sidebar on the left. If you don’t have a VS Code installation to import from, skip this step; Cursor’s defaults are sensible.

Step 3: Configure AI Models for Different Tasks

Cursor routes requests to different models depending on the task type, and configuring this correctly is the single highest-leverage setup step. Open Settings (Cmd/Ctrl + ,) and navigate to Cursor > Models. For Tab Completion — low-latency predictions that fire on every keystroke — use a fast small model: Cursor’s default cursor-small is purpose-built for sub-100ms latency. For Chat and Composer, where you’re asking questions or orchestrating multi-file edits, route to a frontier model: Claude Sonnet 4.6 is the 2026 default for most teams because it balances reasoning quality with speed. For Agent Mode tasks that run autonomously over many steps, Claude Opus 4.7 or GPT-4o give better multi-step coherence. You can also connect your own API keys for OpenAI, Anthropic, or Google under Cursor > AI Keys — useful for Business teams that need per-org billing or want to use models not in Cursor’s default list. Set a monthly spend cap under Cursor > Billing to avoid surprises.

Step 4: Master Tab Completion with Multi-Line Predictions

Cursor’s Tab Completion is the feature most developers notice first — and it behaves differently from GitHub Copilot’s single-line suggestions. Cursor predicts multi-line completions and adapts them to the exact cursor position, surrounding code, and recent edits within the file. The key interaction model: start typing, see the grey ghost text, press Tab to accept the full suggestion, or Ctrl+Right to accept one word at a time. Press Esc to dismiss. If the suggestion is wrong, just keep typing — Cursor re-predicts within ~200ms. Practical technique: write a comment explaining what you want (// fetch user by email, return null if not found), then press Enter and Tab. Cursor often generates the entire function body. For repetitive patterns — adding type annotations, writing test cases for a new function — let Tab Completion do the structural work while you focus on correctness. The free tier allows 2,000 completions/month; Pro gives unlimited fast completions.

Step 5: Inline Editing with Cmd+K

Inline editing via Cmd+K (Mac) or Ctrl+K (Windows/Linux) is Cursor’s most surgical AI tool. Select any code, press the shortcut, and a small prompt bar appears inline — no chat panel, no context switch. Type your instruction (“make this async”, “add error handling”, “rename all params to camelCase”, “convert to TypeScript”) and press Enter. Cursor streams the edit directly into the selected region with a diff view — green for additions, red for deletions. Press Tab to accept or Esc to reject. For whole-file operations without a selection, press Cmd+K with nothing selected; Cursor operates on the visible viewport. Practical patterns: highlight a function and ask “add JSDoc with param types,” select a SQL query and ask “rewrite as parameterized to prevent injection,” or select a test file and ask “add edge cases for null and empty inputs.” Cmd+K round-trips in ~2–5 seconds for most edits, making it faster than opening a separate chat for small transformations.

Step 6: Chat with Codebase Context Using @Mentions

Cursor’s Chat panel (Cmd+L) is a conversation interface with full codebase awareness via the @ mention system. Unlike generic chatbots, Chat knows about your repo structure because Cursor indexes it locally on first open. Type @ to see a menu of mentionable context types: @Files for specific files, @Folders for directories, @Codebase for a semantic search across the whole repo, @Docs for framework documentation, @Web for live web search, and @Git for recent diffs and commit history. Practical example: @Codebase how does authentication middleware work in this project? returns a grounded answer pointing to actual file paths, not generic advice. Use Chat for orientation questions (“what does this function call chain do?”), architecture decisions (“should I put this in a service or a hook?”), and code review ("@Files src/api/users.ts review this for security issues"). Chat messages persist in a session thread; start a new chat (Cmd+Shift+L) when switching topics to avoid polluting context.

Step 7: Build Multi-File Features with Composer 2.0

Composer 2.0 (Cmd+I) is Cursor’s answer to multi-file AI editing — it can open, read, modify, and create files across your entire project in a single guided session. Describe a feature at a high level (“add a password reset flow with email verification, a reset token model, and two new API routes”) and Composer generates a plan, lists the files it will touch, and asks for confirmation before writing. You review each change as it streams in, can edit the prompt mid-session to redirect (“actually store the token in Redis, not the database”), and accept or reject per-file. Composer 2.0 improvements over v1: better plan coherence across more than 10 files, checkpoint saves so you can roll back to any step, and integration with Agent Mode for tasks that require running commands. Use Composer for new features, large refactors, and test generation across multiple files. Avoid it for tiny changes — Cmd+K is faster for single-function edits.

Step 8: Set Up .cursorrules for Persistent Project Context

.cursorrules is a plain text file at your project root that Cursor injects into every AI request as system context. Think of it as a persistent prompt that keeps the AI aligned with your project conventions without you repeating them in every chat. Create the file at <project-root>/.cursorrules and write your rules in plain English. Effective rules are specific: instead of “write good code,” write “use TypeScript strict mode, never use any, prefer Result<T, E> types over throwing exceptions, and follow the repository pattern for all database access.” Include stack-specific rules: “this project uses Prisma for ORM, not raw SQL,” “always use React Query for server state, never useEffect for fetching,” “tests use Vitest and Testing Library, not Jest.” Teams should version-control .cursorrules and treat it like a CONTRIBUTING.md that the AI also reads. After saving the file, restart Chat or Composer to pick up the new rules — they don’t hot-reload mid-session in v3.0.

Step 9: Use Agent Mode for Autonomous Task Execution

Agent Mode is Cursor’s highest-autonomy feature — it gives the AI control of the terminal, file system, and editor to complete tasks end-to-end without step-by-step confirmation. Enable it in Composer by toggling “Agent” in the dropdown, or open the dedicated Agent panel. In Agent Mode, Cursor can run shell commands (npm install, git commit, python script.py), read command output, react to errors by editing code and retrying, and loop until the task succeeds or hits a limit. A practical workflow: “set up a new Express API project with TypeScript, ESLint, Prettier, and a health-check endpoint, then run the tests to verify.” Agent Mode handles everything — scaffolding, dependency install, config files, test execution. Guardrails: Agent Mode asks for permission before destructive operations (deleting files, force-pushing) by default. For production work, keep terminal sandboxing on and review the command log after each session. Background Agents (Business tier) run the same way but in Anysphere’s cloud infrastructure, freeing your local machine.

Step 10: Debug and Test with AI Assistance

Cursor integrates AI into the debugging loop in two useful ways. First, when your terminal shows an error, paste it into Chat with @ pointing to the relevant file: @Files src/server.ts TypeError: Cannot read properties of undefined (reading 'id') — what's wrong? Cursor analyzes the stack trace, locates the code path, and proposes a fix you can apply with one click. Second, use Composer to generate test suites: select a module and ask “write unit tests covering the happy path, null inputs, and network error cases.” Composer generates the test file, runs it with your test runner if Agent Mode is on, and fixes failures automatically. For integration tests that require a database, tell Composer explicitly: “use a test database connection from the TEST_DATABASE_URL env var.” Test generation quality is highest when .cursorrules specifies your test framework (Vitest, Jest, Pytest, etc.) so Cursor uses the right APIs from the start.

Step 11: Integrate with Git and Terminal

Cursor’s terminal is the standard VS Code integrated terminal — Cmd+\`` opens it — with one addition: the AI terminal command feature. Press Cmd+Kinside the terminal to describe what you want to do ("list all branches merged in the last 7 days and delete the ones not on main") and Cursor translates it to a shell command for review before execution. You can reject, edit, or run the command. For Git workflows, Cursor's Source Control panel (the branch icon in the left sidebar) adds AI-generated commit messages: stage your changes, click the sparkle icon in the commit message box, and Cursor summarizes the diff into a conventional commit message. For PR descriptions, use Chat with@Git diff mainto get a summary of all changes since your branch diverged. If your team uses GitHub Actions or GitLab CI, store pipeline configs in the repo and reference them in.cursorrules` so Cursor understands your CI constraints when generating code.

Step 12: Optimize Performance and Keyboard Shortcuts

Performance tuning and shortcut fluency separate power users from beginners. For indexing performance: open Settings > Cursor > Indexing and add node_modules, dist, .next, and any large generated directories to the ignore list. Large ignored directories speed up both indexing and @Codebase search significantly. For model routing: if you notice Chat responses are slow, switch the Chat model from Opus to Sonnet for a 3–4x speed improvement on most queries. For keyboard shortcuts, the five highest-ROI bindings to memorize are: Cmd+K (inline edit), Cmd+L (open Chat), Cmd+I (open Composer), Cmd+Shift+L (new Chat thread), and Tab (accept completion). You can customize all of these in Preferences > Keyboard Shortcuts. For teams, share a keybindings.json in the repo alongside .cursorrules so everyone uses consistent bindings.

Pricing Breakdown: Free vs Pro vs Business (2026)

Cursor’s pricing in 2026 reflects its position as a productivity tool rather than a toy. The free tier is genuinely useful — 2,000 fast AI completions/month and 50 slow requests covers light personal projects. Pro at $20/month removes most limits: unlimited fast completions, 500 fast Composer requests, and access to all frontier models. Business at $40/user/month adds privacy mode (code never leaves your org), SSO/SAML, centralized billing, audit logs, and Cloud Agents. Most individual developers land on Pro. Teams that process proprietary code or work in regulated industries (finance, healthcare, defense) need Business for the privacy guarantees.

5 Common Cursor Pitfalls and How to Avoid Them

1. Accepting completions without reading them. Tab Completion is fast but not infallible. Pause for one second before accepting multi-line suggestions, especially in security-critical code (auth, input validation, SQL). Use Ctrl+Right to accept word-by-word when unsure.

2. Not setting .cursorrules. Without project context, Cursor defaults to generic patterns that may conflict with your stack. The first 30 minutes you invest in a good .cursorrules file returns hours of avoided corrections.

3. Using Composer for tiny edits. Composer’s strength is multi-file coordination. For single-function changes, Cmd+K is 5x faster. Match the tool to the scope.

4. Running Agent Mode without reviewing the command log. Agent Mode is powerful but can install unexpected packages or modify config files. Review the terminal log after every agent session before committing.

5. Ignoring the @Codebase context type. Most beginners chat without @ mentions and get generic answers. Adding @Codebase or @Files turns generic advice into project-specific guidance grounded in your actual code.

Troubleshooting Common Issues

Cursor won’t index my codebase. Check Settings > Cursor > Indexing > Ignored Paths. If node_modules or a large generated directory is being indexed, the indexer stalls. Add the directory to the ignore list and trigger a manual reindex via Command Palette > “Cursor: Reindex Codebase.”

Tab Completion stopped working. First check your free tier usage — 2,000 completions/month resets on the billing date, not the calendar month. Open Cursor’s account dashboard to verify. If usage is fine, toggle the completion model in Settings and back again to reset the connection.

Composer applies changes to the wrong files. This usually means Cursor’s @Codebase index is stale. Reindex (Command Palette > “Cursor: Reindex Codebase”) and retry. Also verify .cursorrules doesn’t have contradictory file path instructions.

Agent Mode terminal commands fail silently. Check that your shell profile (.zshrc, .bashrc) is sourced in non-interactive shells. Some tools (nvm, pyenv, rbenv) only activate in interactive shells. Add explicit source ~/.zshrc at the top of Agent Mode sessions or configure Cursor to use your full shell path.

Advanced Tips for Power Users

Multi-root workspaces: Open multiple related repos in one Cursor window via File > Add Folder to Workspace. @Codebase searches across all roots, and Composer can edit files in any root. Useful for monorepo setups where the API and frontend are separate repos.

Model routing by file type: In Settings > Cursor > Models, you can assign different models per language. Use a smaller, faster model for plain-text files (markdown, JSON config) and reserve frontier models for TypeScript/Python where reasoning quality matters.

MCP integrations: Cursor v3.0 supports Model Context Protocol servers — plugins that extend Chat and Agent Mode with external tool access (GitHub PRs, Linear tickets, Notion docs, database queries). Install community MCP servers from the Cursor marketplace or write your own using the MCP SDK.

Shared team .cursorrules: For larger teams, store project-specific rules in .cursorrules at the repo root and personal preferences in ~/.cursor/rules/global.md. Both are merged at request time — project rules take precedence on conflicts.

FAQ

Is Cursor AI free to use? Yes. The free tier gives 2,000 fast AI completions and 50 slow requests per month, which covers light personal use. Pro ($20/month) removes most limits and is what most active developers use.

Does Cursor replace VS Code completely? Cursor is a fork of VS Code, so it retains all VS Code functionality — extensions, keybindings, themes, language servers. You can import your VS Code settings with one click. Most developers use Cursor as a drop-in replacement and don’t keep VS Code installed.

Is my code sent to Anysphere’s servers? On the free and Pro tiers, code snippets and context are sent to AI model providers (Anthropic, OpenAI) to generate responses. Anysphere states it does not train on user code. The Business tier adds Privacy Mode, which routes requests through an isolated pipeline with contractual guarantees that code is not retained.

Can I use my own OpenAI or Anthropic API key? Yes. Under Settings > Cursor > AI Keys, you can add your own API keys for OpenAI, Anthropic, or Google. This lets you use models not in Cursor’s default list and bills usage directly to your API account rather than your Cursor subscription.

How is Cursor different from GitHub Copilot? Copilot is a VS Code extension that adds single-line completions and a chat sidebar. Cursor is a full editor fork with multi-line Tab Completion, Cmd+K inline editing, Composer 2.0 for multi-file features, and Agent Mode for autonomous task execution. Cursor’s context system (@Codebase, @Git, @Docs) is also significantly more powerful than Copilot’s workspace context.

What Makes Windsurf Different From Other AI Editors?

Windsurf is an AI-native IDE built around Cascade, an autonomous agent that can plan multi-step workflows, execute terminal commands, read files across your entire repo, and iterate without waiting for step-by-step instructions. By March 2026, Windsurf had 1M+ active users generating 70M+ lines of AI-written code per day, with 94% of its code output being AI-generated. Unlike GitHub Copilot (which autocompletes inline) or Cursor (which focuses on precision edit suggestions), Windsurf’s core value proposition is agentic autonomy: describe an outcome, and Cascade plans and executes the path to get there. ServiceNow deployed Windsurf across ~7,000 engineers and saw a 10% productivity boost. The fundamental distinction is philosophy — Windsurf optimizes for “describe what you want” workflows, while Cursor optimizes for “precise, surgical edits.” If your team produces greenfield features or prototypes frequently, Windsurf’s architecture pays off. If you do mostly targeted refactors on large mature codebases, the tradeoff is different.

System Requirements Before You Install

Before downloading, confirm your machine meets the minimum specs. Windsurf runs on any modern hardware but performs noticeably better with adequate RAM. The tool’s idle memory footprint is ~1.1GB and cold start time is approximately 3.4 seconds on a modern machine — the AI completion latency runs 102ms, fast enough that it doesn’t interrupt flow. On 8GB RAM machines running Codebase context mode on large repos, expect slowdown during the initial embedding scan because Windsurf indexes your entire repository before enabling full multi-file awareness.

Minimum requirements:

• macOS: OS X Yosemite (10.10) or later
• Windows: Windows 10 64-bit or later
• Linux: Ubuntu 18.04+ or equivalent glibc 2.17+ distribution
• RAM: 8GB minimum
• RAM: 16GB recommended if you plan to use Codebase context mode on projects over 10k lines

If you’re on 8GB RAM and plan to run Codebase context mode on large repos, expect some slowdown during the initial embedding scan. You can work around this with a .codeiumignore file to exclude node_modules, dist, .git, and other large generated directories from the index.

Step 1: Download and Install Windsurf

Download Windsurf from the official site (windsurf.com) for your platform. All three major platforms are supported with native packages. Installation is straightforward but there are a few platform-specific gotchas worth knowing before you start, particularly on macOS where Gatekeeper may block the first launch and on Linux where the apt repository setup requires a few extra commands.

macOS:

brew install --cask windsurf

Or download the .dmg directly. If macOS Gatekeeper blocks the app on first launch, go to System Settings → Privacy & Security and click “Open Anyway.” This is expected for apps downloaded outside the App Store.

Ubuntu / Debian Linux:

# Add the Codeium apt repository
curl -fsSL https://windsurf-stable.codeiumdata.com/wVxQEIWkwPUEAGf3/windsurf.gpg \
  | sudo gpg --dearmor -o /usr/share/keyrings/windsurf-stable-archive-keyring.gpg

echo "deb [signed-by=/usr/share/keyrings/windsurf-stable-archive-keyring.gpg arch=amd64] \
  https://windsurf-stable.codeiumdata.com/wVxQEIWkwPUEAGf3/apt stable main" \
  | sudo tee /etc/apt/sources.list.d/windsurf.list > /dev/null

sudo apt-get update && sudo apt-get install windsurf

Windows: Download the .exe installer from windsurf.com and run it. Windsurf installs to %LOCALAPPDATA%\Programs\Windsurf by default.

Step 2: Complete the Onboarding Flow

When Windsurf launches for the first time, it walks you through a 4-step onboarding that sets up your core preferences. This is worth doing carefully — the choices here save you configuration time later. The onboarding sequence takes about 3-5 minutes, and you can import your existing VS Code or Cursor setup at this stage rather than rebuilding your configuration from scratch. Windsurf copies your extensions list, keybindings, and settings.json automatically during the import, which means most developers are functional within minutes rather than spending an hour reconfiguring their environment.

Onboarding steps:

1. Setup path — Choose one: “Start fresh,” “Import from VS Code,” or “Import from Cursor.” If you’re migrating, pick the import option.
2. Theme selection — Dark, light, or high-contrast. This can be changed anytime.
3. Keybindings — Choose VS Code keybindings (default) or Vim bindings. Vim users: select this now.
4. Account creation / login — Sign up for a free account at codeium.com or log in. The free tier gives you 25 Cascade flow actions per month.

If you skipped the VS Code import during onboarding, trigger it afterward via the Command Palette (Cmd+Shift+P / Ctrl+Shift+P): search “Import VS Code Settings.” Note that other AI completion extensions (GitHub Copilot, Tabnine) and proprietary language server extensions are incompatible with Windsurf and will be flagged during import.

Step 3: Create Your .windsurfrules File

The .windsurfrules file is the single highest-leverage configuration in Windsurf. It lives at your project root and tells Cascade your stack, coding conventions, file structure boundaries, and constraints — before every single prompt. Teams that skip this file spend 2-3x more tokens repeating context. Teams that write a good .windsurfrules file cut their prompt length in half and see dramatically more consistent output from Cascade. Think of it as a permanent system prompt that applies to every Cascade interaction in your project. Unlike one-off instructions in a chat window, .windsurfrules is committed to git, visible to your whole team, and applied automatically without requiring anyone to remember to include it.

Create it at your project root:

touch .windsurfrules

A practical starter template for a Node.js/TypeScript project:

The more specific your rules, the better Cascade’s output. Include your exact library versions, the things your team has decided never to do, and where each concern lives in the repo.

Step 4: Configure Cascade Context Mode

Cascade has three context modes that control how much of your codebase it reads before generating. Choosing the wrong one is the most common reason Windsurf feels slow or produces inaccurate suggestions. The default is File mode — Cascade reads only your currently open file — which is deliberately conservative. For most real development work where features span multiple files, you’ll want to switch to Codebase mode. The mode you choose has a direct impact on both response quality and machine performance, so understanding the tradeoffs before you start using Cascade seriously is worth 5 minutes of your time.

To set context mode: Open Cascade panel (Cmd+L / Ctrl+L), click the context dropdown at the top.

For projects under 50k lines, switch to Codebase mode. The first time you do this, Windsurf scans and indexes your repo — 30-120 seconds depending on size. After that, index updates are incremental.

On repos over 50k lines or on 8GB RAM machines, use explicit @file references instead: @src/auth/middleware.ts update this to support OAuth2 PKCE flow.

Step 5: Run Your First Cascade Flow

A Cascade Flow is a multi-step agentic task. You describe the outcome; Cascade reads the relevant files, writes a plan, executes it across multiple files, runs tests, fixes failures, and reports back. Open the Cascade panel with Cmd+Shift+L (macOS) or Ctrl+Shift+L (Windows/Linux). The key shift in mindset from Copilot or Cursor is that you stop describing steps and start describing end states. In benchmarks from devtoolsreview.com, Cascade completed a Redis rate-limiting implementation in 3.5 minutes versus 45-60 minutes manually — reading files, writing middleware, adding env vars, applying routes, writing tests, and fixing test failures autonomously. Cascade works correctly on clearly scoped tasks about 75-80% of the time.

Outcome-first prompt example:

What to avoid: Don’t write step-by-step instructions like “First read middleware.ts, then add a new file…” — Cascade plans steps internally. Describe the end state, not the path.

When Cascade enters a loop (you’ll see it running the same commands repeatedly), interrupt with Cmd+K / Ctrl+K and break the task into smaller pieces.

Step 6: Set Up Memories and Rules for Persistent AI Behavior

Windsurf has two persistence mechanisms beyond .windsurfrules that let you encode preferences once and have Cascade apply them automatically forever after. Memories are personal facts Cascade stores about your working style, stored in your Windsurf account and applying across all your projects. Global Rules are project-agnostic preferences that sit above your .windsurfrules in the priority chain. Together with .windsurfrules, these three layers let you encode your entire development philosophy once and stop repeating yourself every session. Understanding the priority order prevents confusion when Cascade seems to ignore something you’ve told it: Global Rules override everything, then .windsurfrules, then Memories, then your current prompt.

Memories — Open Cascade → click the brain icon → “Manage Memories.” Tell Cascade to remember something inline: @Cascade remember: we never use moment.js, always date-fns.

Global Rules — Go to Settings → Windsurf → Cascade → Rules and add rules like “Always use TypeScript strict mode” or “Prefer functional components in React.”

The priority order is: Global Rules → .windsurfrules → Memories → your prompt.

Step 7: Set Up Workspace Snippets and prompts.md

For prompts you type repeatedly, Windsurf supports a prompts.md shortcut system that saves keystrokes and ensures consistent prompting across your team. Create a prompts.md file at your repo root — each H2 heading becomes a named snippet accessible by typing / in the Cascade panel. This is one of the most underused features in Windsurf: teams that skip it end up with each developer writing their own variation of the same test-generation or code-review prompt, producing inconsistent Cascade outputs. A prompts.md committed to git means every developer uses the same tested, refined prompt templates for common tasks like writing tests, reviewing diffs, or generating documentation. It eliminates prompt quality variance that makes AI output inconsistent across team members, and it compounds over time as your team refines and improves the templates together.

Example prompts.md:

## write-test
Write a Jest integration test for the function I have selected.
Use supertest for HTTP tests. Mock external APIs with nock.

## review-pr
Review this diff for: security issues, missing error handling,
N+1 queries, and consistency with our coding conventions.

## explain
Explain what this code does, including non-obvious side effects.
Assume the reader knows the language but not this codebase.

Type /write-test in the Cascade panel to insert the full prompt template.

Step 8: Connect MCP Servers to Extend Cascade

Model Context Protocol (MCP) servers let Cascade access external tools — databases, APIs, GitHub, Slack, file systems. This is one of Windsurf’s most powerful but least-configured features among new users. Once connected, an MCP server gives Cascade live context it can’t get from reading source code alone. A database MCP server, for example, lets Cascade query your actual schema before writing a migration — eliminating the column-name hallucinations that make AI-generated SQL unreliable. Teams that add a database MCP server on day one report Cascade generating syntactically correct SQL on first attempt over 80% of the time, compared to frequent schema mistakes without it.

To add an MCP server: Go to Settings → Windsurf → Cascade → MCP Servers → click “Add Server.”

Example: connecting to a local PostgreSQL database:

{
  "name": "postgres",
  "command": "npx",
  "args": ["-y", "@modelcontextprotocol/server-postgres", "postgresql://localhost:5432/mydb"]
}

Common MCP servers to add early:

• @modelcontextprotocol/server-github — PR creation, issue lookup
• @modelcontextprotocol/server-filesystem — read/write access outside the current project
• @modelcontextprotocol/server-postgres or server-sqlite — database access

Step 9: Creating Your First Full Project With Cascade

Here’s a concrete walkthrough: scaffolding a new Express API from scratch using Windsurf’s built-in project generation. This covers the complete first-use experience from blank canvas to a working API with authentication and tests — the kind of greenfield task where Windsurf genuinely outperforms every other AI coding tool available in 2026. The goal isn’t just to see Cascade write code; it’s to build the habit of outcome-first prompting and understand where to intervene when Cascade needs guidance.

1. Open Windsurf → click “Generate a project” from the welcome screen (or Command Palette: “Windsurf: New AI Project”)
2. Describe the project: Express REST API with TypeScript, PostgreSQL, JWT auth, and Jest tests. Users can create accounts, login, and manage todos.
3. Windsurf generates the initial scaffold, installs dependencies, and opens the project
4. Immediately create your .windsurfrules file with the stack details
5. Switch Cascade to Codebase context mode
6. Add your first feature: Add the todo CRUD endpoints. Include validation with zod. All routes should require JWT authentication. Write tests.

Cascade will read the existing auth middleware, understand the schema, write route handlers, add zod validation, update the router index, and write tests. Review the diff before accepting — check migration files and security-critical paths carefully.

Windsurf Pricing: What You Get at Each Tier

For context: Cursor Pro is $20/month. Windsurf Pro at $15/month is the more affordable option for developers who lean heavily on agentic flows. The free tier’s 25 flow actions/month is enough to evaluate the tool but a typical workday of serious development burns 15-30 actions, making the free tier insufficient for daily use. Windsurf reported $82M ARR with 350+ enterprise customers as of July 2025, with 4,000+ enterprises in production and 59% of Fortune 500 companies building with it. Enterprise features include SSO, RBAC, audit logs, SOC 2 Type II compliance, FedRAMP High authorization, HIPAA compliance, and hybrid/on-premise deployment.

Troubleshooting Common Setup Issues

macOS Gatekeeper blocks Windsurf on launch: Go to System Settings → Privacy & Security → scroll down → “Open Anyway.” One-time step for apps downloaded outside the App Store.

Cascade enters an execution loop: Press Cmd+K / Ctrl+K to interrupt. The most common cause is an ambiguous task scope or a missing dependency. Break the task into smaller pieces and be explicit about constraints.

Codebase context mode is slow or crashes: Add a .codeiumignore file (same syntax as .gitignore) to exclude node_modules, dist, .git, large binary assets, and generated files. Also exclude directories over 5MB.

Extensions conflict with Windsurf: Disable other AI completion extensions (Copilot, Tabnine, Codeium standalone). They compete for the same completion hooks and cause latency spikes or silent failures.

VS Code settings didn’t import correctly: Open Command Palette → “Open User Settings (JSON)” and verify ~/.config/windsurf/User/settings.json. Most VS Code settings keys work unchanged in Windsurf.

Windsurf vs Cursor Setup: Different Philosophies

Windsurf and Cursor are both serious AI coding tools, but their setup process reveals fundamentally different workflow philosophies — and choosing the wrong one for your team’s working style is a common source of frustration. Windsurf optimizes for autonomous, outcome-driven work: configure it once with .windsurfrules and context mode, then describe what you want to build. Cursor optimizes for precision: inline suggestions and targeted edits where you maintain tight control over each change. In benchmark tests, Windsurf’s Cascade completed a Redis rate-limiting task in 3.5 minutes with zero step-by-step guidance; Cursor would have required more manual steering for the same task. Understanding which philosophy fits your team saves weeks of adapting to the wrong tool.

Windsurf is better when you frequently build new features and prefer describing outcomes. Cursor is better when you work on mature, large codebases and want precise, predictable suggestions. Many teams use both.

Enterprise Teams: SSO, FedRAMP, and RBAC Setup

For teams on the Enterprise plan, setup involves three additional steps beyond the standard installation that enable the compliance and access control features that make Windsurf viable in regulated industries. Windsurf achieved FedRAMP High authorization and HIPAA compliance in 2025, making it one of the few AI coding tools cleared for federal and healthcare environments. The enterprise setup process follows a standard identity provider integration pattern, so if your team already uses Okta, Azure AD, or Google Workspace, SSO configuration takes under 30 minutes. RBAC setup follows after SSO and controls which developers can use which Cascade features.

SSO configuration: Admin panel → Settings → Authentication → “Enable SSO.” Supports SAML 2.0 and OIDC. Paste your IdP metadata URL (Okta, Azure AD, Google Workspace all work). Test before rollout.

RBAC setup: Admin panel → Policies → define roles. Typical setup: developers get full Cascade access, contractors get File context mode only, read-only reviewers can see AI suggestions but not trigger flows.

FedRAMP / HIPAA: For government or healthcare deployments, contact enterprise sales for hybrid deployment — Cascade inference runs on-premise with your data never leaving your infrastructure.

Audit logs: Admin panel → Audit Log. Captures every Cascade flow, every file written, every terminal command, and every external API call. Required for SOC 2 Type II reviews.

FAQ

Can I use Windsurf without a paid subscription? Yes. The free tier gives you 25 Cascade flow actions per month, unlimited autocomplete suggestions, and access to base models. For occasional or evaluation use, the free tier works. For daily development, most developers find they need Pro ($15/month) within the first week since a typical workday burns 15-30 flow actions.

How do I import my VS Code extensions into Windsurf? During onboarding, select “Import from VS Code.” Afterward, use the Command Palette and search “Install Extensions from VS Code.” Extensions requiring VS Code’s proprietary APIs or competing AI completion extensions (Copilot, Tabnine) won’t work and will be flagged automatically.

What’s the difference between Cascade flows and regular chat? Regular chat (Cmd+L) gives you a conversational interface for questions and suggestions you apply manually. Cascade flows (Cmd+Shift+L) give Cascade permission to read files, write code, run terminal commands, and execute multi-step plans autonomously. Flows consume from your monthly action quota; chat does not.

How does .windsurfrules differ from Memories? .windsurfrules is project-specific, checked into git, and applies to everyone on the team. Memories are personal, stored in your Windsurf account, and apply across all your projects. Use .windsurfrules for team conventions and stack definitions. Use Memories for personal preferences like “always add JSDoc to public functions.”

Is Windsurf safe for codebases with proprietary or sensitive code? Windsurf offers enterprise options with SOC 2 Type II, FedRAMP High, and HIPAA compliance, plus hybrid/on-premise deployment where Cascade inference runs within your infrastructure. For standard cloud plans, code is sent to Codeium’s servers for AI inference. Review Windsurf’s data processing agreement before using it on codebases with contractual data residency requirements.