How to Use Windsurf AI: The Beginner's Safe Path (Cascade, Chat, and the Rules File)

CodexFuse Team · 2026-10-27T22:32:36.379Z · 19 min read

Learning how to use Windsurf is mostly learning one new habit: telling an AI agent what to do, then checking its work before anything lands in your code. Windsurf is an AI-native code editor — a fork of Visual Studio Code rebuilt around an agent called Cascade that can read your whole project, plan multi-step changes, edit files across it, and run terminal commands to test the result. If you already know VS Code, the editor itself will feel familiar on day one. The part that takes practice is delegation: writing a specific prompt, reading the plan Cascade proposes, and reviewing every diff before you accept it. This Windsurf AI tutorial follows that safe path step by step, from install to your first real session, and it also covers the name change you will run into: Windsurf is now called Devin Desktop. If you are weighing the other big AI editor first, our guide on how to use Cursor AI walks through its workflow so you can compare the two side by side.

How do you use Windsurf AI?

Windsurf AI is used by opening the Cascade panel, describing a small, specific coding task in plain English, reading the plan Cascade proposes, and reviewing each file change as a diff before accepting it. You do not write the code yourself — you brief the agent, check its plan, and approve or correct the result. The full first session takes five steps:

1. Install Windsurf, sign in with a free account, and open a real project you already understand.
2. Press Cmd+L on macOS or Ctrl+L on Windows and Linux to open Cascade, and make sure Write mode is selected.
3. Write a specific, bounded prompt that names the file, the change, and what "done" looks like.
4. Read the plan Cascade proposes before approving it — the plan shows whether it understood you.
5. Review every diff like a code review, accept the good changes, then run your tests.

The rest of this guide fills in each step, including the safety rules that keep a beginner's first week from turning into a cleanup job.

What is Windsurf AI?

Windsurf is an AI-native code editor built by Codeium and now owned by Cognition, the company behind the Devin coding agent. On the surface it looks like VS Code: the same file explorer, command palette, and extension support. Underneath, it adds Cascade, an agentic AI that reads your entire codebase, understands context across files, and makes coordinated changes from a single instruction. Where a chatbot suggests a snippet you paste yourself, Cascade plans the work, edits the files, and runs commands to verify the result. That "agentic flow" is what separates Windsurf from older autocomplete-style tools, and it is also why the learning curve is about delegation rather than syntax.

Three features do most of the work. Cascade is the agent itself, handling multi-file, multi-step edits. Tab (also called Supercomplete) is predictive autocomplete that anticipates whole functions, not just the next token. And the editor keeps shared context: if you manually edit a file, Cascade factors that in, which is why developers describe it as pair programming with an agent that never loses the thread. If the idea of steering an AI while it handles the mechanical work sounds familiar, that is the vibe coding workflow — you set direction at a high level and the agent does the typing.

Is Windsurf still called Windsurf?

No — not officially. Cognition renamed Windsurf to Devin Desktop on June 2, 2026, and windsurf.com/pricing now redirects to devin.ai/pricing. The editor, extensions, keybindings, and workflows stay the same; the app is renamed (Devin.app on macOS) and the old surf command gives way to devin-desktop. Most people still search for and refer to it as Windsurf, so this guide uses the name you searched for and flags the new name wherever it matters, such as the download page and the pricing page. One more change is in progress: Cascade is being replaced by a new local agent called Devin Local, which Cognition says has up to 30% better token efficiency at the same pricing. Cascade remains documented as the legacy agent, and the workflow in this guide — prompt, plan, diff — is the same either way.

How do I install Windsurf and set it up?

Installing Windsurf takes a few minutes: download it from the official site, run the installer, import your VS Code setup if you have one, and sign in so Cascade activates. Windsurf runs on macOS (OS X Yosemite 10.10 or later), Windows 10 or later, and Linux (Ubuntu 20.04 or equivalent), and the installer is roughly 100–200 MB. During installation you can add Windsurf to your system PATH so you can open projects from the terminal.

