> ## Documentation Index
> Fetch the complete documentation index at: https://docs.devinenterprise.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Cascade (legacy)
> Reference for the legacy Cascade agent in Devin Desktop: modes, memories and rules, skills, AGENTS.md, workflows, worktrees, MCP, and hooks.
> [!NOTE]
>
> Cascade is the legacy agent in Devin Desktop. New conversations start with [Devin Local](https://docs.devinenterprise.com/desktop/devin-local/overview.md); existing Cascade conversations remain available from the history and sidebar.
## Overview
Devin Desktop's Cascade unlocks a new level of collaboration between human and AI.
Cascade is one of two local agents in Devin Desktop; the other is the [Devin Local agent](https://docs.devinenterprise.com/desktop/devin-local/overview.md), which new tabs default to when you haven't chosen a preferred agent.
To open Cascade, press `Cmd/Ctrl+L` or click the Cascade icon in the top right corner of the Devin Desktop window. Any selected text in the editor or terminal will automatically be included.
> [!NOTE]
>
> Cascade, Devin Local, and every other ACP agent are unavailable while a workspace is open in Restricted Mode.
##### Quick links to features
> **[Terminal](https://docs.devinenterprise.com/desktop/terminal.md)**
>
> An upgraded Terminal experience.
> **[Workflows](https://docs.devinenterprise.com/desktop/cascade.md#workflows)**
>
> Automate repetitive trajectories.
### Model selection
Select your desired model from the selection menu below the Cascade conversation input box. Click below to see the full list of the available models and their availability across different plans and pricing.
> **[Models](https://docs.devinenterprise.com/desktop/models.md)**
>
> Model availability in Devin Desktop.
### Cascade Code / Cascade Chat
Cascade comes in two primary modes: **Code** and **Chat**.
Code mode allows Cascade to create and make modifications to your codebase, while Chat mode is optimized for questions around your codebase or general coding principles.
While in Chat mode, Cascade may propose new code to you that you can accept and insert.
### Plans and Todo Lists
Cascade has built-in planning capabilities that help improve performance for longer tasks.
In the background, a specialized planning agent continuously refines the long-term plan while your selected model focuses on taking short-term actions based on that plan.
Cascade will create a Todo list within the conversation to track progress on complex tasks. To make changes to the plan, simply ask Cascade to make updates to the Todo list.
Cascade may also automatically make updates to the plan as it picks up new information, such as a Memory, during the course of a conversation.
### Queued Messages
While you are waiting for Cascade to finish its current task, you can queue up new messages to execute in order once the task is complete.
To add a message to the queue, simply type in your message while Cascade is working and press `Enter`.
* **Send immediately**: Press Enter again on an empty text box to send it right away.
* **Delete**: Remove any message from the queue before it's sent
### Tool Calling
Cascade has a variety of tools at its disposal, such as Search, Analyze, MCP, and the [terminal](https://docs.devinenterprise.com/desktop/terminal.md).
It can detect which packages and tools that you're using, which ones need to be installed, and even install them for you. Just ask Cascade how to run your project and press Accept.
> [!NOTE]
>
> By default, Cascade can make up to 40 invocations per prompt. If the trajectory stops at this limit, simply press the `continue` button and Cascade will resume from where it left off. However, each `continue` will count as a new prompt credit due to tool calling costs.
You can turn on the `Auto-Continue` setting to have Cascade automatically continue its response when it hits the invocation limit instead of stopping. These will consume a prompt credit(s) corresponding to the model you are using.
In `settings.json`, this is the `devin.autoContinue` setting: `0` or a negative value turns auto-continue on, so Cascade continues indefinitely, and a positive value (the default is `40`) turns it off, so Cascade stops at the invocation limit and prompts you to continue.
### Voice input
Use Voice input to use your voice to interact with Cascade. In its current form it can transcribe your speech to text.
### Named Checkpoints and Reverts
You have the ability to revert changes that Cascade has made. Simply hover your mouse over the original prompt and click on the revert arrow on the right, or revert directly from the table of contents. This will revert all code changes back to the state of your codebase at the desired step.
> [!WARNING]
>
> Reverts are currently irreversible, so be careful!
You can also create a named snapshot/checkpoint of the current state of your project from within the conversation, which you can easily navigate to and revert at any time.
### Real-time awareness
A unique capability of Devin Desktop and Cascade is that it is aware of your real-time actions, removing the need to prompt with context on your prior actions.
Simply instruct Cascade to "Continue".
### Send problems to the agent
When you have problems in your code which show up in the Problems panel at the bottom of the editor, send them to the agent as context:
* Click `Send all to agent` at the top of the Problems panel to send every problem currently listed.
* Click `Send to agent` next to a file in the Problems panel to send only that file's problems.
### Explain and fix
For any errors that you run into from within the editor, you can simply highlight the error and click `Explain and Fix` to have Cascade fix it for you.
### Ignoring files
If you'd like Cascade to ignore files, you can add your files to `.devinignore` (or the legacy `.codeiumignore`) at the root of your workspace. This will prevent Cascade from viewing, editing or creating files inside of the paths designated. You can declare the file paths in a format similar to `.gitignore`. See [Ignore Files](https://docs.devinenterprise.com/desktop/context-awareness/devin-ignore.md) for details.
#### Global .codeiumignore
For enterprise customers managing multiple repositories, you can enforce ignore rules across all repositories by placing a global `.codeiumignore` file in the `~/.codeium/` folder. This global configuration will apply to all Devin Desktop workspaces on your system and works in addition to any repository-specific `.codeiumignore` files.
### Linter integration
Cascade can automatically fix linting errors on generated code. This is turned on by default, but it can be disabled by clicking `Auto-fix` on the tool call, and clicking `disable`. This edit will not consume any credits.
When Cascade makes an edit with the primary goal of fixing lints that it created and auto-detected,
it may discount the edit to be free of credit charge. This is in recognition of the fact that
fixing lint errors increases the number of tool calls that Cascade makes.
### Sharing your conversation
> [!NOTE]
>
> This feature is currently only available for Teams and Enterprise customers.
You can share your Cascade trajectories with your team by clicking the `...` Additional options button in the top right of the Cascade panel, and clicking `Share Conversation`.
### @-mention previous conversations
You can also reference previous conversations with other conversations via an `@-mention`.
When you do this, Cascade will retrieve the most relevant and useful information like the conversation summaries and checkpoints, and specific parts of the conversation that you query for. It typically will not retrieve the full conversation as to not overwhelm the context window.
### Simultaneous Cascades
Users can have multiple Cascades running simultaneously. You can navigate between them using the dropdown menu in the top left of the Cascade panel.
> [!WARNING]
>
> If two Cascades edit the same file at the same time, the edits can race, and sometimes the second edit will fail.
If you expect two Cascades to edit similar files, you should consider using [worktrees](https://docs.devinenterprise.com/desktop/cascade.md#worktrees) to keep them isolated.
## Workflows
Workflows enable users to define a series of steps to guide Cascade through a repetitive set of tasks, such as deploying a service or responding to PR comments.
These Workflows are saved as markdown files, allowing users and their teams an easy repeatable way to run key processes.
Once saved, Workflows can be invoked in Cascade via a slash command with the format of `/[name-of-workflow]`.
> [!NOTE]
>
> Workflows are **manual-only** — Cascade will never invoke a workflow automatically. If you want Cascade to pick up a procedure on its own, use a [Skill](https://docs.devinenterprise.com/desktop/devin-local/customizations.md#skills) instead.
Workflows are specific to Cascade — the [Devin Local agent](https://docs.devinenterprise.com/desktop/devin-local/overview.md) does not support them. Migrate your workflows to [skills](https://docs.devinenterprise.com/desktop/devin-local/customizations.md#skills) with the **Devin: Open Cascade Migration Wizard** command.
### How it works
Rules generally provide large language models with guidance by providing persistent, reusable context at the prompt level.
Workflows extend this concept by providing a structured sequence of steps or prompts at the trajectory level, guiding the model through a series of interconnected tasks or actions.
To execute a Workflow, users simply invoke it in Cascade using the `/[workflow-name]` command.
> [!TIP]
>
> You can call other Workflows from within a Workflow! \
> \
> For example, /workflow-1 can include instructions like "Call /workflow-2" and "Call /workflow-3".
Upon invocation, Cascade sequentially processes each step defined in the Workflow, performing actions or generating responses as specified.
### How to create a Workflow
To get started with Workflows, click on the `Customizations` icon in the top right slider menu in Cascade, then navigate to the `Workflows` panel. Here, you can click on the `+ Global` or `+ Workspace` button to create a new Workflow at either the global or workspace level, respectively.
Workflows are saved as markdown files within `.devin/workflows/` directories (or the legacy `.windsurf/workflows/`) and contain a title, description, and a series of steps with specific instructions for Cascade to follow.
### Workflow Discovery
Devin Desktop automatically discovers workflows from multiple locations to provide flexible organization:
* **Current workspace and sub-directories**: All `.devin/workflows/` (and legacy `.windsurf/workflows/`) directories within your current workspace and its sub-directories
* **Git repository structure**: For git repositories, Devin Desktop also searches up to the git root directory to find workflows in parent directories
* **Multiple workspace support**: When multiple folders are open in the same workspace, workflows are deduplicated and displayed with the shortest relative path
#### Workflow Storage Locations
| Scope | Location | Notes |
| - | - | - |
| Workspace | `.devin/workflows/*.md` (preferred) or `.windsurf/workflows/*.md` (fallback) | In your current workspace, any sub-directory, or any parent directory up to the git root. Committed with your repo. |
| Global | `~/.codeium/windsurf/global_workflows/*.md` | Available in every workspace on your machine. Not committed. |
| Built-in | Managed by Devin Desktop | Templates shipped with Devin Desktop (e.g. `/plan`). |
| [System (Enterprise)](#system-level-workflows-enterprise) | OS-specific (e.g. `/etc/devin/workflows/`, legacy `/etc/windsurf/workflows/`) | Deployed by IT, read-only for end users. |
When you create a new workflow through the UI, it will be saved in the `.devin/workflows/` directory of your current workspace, not necessarily at the git root. If you declined migration for a workspace that still has a `.windsurf/` directory, it is saved in `.windsurf/workflows/` instead. To create a global workflow, use the `+ Global` button in the Workflows panel or create the file directly in `~/.codeium/windsurf/global_workflows/`.
Workflow files are limited to 12000 characters each.
#### Generate a Workflow with Cascade
You can also ask Cascade to generate Workflows for you! This works particularly well for Workflows involving a series of steps in a particular CLI tool.
### Example Workflows
There are a myriad of use cases for Workflows, such as:
> **/address-pr-comments**
>
> This is a Workflow our team uses internally to address PR comments:
>
> ```
> 1. Check out the PR branch: `gh pr checkout [id]`
>
> 2. Get comments on PR
>
> bash
> gh api --paginate repos/[owner]/[repo]/pulls/[id]/comments | jq '.[] | {user: .user.login, body, path, line, original_line, created_at, in_reply_to_id, pull_request_review_id, commit_id}'
>
> 3. For EACH comment, do the following. Remember to address one comment at a time.
> a. Print out the following: "(index). From [user] on [file]:[lines] — [body]"
> b. Analyze the file and the line range.
> c. If you don't understand the comment, do not make a change. Just ask me for clarification, or to implement it myself.
> d. If you think you can make the change, make the change BEFORE moving onto the next comment.
>
> 4. After all comments are processed, summarize what you did, and which comments need the USER's attention.
> ```
> **/git-workflows**
>
> Commit using predefined formats and create pull requests with standardized title and descriptions using the appropriate CLI commands.
> **/dependency-management**
>
> Automate the installation or updating of project dependencies based on a configuration file (e.g., requirements.txt, package.json).
> **/code-formatting**
>
> Automatically run code formatters (like Prettier, Black) and linters (like ESLint, Flake8) on file save or before committing to maintain code style and catch errors early.
> **/run-tests-and-fix**
>
> Run or add unit or end-to-end tests and fix the errors automatically to ensure code quality before committing, merging, or deploying.
> **/deployment**
>
> Automate the steps to deploy your application to various environments (development, staging, production), including any necessary pre-deployment checks or post-deployment verifications.
> **/security-scan**
>
> Integrate and trigger security vulnerability scans on your codebase as part of the CI/CD pipeline or on demand.
### System-Level Workflows (Enterprise)
Enterprise organizations can deploy system-level workflows that are available globally across all workspaces and cannot be modified by end users without administrator permissions. This is ideal for enforcing organization-wide development processes, deployment procedures, and compliance workflows.
System-level workflows are loaded from OS-specific directories. Devin Desktop loads the `Devin` workflows directory if it exists and only falls back to the legacy `Windsurf` workflows directory when it does not. The two are not merged, so move any legacy workflows into the `Devin` directory when you create it:
**macOS:**
```
/Library/Application Support/Devin/workflows/*.md
/Library/Application Support/Windsurf/workflows/*.md # legacy fallback
```
**Linux/WSL:**
```
/etc/devin/workflows/*.md
/etc/windsurf/workflows/*.md # legacy fallback
```
**Windows:**
```
C:\ProgramData\Devin\workflows\*.md
C:\ProgramData\Windsurf\workflows\*.md # legacy fallback
```
Place your workflow files (as `.md` files) in the appropriate directory for your operating system. The system will automatically load all `.md` files from these directories.
#### Workflow Precedence
When workflows with the same name exist at multiple levels, system-level workflows take the highest precedence:
1. **System** (highest priority) - Organization-wide workflows deployed by IT
2. **Workspace** - Project-specific workflows in `.devin/workflows/` (or legacy `.windsurf/workflows/`)
3. **Global** - User-defined workflows in `~/.codeium/windsurf/global_workflows/`
4. **Built-in** - Default workflows provided by Devin Desktop
This means that if an organization deploys a system-level workflow with a specific name, it will override any workspace, global, or built-in workflow with the same name.
In the Devin Desktop UI, system-level workflows are displayed with a "System" label and cannot be deleted by end users.
> [!NOTE]
>
> **Important**: System-level workflows should be managed by your IT or security team. Ensure your internal teams handle deployment, updates, and compliance according to your organization's policies. You can use standard tools and workflows such as Mobile Device Management (MDM) or Configuration Management to do so.
## Worktrees
Devin Desktop supports using git worktrees to run Cascade tasks in parallel without interfering with your main workspace.
When using worktrees, each Cascade conversation gets its own session, allowing Cascade to make edits, or build and test code without interfering with your main workspace.
The [Devin Local agent](https://docs.devinenterprise.com/desktop/devin-local/worktrees.md) can also start a session in an existing worktree, picked from its agent location selector, and bring the changes back with a **Merge** button.
### Basic worktree usage
The simplest way to get started with using worktrees is switch to the "Worktree" mode in the bottom right corner of the Cascade input.
> [!NOTE]
>
> Currently, you can only switch to a worktree at the beginning of a Cascade session. Conversations cannot be moved to a different worktree once started.
After Cascade makes file changes in the worktree, you have the option of clicking "merge" to incorporate those changes back into your main workspace.
### Location
Worktrees are organized by repo name inside `~/.windsurf/worktrees/`.
Each worktree is given a unique random name.
To see a list of active worktrees, you can run `git worktree list` from within the repository directory.
> [!WARNING]
>
> Because worktrees live in a different directory than your original project, **build systems or tools that rely on relative paths** (e.g., `../shared-lib` references, symlinked dependencies, or monorepo source dependencies resolved by path) may break inside a worktree. If your project uses relative paths outside the repository root, configure a [`post_setup_worktree` hook](https://docs.devinenterprise.com/desktop/cascade#setup-hook) to create the necessary symlinks or copy the required files into the expected locations.
### Setup hook
Each worktree contains a copy of your repository files, but does not include `.env` files or other packages that aren't version-controlled.
If you would like to include additional files or packages in each worktree, you can use the `post_setup_worktree` hook to copy them into the worktree directory.
The `post_setup_worktree` hook runs after each worktree is created and configured. It is executed inside the new **worktree** directory.
The `$ROOT_WORKSPACE_PATH` environment variable points to the original workspace path and can be used to access files or run commands relative to the original repository.
#### Example
Copy environment files and install dependencies when a new worktree is created.
**Config** (in `.windsurf/hooks.json`):
```json theme={null}
{
"hooks": {
"post_setup_worktree": [
{
"command": "bash $ROOT_WORKSPACE_PATH/hooks/setup_worktree.sh",
"show_output": true
}
]
}
}
```
**Script** (`hooks/setup_worktree.sh`):
```bash theme={null}
#!/bin/bash
# Copy environment files from the original workspace
if [ -f "$ROOT_WORKSPACE_PATH/.env" ]; then
cp "$ROOT_WORKSPACE_PATH/.env" .env
echo "Copied .env file"
fi
if [ -f "$ROOT_WORKSPACE_PATH/.env.local" ]; then
cp "$ROOT_WORKSPACE_PATH/.env.local" .env.local
echo "Copied .env.local file"
fi
# Install dependencies
if [ -f "package.json" ]; then
npm install
echo "Installed npm dependencies"
fi
exit 0
```
This hook ensures each worktree has the necessary environment configuration and dependencies installed automatically.
### Cleanup
Devin Desktop automatically cleans up older worktrees when creating a new worktree to prevent excessive disk usage. Each workspace can have up to **20** worktrees.
Worktrees are cleaned up based on when they were last accessed—the oldest ones are removed first. This cleanup happens on a per-workspace basis, ensuring that worktrees from different repositories remain independent of each other.
Additionally, if you manually delete a Cascade conversation, Devin Desktop will automatically delete the associated worktree.
### Source Control Panel
By default, Devin Desktop does not show worktrees created by Cascade in the SCM Panel.
You can set `git.showDevinWorktrees` to `true` in your settings to override this and enable visualizing the worktrees in the SCM Panel.
> [!NOTE]
>
> The older `git.showWindsurfWorktrees` setting is deprecated. It is still honored for existing configurations when `git.showDevinWorktrees` is not set, but use `git.showDevinWorktrees` going forward.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.