Windsurf Cascade Architecture
Deep dive into Windsurf's Cascade agent — Planning Agent + Execution Agent dual-layer architecture, AI Flow paradigm, and real-world workflow patterns.
Windsurf Cascade Architecture
Windsurf's Cascade is one of the most architecturally distinctive agentic coding systems available today. Rather than the explicit mode-switching model used by Cursor (Chat vs. Agent), Cascade implements a dual-layer agent architecture governed by what Codeium calls the AI Flow paradigm — a continuous, fluid workflow where planning and execution blend without manual transitions. This article dissects that architecture, compares it to competing approaches, and maps it to real loop engineering patterns.
The Cascade Agent: Two-Layer Architecture
At its core, Cascade separates the cognitive work of coding into two cooperating layers:
┌───────────────────────────────────────────────────────┐
│ CASCADE AGENT │
│ │
│ ┌─────────────────────────────────────────────────┐ │
│ │ PLANNING AGENT │ │
│ │ │ │
│ │ - Interprets user intent │ │
│ │ - Analyzes codebase context │ │
│ │ - Decomposes tasks into steps │ │
│ │ - Selects tools and execution order │ │
│ │ - Maintains memory of decisions │ │
│ └──────────────────┬──────────────────────────────┘ │
│ │ Task Plan │
│ ▼ │
│ ┌─────────────────────────────────────────────────┐ │
│ │ EXECUTION AGENT │ │
│ │ │ │
│ │ - Reads and writes files │ │
│ │ - Runs terminal commands │ │
│ │ - Searches codebase (grep, semantic) │ │
│ │ - Deploys and previews │ │
│ │ - Recovers from errors │ │
│ └─────────────────────────────────────────────────┘ │
│ │
│ FEEDBACK LOOP: Execution results flow back to │
│ Planning Agent for iterative refinement │
└───────────────────────────────────────────────────────┘
The Planning Agent does not write code. It reasons about what to do and how to sequence it. The Execution Agent does not plan — it carries out the plan using a rich toolkit of file, terminal, and search operations. Critically, execution results feed back into the planning layer, creating a closed loop that continues until the task is complete.
AI Flow vs. Cursor's Agent Mode
The most consequential architectural difference between Windsurf and Cursor is not the feature list — it is the interaction paradigm. Cursor requires the developer to explicitly choose between modes. Cascade does not.
| Dimension | Windsurf Cascade (AI Flow) | Cursor Agent Mode |
|---|---|---|
| Mode switching | None — behavior adapts fluidly to the request | Explicit: Chat mode or Agent mode |
| Planning model | Always-on Planning Agent decomposes tasks internally | User switches to Agent mode to trigger multi-step execution |
| Context retrieval | Automatic — Cascade determines which files to read | Semi-automatic — uses @ references plus codebase indexing |
| Error recovery | Silent internal recovery by default; transparent on request | Shows each step and error explicitly in the agent panel |
| Execution model | "Automatic transmission" — adapts to task complexity | "Manual transmission" — developer selects the gear |
| Parallelism | Multiple Cascade instances (Simultaneous Cascades) | Single agent session per chat |
The PAIR-code/vibe-tasking reference documentation at GitHub describes this distinction with an apt analogy: Cascade is an automatic transmission that shifts gears based on road conditions, while Cursor is a manual transmission where the driver selects each mode.
For loop engineering, this distinction has practical implications. In a tight edit-test-fix loop, the automatic paradigm means the agent decides whether a quick edit suffices or a full replan is needed — without interrupting the developer's flow.
The Planning Agent in Detail
The Planning Agent is responsible for everything that happens before code touches disk. Its responsibilities include:
Task Understanding and Decomposition
When a developer types a request like "Add pagination to the user list API," the Planning Agent:
- Reads relevant files via
view_file_outlineandcodebase_search - Identifies the API route handler, database query, and frontend component
- Produces a step-by-step execution plan
- Presents the plan for approval (or proceeds autonomously in Write mode)
Context Construction
Unlike Cursor, which relies heavily on the developer's @ file references, Cascade constructs its own context. The Planning Agent uses a suite of tools documented in the vibe-tasking reference:
| Tool | Purpose |
|---|---|
find_by_name | Locate files by glob pattern, filter by type |
view_file_outline | Inspect structure without reading full content |
codebase_search | Semantic search across the repository |
grep_search | Exact pattern matching via ripgrep |
view_code_item | Read specific functions or classes by qualified path |
This means Cascade can operate effectively on large monorepos where manually tagging every relevant file is impractical. The Planning Agent determines which files matter and loads only those — a pattern Codecademy's 2026 agentic IDE comparison identified as Windsurf's core strength.
Memory System
Cascade's create_memory tool persists important decisions across sessions. When the Planning Agent learns that a project uses React Query instead of SWR, or that the team prefers Zod for validation, it stores that as a memory. Future sessions retrieve these memories automatically, reducing repeated context-setting.
This maps directly to the loop engineering principle of state persistence across iterations — the same reason Claude Code uses CLAUDE.md files. Cascade's memory is just more implicit.
The Execution Agent in Detail
The Execution Agent is the hands-on layer. It carries out the plan produced by the Planning Agent using a deterministic set of tools.
File Operations
| Tool | Behavior |
|---|---|
write_to_file | Creates new files only — refuses to overwrite |
replace_file_content | Edits existing files via content chunk replacement |
view_line_range | Reads specific line ranges from files |
The split between write_to_file (create-only) and replace_file_content (edit-only) is a deliberate safety design. It prevents the agent from accidentally overwriting existing work — a failure mode documented extensively in production loop failure analyses.
Terminal Integration
The Execution Agent runs commands via run_command, with safeguards for destructive operations (file deletion, dependency installation, network requests) that require explicit user approval. It supports both blocking execution (waits for result) and non-blocking execution (runs in background, checked via command_status).
For loop engineering, the non-blocking pattern enables parallel execution of independent steps — running tests while simultaneously generating documentation, for example.
Browser Preview and Deployment
Cascade can spin up a local browser preview via browser_preview to verify visual changes, and deploy web applications through the experimental deploy_web_app tool. This closes the verify loop entirely within the IDE, reducing context switches.
The Feedback Loop: Where Cascade Becomes Agentic
The defining characteristic of Cascade's architecture is the feedback loop between execution results and planning:
User Request
│
▼
Planning Agent ─────► Execution Plan
▲ │
│ ▼
│ Execution Agent
│ │
│ ▼
│ Tool Outputs + Errors
│ │
└──────────────────────┘
(iterative refinement)
When the Execution Agent encounters an error — a failing test, a type error, a merge conflict — the result flows back to the Planning Agent, which reassesses the approach and produces a revised plan. This loop continues until convergence.
By default, Cascade handles minor, recoverable errors internally without surfacing them to the developer. This is the "smooth experience" design choice. For loop engineering workflows where transparency matters — production debugging, security-sensitive changes — developers can configure Cascade to show every step.
Real-World Loop Patterns with Cascade
Pattern 1: Feature Development Loop
A typical feature development loop in Cascade follows this flow:
# Developer prompt in Cascade
> "Add a newsletter signup component with Zod validation
and react-hook-form. POST to /api/subscribe."
# Cascade's internal plan (auto-generated):
# Step 1: view_file_outline on existing form components
# Step 2: codebase_search for "/api" route patterns
# Step 3: write_to_file components/Newsletter.tsx
# Step 4: write_to_file app/api/subscribe/route.ts
# Step 5: run_command "npm install zod react-hook-form"
# Step 6: run_command "npm run build" (verify)
# Step 7: Fix any type errors (if build fails)
# Step 8: browser_preview to verify UI
The Planning Agent produces steps 1-2 before writing any code. The Execution Agent handles steps 3-8, with step 7 being the feedback loop in action.
Pattern 2: Bug Fix Loop
For debugging, Cascade's automatic context retrieval is particularly effective:
# Developer prompt
> "Fix the memory leak in the WebSocket event pipeline.
Users report the tab crashes after ~10 minutes."
# Cascade's internal reasoning:
# Step 1: codebase_search for "WebSocket", "EventEmitter"
# Step 2: grep_search for "addEventListener" without "removeEventListener"
# Step 3: view_code_item on suspicious functions
# Step 4: replace_file_content to add cleanup logic
# Step 5: run_command "npm test" to verify fix
# Step 6: If tests fail → back to Planning Agent for revised approach
Note that the developer does not need to identify which files are relevant. The Planning Agent's semantic search handles that — a significant advantage for unfamiliar codebases.
Pattern 3: Monorepo Refactoring
Cascade was originally designed by Codeium specifically for enterprise-scale repositories. The automatic context retrieval pattern scales to monorepos where manual @ referencing becomes untenable:
# In a monorepo with 200+ packages
> "Migrate all packages from Jest to Vitest.
Update CI configs and shared test utilities."
# Cascade handles the scope automatically:
# Step 1: find_by_name all "jest.config.*" files
# Step 2: grep_search for "from 'jest'" patterns
# Step 3: Identify shared test utilities in packages/test-utils/
# Step 4: Plan migration order (dependencies first)
# Step 5: Execute across packages sequentially
# Step 6: run_command "pnpm test --filter=..." per package
Cascade vs. Claude Code: Architectural Comparison
For loop engineering practitioners choosing between tools, the architectural differences matter:
| Aspect | Windsurf Cascade | Claude Code |
|---|---|---|
| Architecture | Dual-agent (Planning + Execution) | Single-agent loop |
| Context model | Auto-retrieved via semantic search | File reads + system prompt |
| Memory | Implicit create_memory database | Explicit CLAUDE.md files |
| Tool access | 20+ built-in tools | Shell + MCP extensions |
| Model support | Claude, GPT-4, Gemini (multi-provider) | Claude only (Opus/Sonnet/Haiku) |
| Transparency | Configurable (smooth by default) | Always explicit |
| Parallelism | Simultaneous Cascades | Background tasks via Monitor |
| Loop control | Autonomous with approval gates | Developer-driven iteration |
Claude Code gives the developer more explicit control over each iteration. Cascade gives the agent more autonomy. The right choice depends on whether your loop engineering workflow prioritizes supervision (Claude Code) or delegation (Cascade).
Pricing and Plan Tiers
Windsurf offers several tiers relevant to loop engineering teams:
| Plan | Price | Cascade Credits | Key Limits |
|---|---|---|---|
| Free | $0/month | 25/month | Basic models, no premium features |
| Pro | $15/month | 500/month | Premium models, Fast Context, Codemaps |
| Teams | $30/seat/month | Shared pool | Admin dashboard, analytics |
| Enterprise | $60/seat/month | Unlimited | SSO/SCIM, longer contexts, self-hosted option |
Compared to Cursor at $20/month and Claude Code's consumption-based pricing, Windsurf's Pro tier sits in the middle. The credit model means teams running heavy loop workloads should evaluate actual consumption against their iteration counts.
The Devin Desktop Transition (June 2026)
A significant development: on June 2, 2026, Cognition acquired Codeium and rebranded Windsurf as Devin Desktop. The editor remains the same product with the same pricing and keybindings, but the underlying agent runtime is changing:
- Cascade is being replaced by Devin Local, a Rust rewrite that claims up to 30% token efficiency improvement
- Devin Local adds native subagent support for parallel work
- Cascade continues to function until its EOL on July 1, 2026
For teams currently using Cascade, this means the dual-agent architecture described in this article will persist conceptually in Devin Local, but the implementation details will shift. The Planning Agent / Execution Agent separation appears to remain, now with the addition of subagents that can handle independent subtasks in parallel.
Quick Reference: Cascade Tool Map
NAVIGATION SEARCH MODIFICATION
───────── ─────── ────────────
find_by_name grep_search write_to_file
list_dir codebase_search replace_file_content
view_file_outline search_in_file (create-only)
view_line_range search_web (edit-only)
view_code_item
EXECUTION CONTEXT DEPLOYMENT
───────── ─────── ────────────
run_command create_memory deploy_web_app
command_status Memories & Rules check_deploy_status
browser_preview .codeiumignore read_deployment_config
Related Resources
- Model tiering within agents: See Claude Models for Loop Engineering for how to optimize which model powers each agent layer
- IDE plugin ecosystem: Browse the full IDE Plugins Directory for alternatives and extensions
- Cascade capabilities reference: The PAIR-code/vibe-tasking repository on GitHub maintains the most comprehensive technical documentation of Cascade's tool set
- Agentic IDE comparison: Codecademy's 2026 comparison of Cursor, Windsurf, Antigravity, and VS Code Agents provides a broader market context