On first launch, an onboarding wizard walks through four choices. First, choose a setup style: "Start Fresh" for defaults, or "Import from VS Code/Cursor" to migrate your extensions, themes, keybindings, and settings — the import is the faster start if you already use VS Code. Second, pick keybindings: VS Code defaults or Vim mode; beginners should stick with the defaults. Third, choose a color theme. Fourth, sign in: create a free Windsurf account or sign in with Google, GitHub, or GitLab. Signing in is what activates the AI features, so Cascade will not work until this step is done. If browser sign-in fails, the wizard offers a manual code entry: copy the auth link, paste it in a browser, and enter the generated code back in Windsurf.

Before your first Cascade session, finish four setup checks. Install and authenticate first, choose a default model, open a real project rather than a blank folder, and confirm your language server is active — open a file and check that syntax highlighting, diagnostics, and autocomplete all work. A broken language server produces misleading results from Cascade, and an empty folder gives its codebase indexing nothing to reason about. Finally, press Cmd+L (macOS) or Ctrl+L (Windows/Linux) to open Cascade and confirm it responds and your account shows as authenticated in the sidebar.

What is Cascade, and how is it different from Chat?

Windsurf Cascade is the editor's agentic assistant: you describe a goal and it plans, edits, and verifies across your project. Chat is the lighter-weight panel for questions and explanations that do not change any files. Confusing the two is the most common beginner mistake, because they look similar and sit in the same sidebar — but they do different jobs, and picking the wrong one wastes agent quota or, worse, edits files when you only wanted an answer.

Cascade has two modes. Write mode is the default: Cascade generates or modifies code, shows you a plan first, then presents every change as a diff you review. Chat mode gives guidance, explanations, and suggestions without changing code. Open Cascade with Cmd+L on macOS or Ctrl+L on Windows and Linux; the Chat panel is the lighter-weight companion for asking questions. Tab is the third tool in the same family: press Tab to accept AI completions as you type, including multi-line edits before and after your cursor. Use the table below to pick the right panel for the job.

Two details make Cascade work well. First, it keeps context across the session: if a result is not correct, type the correction into the same Cascade panel rather than starting a new session, because corrections inside the same thread are more reliable than re-prompting from scratch. Second, you can point it at exactly the right place with the @ symbol — type @ followed by a file or folder name to focus the prompt, for example "@App.js add a header." That focus is what stops Cascade from making broad changes when you wanted a small one.

How do I run my first Cascade session safely?

A safe first Cascade session follows five rules: commit your code to git first, pick a task you already understand, write a bounded prompt, read the plan before approving it, and review every diff before accepting it. Those rules are the whole system — skip one and you are trusting the agent instead of checking it, which is exactly how beginners end up with a broken codebase they cannot explain.

Start with git. Before Cascade touches anything, commit your current work so you can revert any change with one command. Then pick a first task you could write manually in the next hour — adding input validation to a form, writing unit tests for a module you just built, or refactoring one function for readability. A task you already understand is the only kind you can evaluate accurately, and the comparison between what you expected and what Cascade produced is where the learning happens. Do not start by asking it to build a whole project from scratch: there is no codebase to index, no existing patterns to follow, and no baseline for judging the output.

Write the prompt the way you would brief a developer: specific, bounded, and connected to a file you already understand. A good first prompt looks like this: "Add input validation to the registration form in /src/forms/register.tsx and return an error message if the email field is empty." It names the file, the change, and what "done" looks like. A bad first prompt looks like "fix the bug in my app" — Cascade cannot infer which file matters or what the desired output looks like, and vague prompts are the most common failure mode for beginners. Keep the task to two or three files; a first session scoped to "rebuild the entire authentication system" produces a diff too large to review properly.

When Cascade answers, it shows a plan of the changes it intends to make before any file is modified. Reading that plan is the single most important habit in this guide: it reveals whether Cascade understood the instruction, and beginners who approve without reading it frequently find it modified the wrong file, added an unwanted dependency, or solved a different problem than the one intended. If the plan is wrong, correct it in the same session before approving. After execution, Windsurf shows a diff view for every modified file — treat each diff as a code review rather than an automatic approval, accept or reject changes individually, and then run your tests. A useful two-session structure for the first day: first, complete a bounded task with Cascade and review the diff carefully; second, ask Cascade to write tests for the code it just produced. That gives you two rounds of prompt-and-review practice on work you can judge.

The safety rules that never change

