Introduction to Cascade: Your Agentic Chatbot

In our previous lessons, we laid the groundwork for this journey. We explored the Windsurf IDE, customized its environment, and examined the powerful AI models that drive it. Now it’s time to meet the star of the show—the entity that uses those models to get things done. It’s time to learn how to command the agent.

This lesson introduces you to Cascade. We’ll move beyond thinking of it as a simple chat window on the side of the screen. You’ll learn to see it for what it truly is: mission control for your AI co-pilot, a powerful collaborator equipped with diverse tools to execute complex software engineering tasks.

A codebase-aware collaborator

There’s a fundamental difference in AI assistants between a tool that provides information and an agent that takes action. This is the most important paradigm shift to understand when working with Cascade.

A traditional chatbot is reactive. You ask a question, it gives you an answer—often a block of code that you must then copy, paste, and integrate into your project. The cognitive load remains on you. Cascade, on the other hand, is an agentic co-pilot. It’s designed for action. When you give it an instruction, its goal is not just to respond with text but to accomplish the task within your development environment.

Think of the Cascade panel as the central nervous system of the AI. It provides a transparent log of the entire process, allowing you to see:

• Your prompt: The high-level goal you’ve assigned.

• The agent’s plan: Cascade often breaks down a complex task into a series of logical steps, giving insight into its reasoning.

• The tool calls: You’ll see explicit actions being taken, like [Analyze File], [Run Command], or [Search Web].

• The result: The final summary of what was accomplished and the code changes made.

This transparency is key. You’re not interacting with an external monitoring; you’re collaborating with a partner whose work is fully auditable.

Key features and capabilities

Cascade is packed with features designed to facilitate this new, active style of collaboration. Let’s tour its primary capabilities.

• Tool calling: This is the foundation of Cascade’s agency. It has a built-in set of tools to use to accomplish your goals. It can run shell commands in your terminal, perform a semantic search across your entire codebase, read and analyze files, and even browse the web for up-to-date information. When you ask it to “install numpy,” it knows to invoke its terminal tool and execute pip install numpy.

• Write mode vs. chat mode: Cascade operates in two distinct modes, giving you control over its level of autonomy. Chat Mode is great for asking questions about your code base. Write Mode is for when you want to delegate fully, allowing the agent to make changes autonomously. The agent will propose changes and await your explicit approval before applying them.

• The “Continue” command: Cascade is uniquely aware of your actions outside its own panel. If you ask it to start a task and then manually edit a file yourself, you can simply return to Cascade and type “continue.” The agent will perceive your changes and seamlessly incorporate them into its plan. It doesn’t lose context just because you took the keyboard.

• Reverting changes: This is your ultimate safety net, encouraging fearless experimentation. If Cascade makes a series of edits you don’t like, you don’t have to manually undo them. In the Cascade panel, you can simply hover over any previous step in the trajectory and click the “revert” arrow. Windsurf will roll back all subsequent code changes, returning your project to its state at that point.

• Linter integration and auto-fix: Cascade can automatically run your project’s linter on the code it generates to maintain code quality. It will perform a second, automatic auto-fix edit if it finds any style violations or simple errors. This ensures the AI’s output adheres to your team's standards without requiring you to manually clean it up.

• @-Mentions: You have direct control over the context Cascade uses. By typing @ in the chat input, you can explicitly reference specific items, guaranteeing they are included in the agent’s “thinking” process. You can mention:

  • @functions and @classes from your code.

  • @files and @directories.

  • @web or @docs to instruct the agent to perform a web search.

Persistent memory and rules

An agent needs a memory to become a true long-term collaborator. Cascade has a sophisticated system for persisting context across conversations.

• Memories: As you work, Cascade may automatically identify useful pieces of context, such as a project’s primary programming language or a key architectural decision, and save them as a “memory.” You can also explicitly instruct it to “remember that we use Tailwind CSS for styling.”

• Rules: As we saw earlier, we can define a permanent set of guidelines to shape the AI’s output for a project.

• Planning mode (Pro/Teams/Enterprise): You can enable Planning Mode for long-term projects. Here, Cascade maintains a persistent markdown file outlining a high-level plan, referring to it and updating it as it completes tasks.

The game plan

Theory is essential, but fluency comes from practice. Let’s begin by engaging directly with Cascade to establish a foundational workflow.

We want to start fresh and create a game using three.js. This might be the perfect Windsurf task for someone with a programming pedigree but may not be well-versed in three.js. This will take us on a short journey with Cascade as we get to grips with this AI-powered future.

We will be creating a simple Snake game. For those who might not be aware, a Snake game is a video game where the player controls a growing Snake in a confined playing area. The main objective is to eat food (often apples or other objects) that appears on the screen, which makes the Snake grow longer.

• Movement: The Snake continuously moves in one direction. The player can change direction to navigate the playing field (typically using arrow keys or swiping on a touchscreen).

• Growing: Each time the Snake eats food, it gets longer. This is a key element that increases the game’s difficulty.

• Collision avoidance: The game ends if the Snake collides with:

  • The boundaries or walls of the playing area.

  • Its own body, which gets longer and harder to avoid as the game progresses.

• Scoring: Players typically earn points for each piece of food eaten, aiming for the highest score possible.

Now that we know what to build, let’s head to Windsurf and put Cascade to work.

Getting started

Let’s start simple. Create a new folder or workspace in Windsurf and open up Casade. Select SWE-1 as the model. At the time of writing this course, the SWE-1 model is available for free to all users for a limited time. Use the following prompt to begin:

Create a simple 3D Snake game using Three.js. Use cubes to represent the Snake and a 3D grid as the playfield. The Snake should move in discrete steps across the grid, and respond to arrow key inputs for direction changes. Place a food object on the grid as a 3D shape. Set up a Three.js scene with camera, lighting, and renderer, and include an animation loop to handle movement updates. Write clean, modular JavaScript code with comments, and use only Three.js and standard HTML/CSS/JS, no external game engines or libraries.

This is perhaps not the most descriptive prompt, as we do not mention the game’s rules. However, since we expect the game to follow the rules, this prompt will also allow us to test SWE-1’s general world knowledge.

This simple interaction did create the game for us, but it has a few bugs. The most problematic one is an infinite spam of pop-up messages when the game ends. This renders the browser useless and requires a force close. Another issue is that the grid is at an angle that makes the navigation a bit confusing. Let’s prompt Cascade to fix the issues.

Replace all browser pop-ups in the game with a custom HTML overlay that appears when the game ends. The overlay should have a Game Over message and a “Restart” button. When the player clicks the "Restart” button, the game should reset: the Snake returns to its starting state, the score resets, and a new food item spawns. Update the camera to be high above the grid and slightly tilted downward. Ensure the camera still clearly shows the grid layout and keeps gameplay readable.

With just 2 major prompts, we have a game that is certainly playable, all thanks to Windsurf!

Why should we have all the fun? Windsurf generated the complete code and game demo for us.

You’ve seen that Cascade serves not only as a chatbot but as an essential part of your workflow, equipped with a rich set of features designed for taking action. This is just the beginning. We will continue to iterate and improve this game and explore more Windsurf features.

Quiz