Three rules protect every session, not just the first. Never paste passwords, API keys, or other secrets into a prompt — Cascade sends your prompt to a model, and a secret in a prompt is a secret you have shared. Keep your work in git and commit before every session, so a bad run is one revert, not a rebuild. And never let Cascade run a command you would not run yourself: it can execute terminal commands, so read any queued command — such as installing a package or running a script — before you approve it. These rules also apply to the other AI coding tools in the same family: if your work lives mostly in the terminal, compare editor-based agents with a Claude Code style CLI workflow, where the same habits — git first, read before approving — apply.

What goes in the rules file?

Windsurf rules live in a .windsurfrules file in your project root that tells Cascade how your project works, so you stop repeating the same instructions in every prompt. Put project facts in it, not wishes: the stack and versions, the folder layout, the code style, and the commands for testing and building. A short example covers most projects:

Always use TypeScript and strict mode.
Use functional components with hooks; no class components.
Run `npm test` before finishing any change.
Never edit files in /migrations by hand.
Prefer the existing utility functions in /src/utils over new dependencies.

Rules can also live globally as Memories in settings — for example "Always use Python 3.12" or "Prefer functional programming" — which apply across projects, while .windsurfrules applies to one project. Beginners who skip both miss capabilities that directly affect how accurately Cascade understands their codebase, and the @ context syntax is the other half of the same idea: tag the files a prompt is about instead of letting Cascade guess. Keep the rules file short and factual; a long list of vague preferences is ignored more often than a short list of concrete ones.

What should I build first to learn Windsurf?

Build something you already know how to do manually, on a real project you already understand. That is the only way to evaluate what Cascade produces accurately and identify exactly where it diverged from your intent — and one session on known territory teaches more than ten sessions on unfamiliar code. Good first tasks are adding a new API endpoint to an existing project, writing unit tests for a module you just built, refactoring a function for readability, or adding form validation to an existing UI component. Each touches a small number of files and has a clear pass/fail result: the tests pass, the form rejects bad input, the endpoint returns the right data.

The timeline is predictable. Days one and two are orientation: getting familiar with the interface, completing your first two or three Cascade sessions, and making the shift from writing code to describing tasks. Days three through seven are prompt calibration, when you discover that prompt specificity directly determines output quality. By week two, most beginners have found a rhythm and start delegating confidently — and the tasks where Cascade saves real time are the same ones every guide names: scaffolding, refactoring, and test generation. The tasks where it adds friction are small targeted edits and security-sensitive changes, which are often faster by hand. If you want a broader map of the AI-assistant landscape before you commit to one editor, our guide on how to use Google Gemini covers the other kind of AI assistant — the chat-first one you use outside an editor — so you can see where an editor agent fits and where a chatbot fits better.

What are the most common beginner mistakes?

The most common beginner mistakes are prompt-related, not technical: vague prompts, skipping the plan review, starting with tasks that are too large, and using full Cascade sessions for jobs that do not need them. All four are avoidable once you know to watch for them, and they account for nearly every "Windsurf broke my project" story a beginner tells in the first week.

Vague prompts fail because Cascade cannot infer the file, the expected output, or the constraints from a one-line ask. Skipping the plan review fails because the plan is the only moment you can catch a misunderstanding before files change. Oversized first tasks fail because a huge diff cannot be reviewed properly, so errors slip through inside changes you never read. And treating every task as a Cascade task fails in a different way: inline chat and the Chat panel are better for explaining code, writing docstrings, and answering questions, and using a full agent session for those small jobs burns your free quota and adds complexity for no benefit. A related mistake is forgetting the free tier's limits: the agent quota resets daily, but a single complex session can exhaust it, so a heavy first session can stop mid-task with nothing left until the next reset.

Is Windsurf free, and what does the free plan include?

Yes, Windsurf is free with limits. Windsurf pricing is simple — five plans, one free — and the Windsurf free plan costs $0 and includes unlimited Tab completions and unlimited inline edits, plus a light agent quota that resets daily and weekly. The catch is the model list and the quota size. Free-tier users only have access to SWE-1.6, Cognition's previous-generation in-house model — no Claude, GPT, or Gemini models — and Cognition does not publish the free quota as a number, so the practical rule is to spend it on small, well-scoped asks and keep typing with Tab when it runs out. When the quota is gone, you wait for the next reset; extra usage is only available on paid plans.

Prices above are from devin.ai/pricing, checked on October 23, 2026, and they can change — check the pricing page before you buy. Three details matter before you pay. First, there is no free trial of the paid plans: the docs state plainly that free trials are not currently offered, so the Free plan is effectively the trial and it does not expire. Second, existing Pro subscribers at the old $15 per month keep that price indefinitely, and existing Teams seats keep $30 per developer seat. Third, you can link a ChatGPT Go, Plus, or Pro plan so GPT requests bill to that subscription instead of your Devin quota, but that link is not available on the Free plan. Use Free when you want a capable editor with unlimited Tab and an occasional agent assist; pay for Pro when you want frontier models, cloud agents, or third-party agents running inside the same command center.

Windsurf vs Cursor: which should a beginner pick?

Windsurf vs Cursor comes down to guidance versus control. Both are VS Code forks, both offer multi-file agents, and both support frontier models from Anthropic, OpenAI, and Google on their paid plans. Windsurf's Cascade tends to favor a cleaner, more guided agentic flow that is friendly to newcomers — the plan-first, diff-review workflow this guide teaches. Cursor exposes more granular controls that power users love, and it is the more polished editor with the larger community. Both start at $20 a month for their Pro plans, so price does not decide it. The honest answer for most developers is to trial both free tiers on your own codebase for a week and keep whichever one fits your habits. Our how to use Cursor AI guide covers Cursor's side of that trial in the same beginner-safe format, so you can run the comparison on equal footing.

Sources

• LOW/CODE — "Windsurf AI IDE for Beginners: 2026 Starter Guide" (updated October 2026; first-session sequence, plan review, diff review, two-week productivity timeline, common mistakes)
• Sharkly — "Is Windsurf Free? Yes, With Limits, and It Is Now Devin Desktop (2026)" (October 2026; Devin Desktop rename of June 2, 2026, pricing checked on devin.ai/pricing on October 23, 2026, Free/Pro/Max/Teams prices, SWE-1.6 free-tier model limit, no free trial)
• FreeAcademy — "Windsurf AI Code Editor: What It Is (2026)" (May 2026; Cascade, Supercomplete, VS Code fork, Windsurf vs Cursor)
• Tech Company News — "How To Use Windsurf? Step By Step Guide For Beginners" (February 2026; install steps, system requirements, onboarding choices, shortcuts, Write vs Chat modes)
• ToolHalla — "Cursor vs Windsurf vs Cline 2026" (Cascade and Memories, $15 Pro as of early 2026)

Frequently asked questions

Is Windsurf still called Windsurf?

Not officially. Cognition renamed Windsurf to Devin Desktop on June 2, 2026, and windsurf.com/pricing now redirects to devin.ai/pricing. The editor itself is unchanged — same extensions, keybindings, and workflows — and most people still call it Windsurf. Use the new name when you search for the download or pricing pages, since those now live on Devin's site.

Is Windsurf free?

Yes, with limits. The Free plan costs $0 and includes unlimited Tab completions, unlimited inline edits, and a light agent quota that resets daily and weekly. Free-tier users only have access to the SWE-1.6 model, and there is no free trial of the paid plans. Pro is $20 a month, Max is $200 a month, and Teams starts at $80 a month plus $40 per full seat (prices checked October 23, 2026).

What is Cascade in Windsurf?

Cascade is Windsurf's agentic AI assistant. You describe a goal in plain English and Cascade reads your codebase, proposes a plan, edits files across your project, and can run terminal commands to verify the result. Open it with Cmd+L on macOS or Ctrl+L on Windows and Linux. Cognition is replacing Cascade with a new local agent called Devin Local, but the prompt-plan-diff workflow stays the same.

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

You need some coding knowledge. Windsurf accelerates coding rather than replacing it: the most productive beginners are people who can read the code Cascade produces and judge whether it is right. If you are still learning fundamentals, use it on tasks you already understand so you can evaluate its output — that is how the tool makes you a stronger engineer instead of a dependent one.

Is Windsurf safe to use on my code?

Yes, if you follow the safety rules: commit to git before every session, read Cascade's plan before approving it, review every diff like a code review, and never paste passwords or API keys into a prompt. Cascade can run terminal commands, so read any queued command before approving it. Those four habits keep a bad session to one revert instead of a rebuild.