# Billing
Source: https://docs.devinenterprise.com/admin/billing
Devin has two pricing models:
* **Self-serve**: Free, Pro, Max, and Teams plans you can sign up for directly at [app.devin.ai](https://app.devin.ai). Self-serve usage is billed through a mix of included quota and on-demand credits. See [Self-serve plans](/admin/billing/self-serve) for full details.
* **Enterprise**: Devin Enterprise customers are billed in Agent Compute Units (ACUs) at the rate set in their order form. See [Enterprise](/admin/billing/enterprise) for how ACU consumption is tracked, or [contact sales](https://cognition.com/contact) for pricing.
For how Devin meters work in general (how usage accrues, idle/sleep behavior, and tips for keeping consumption under control), see [Usage](/admin/billing/usage). The tips on that page apply to both pricing models.
# Enterprise
Source: https://docs.devinenterprise.com/admin/billing/enterprise
How Devin Enterprise contracts are billed and how admins track ACU consumption
Devin Enterprise customers are billed in **Agent Compute Units (ACUs)** at the rate set in their order form. [Contact sales](https://cognition.com/contact) for pricing.
For how Devin meters work in general (sleep behavior, what counts toward consumption, tips for keeping costs down), see [Usage](/admin/billing/usage).
## Tracking ACU consumption
Enterprise customers can track ACU consumption at both the Enterprise and Organization level:
* **Enterprise admins** view Enterprise ACU consumption at [Settings > Consumption](https://app.devin.ai/settings/consumption) in Enterprise Settings.
* **Organization admins** view Organization ACU consumption at [Settings > Consumption Analytics](https://app.devin.ai/settings/analytics?tab=consumption) within Organization Settings.
* **Any user** can see the ACU cost of a specific session from [Session Insights](/product-guides/session-insights).
## Setting Organization ACU limits
Enterprise admins can set per-Organization ACU limits from [Settings > Organizations](https://app.devin.ai/settings/organizations) in Enterprise Settings.
Once set, an Organization can only consume up to its limit. All Devin activity stops once the limit is reached, and users see a message indicating the Organization has hit its ACU limit and to contact the Enterprise admin to raise it.
## Frequently asked questions
Enterprise customers are billed for ACUs as stated in their order form.
Enterprise ACUs represent the work performed by Devin for customers on the Enterprise plan, which adheres more strictly to task planning and end-to-end testing. They are distinct from self-serve quota and on-demand credits, and are priced per the customer's Enterprise order form.
Enterprise admins can break consumption down by Organization from the [Consumption](https://app.devin.ai/settings/consumption) page in Enterprise Settings. Org admins can break it down by user from [Consumption Analytics](https://app.devin.ai/settings/analytics?tab=consumption) inside Organization Settings.
# Self-serve plans
Source: https://docs.devinenterprise.com/admin/billing/self-serve
Compare Devin's self-serve plans and understand usage quota and on-demand credits
Devin has four self-serve plans you can sign up for directly at [app.devin.ai](https://app.devin.ai). For authoritative pricing, see the [Devin pricing page](https://devin.ai/pricing). This page explains how the plans relate to each other and how billing mechanics work.
## Plan overview
| Plan | For | Price | Members |
| --------- | --------------------------------- | ------------------ | --------- |
| **Free** | Individuals trying Devin | Free | 1 |
| **Pro** | Individual users | \$20/month | 1 |
| **Max** | Power users who need more quota | \$200/month | 1 |
| **Teams** | Teams working with Devin together | \$80/month minimum | Unlimited |
The **Pro** and **Max** plans are individual plans. They cannot be shared across multiple users. If you want multiple people to use Devin under a single subscription, you need the **Teams** plan.
## Free
The Free plan lets you try Devin with limited usage. It includes:
* Limited Devin usage
* Access to [Devin Review](/work-with-devin/devin-review)
* Access to [DeepWiki](/work-with-devin/deepwiki)
Free users can upgrade to any paid plan at any time from [Settings > Plans](https://app.devin.ai/settings/plans).
## Pro
Pro is Devin's entry-level individual plan. It's designed for a single developer who uses Devin regularly. Pro includes:
* A daily and weekly usage quota that covers Devin sessions, [Devin CLI](/cli), and [Devin Desktop](https://windsurf.com)
* Pay-as-you-go [on-demand credits](#on-demand-credits) for usage past your quota
* Slack, Linear, and [MCP](/work-with-devin/mcp) integrations
Pro is a single-user plan. Pro subscribers cannot invite additional members to their organization. To work with teammates on a shared subscription, use the [Teams](#teams) plan.
## Max
Max is for individual users who consistently exceed the Pro quota. It includes everything in Pro, plus a significantly larger weekly usage quota (with no daily cap), also shared between Devin sessions, [Devin CLI](/cli), and Devin Desktop.
Like Pro, Max is a single-user plan and does not support multiple members.
## Teams
The Teams plan is Devin's self-serve plan for teams of any size. Key properties:
* **Unlimited members**: invite as many teammates as you want.
* **\$80/month minimum**: every Teams account pays at least \$80/month.
* Each member gets either a **full seat** or a **flex seat**.
* **On-demand credits** are shared across the whole team.
### Full seats vs. flex seats
Every member of a Teams account holds one of two seat types:
**\$40/month per seat**, billed as a fixed recurring line item.
Best for members who use Devin regularly. Each full seat includes:
* A daily and weekly usage quota equivalent to the Pro plan
* Access to Devin Desktop
**Free**. Teams can have unlimited flex seats.
Best for occasional users. Flex seats:
* Draw entirely from the team's shared pool of on-demand credits
* Do **not** include Devin Desktop access
* Have no fixed monthly charge per seat
Admins choose the seat type when [inviting a member](/product-guides/invite-team), and can convert a member between seat types later from **Settings > Members**.
### The \$80 Teams minimum
Every Teams subscription costs **at least \$80/month**. You can hit this minimum in any combination of full seats (\$40 each) and on-demand credits:
| Full seats | On-demand credits included | Monthly total |
| ---------: | -------------------------: | ------------: |
| 0 | \$80 | \$80 |
| 1 | \$40 | \$80 |
| 2 | \$0 | \$80 |
| 3 | \$0 | \$120 |
| *N* ≥ 2 | \$0 | *N* × \$40 |
When you have fewer than two full seats, the remainder of the \$80 minimum is automatically charged as prepaid on-demand credits that the whole team can draw from. Once you have two or more full seats, you've cleared the minimum and no additional on-demand credits are included, but you can still [top up on-demand credits](#on-demand-credits) at any time.
Give a full seat to anyone who uses Devin regularly. Full seats include their own Pro-equivalent quota and Devin Desktop access at a predictable fixed cost, making them the best fit for power users. Reserve flex seats for occasional or trial users who only need ad-hoc access through shared on-demand credits.
## How quotas work
Each paid plan and full seat includes a usage allowance that refreshes automatically on a calendar basis:
* **Pro** and **Teams full seats** have a **daily and weekly** allowance. The daily allowance is more than 1/7 of the weekly, so you can keep working through weekends without giving up overall capacity for the week.
* **Max** has a **weekly** allowance only, with no daily cap.
When you've used up your allowance, [on-demand credits](#on-demand-credits) keep you working without interruption.
## On-demand credits
On-demand credits are prepaid usage credit that fund any work past your plan's included quota:
* **Roll over** month-to-month. Purchased credits never expire.
* Can be topped up at any time from [Settings > Plans](https://app.devin.ai/settings/plans), and optionally refilled automatically via auto-reload.
* Admins can set auto-reload thresholds and default session spending limits from **Settings > Usage**.
* On the **Teams** plan, credits are **shared across all members**, with no per-member balance. Any teammate can draw from the shared pool.
* On the **Teams** plan, credits fund all usage on **flex seats** and any **full seat** usage past its included quota, and cover any portion of the [\$80/month minimum](#the-80-teams-minimum) not already covered by full seats.
## Devin Review and Automations Pricing
[Automations](/product-guides/automations) and [Devin Review](/work-with-devin/devin-review) are available on self-serve plans.
* **Teams use shared on-demand credits.** On the Teams plan, Automations and Devin Review draw directly from the team's shared [on-demand credit](#on-demand-credits) pool and do not consume full-seat quota.
* **What happens when you run out of credits.** If you run out of credits, Automations stop running and Devin Review switches to its smart diff viewer. Top up [on-demand credits](#on-demand-credits) to start Automations again and re-enable AI-powered review.
* **Public PRs are free.** Anyone can review a public GitHub PR at [devinreview.com](https://devinreview.com) — or by replacing `github.com` with `devinreview.com` in any PR URL — without a Devin account, and no on-demand credits are consumed.
Admins can keep usage predictable by tuning how often auto-review runs. Configure the trigger mode (every commit, only when a PR is first opened, or manual only) per repository or per user from [Settings > Review](https://app.devin.ai/settings/review). See [Trigger Modes](/work-with-devin/devin-review#trigger-modes) in the Devin Review docs for details.
## Migrating from legacy ACU-based plans
If you were previously on a legacy ACU-based plan, here's what you need to know:
* On-demand credits are the same dollar value as the ACUs you're used to.
* **Legacy Core plan users** have been migrated to the Free plan and can continue using any remaining on-demand credits. To purchase additional credits, upgrade to the [Teams](#teams) plan.
## Managing your plan
Admins can view and change the account's plan from [Settings > Plans](https://app.devin.ai/settings/plans). From there you can:
* Upgrade or downgrade between Free, Pro, Max, and Teams
* Add or cancel Teams full seats
* Purchase on-demand credits or configure auto-reload to replenish them automatically
* Download past invoices
For tips on keeping consumption under control across all plans, see [Usage](/admin/billing/usage).
# Usage
Source: https://docs.devinenterprise.com/admin/billing/usage
How Devin meters work, what counts toward consumption, and how to keep usage under control
This page explains how Devin's work is metered. The mechanics are the same regardless of pricing model. The only difference is the unit:
* **Enterprise** customers consume **Agent Compute Units (ACUs)** against the volume in their order form.
* **Self-serve** customers consume their plan's included quota first, then draw from prepaid **on-demand credits**.
Throughout this page, "usage" refers to whichever unit applies to your account.
## What counts toward usage
Usage accrues based on the work Devin actually performs in a session, including:
* Number and complexity of actions Devin takes (planning, context gathering, task execution, browser actions, code execution, and so on)
* Virtual machine time and networking bandwidth (typically a small fraction of total usage)
### Windows sessions
Windows sessions consume approximately **9% more** usage than equivalent Linux (Ubuntu) sessions.
Aside from the few units required to keep the Devin VM running, Devin will not consume usage when:
* Waiting for your response
* Waiting for a test suite to run
* Setting up and cloning repositories
## Sleep and idle behavior
When a session is idle, Devin goes to sleep. While sleeping, Devin does not consume usage. You can wake the session up at any time by sending another message. Devin typically sleeps automatically after roughly 0.1 ACUs (or the equivalent quota / on-demand credit) of inactivity.
## Managing usage effectively
A number of variables affect how much Devin consumes:
* Task complexity
* Prompt quality (or specificity)
* Size of context or codebase
* Number of files being touched or modified
* Session runtime
* Length of conversation
* Frequency of back-and-forth messaging
A few tips to keep usage under control:
* Delegate clearly scoped tasks with a well-defined end goal
* Keep prompts and sessions short
* Avoid asking Devin to do a lot of different tasks in the same session
* Split big projects into sub-tasks across sessions; there are no concurrent session limits, so take advantage of it
These tips also tend to improve the quality of Devin's work, so it's a win-win.
## Frequently asked questions
No, Devin does not consume any usage while sleeping.
Devin typically sleeps automatically after roughly 0.1 ACUs (or the equivalent quota / on-demand credit) of inactivity, so awake-but-idle time generally adds up to very little.
Any user can see per-session usage from [Session Insights](/product-guides/session-insights), regardless of pricing model.
* **Self-serve**: Current month's usage, quota remaining, and on-demand credit balance live at [Settings > Plans](https://app.devin.ai/settings/plans).
* **Enterprise**: Enterprise and per-Organization ACU consumption are available from the [Consumption](https://app.devin.ai/settings/consumption) and [Consumption Analytics](https://app.devin.ai/settings/analytics?tab=consumption) pages in Enterprise and Organization Settings respectively.
Yes. If your enterprise enables [Personal Analytics](/enterprise/security-access/personal-analytics), users with the **View Personal Analytics** permission can see their own ACU consumption across every organization from the **My analytics** page in their settings.
# Common Issues
Source: https://docs.devinenterprise.com/admin/common-issues
## I'm unable to connect my GitHub.com organization
If you're unable to set up your integration or seeing "Configure" next to the organization you want to connect, you or one of your teammates has likely already connected your GitHub organization to another Devin account. **You will need to disconnect the existing integration before you can connect to your Devin account.**
You can disconnect the existing integration by following these steps:
1. Navigate to the Devin Enterprise or Organization with the active integration
2. Navigate to the Integrations page
* If you are on an Enterprise account, navigate to [https://app.devin.ai/settings/connected-accounts](https://app.devin.ai/settings/connected-accounts) in Enterprise Settings
* If you are on a Teams account, navigate to [https://app.devin.ai/settings/integrations](https://app.devin.ai/settings/integrations) in Organization Settings
3. Click through on the GitHub integration card
4. Click "Disconnect" under the GitHub integration
Alternatively, you can disconnect the integration via GitHub:
1. Go to the [GitHub Integration settings](https://github.com/settings/installations)
2. Navigate to Devin.ai Integration and click "Configure"
3. Scroll to the "Danger zone" section to uninstall the integration
## I'm unable to connect my Slack organization
If you're seeing an "Unable to proceed with request" error, it means that you or one of your teammates has already connected your Slack organization to another Devin organization. **You will need to disconnect the existing integration before you can connect your new organization.**
You can disconnect the existing integration by following these steps:
1. Navigate to the Devin Enterprise or Organization with the active integration
2. Navigate to the Integrations page
* If you are on an Enterprise account, navigate to [https://app.devin.ai/settings/connected-accounts](https://app.devin.ai/settings/connected-accounts) in Enterprise Settings
* If you are on a Teams account, navigate to [https://app.devin.ai/settings/integrations](https://app.devin.ai/settings/integrations) in Organization Settings
3. Click through on the Slack integration card
4. Click "Disconnect" under the Slack integration
If you're unable to disconnect or find the existing organization, please reach out to [support@cognition.ai](mailto:support@cognition.ai)
## IP Allowlisting
If you need to allowlist Devin's services, please add the following IP addresses:
* 100.20.50.251
* 44.238.19.62
* 52.10.84.81
* 52.183.72.253
* 20.172.46.235
* 52.159.232.99
* 4.204.199.103
* 140.232.64.0/26
(Please note: While we intend to keep this list static, it is possible these IPs may change in future updates.)
## Session Expiration
Devin sessions can't be continued after 30 days. If you need to resume work after that window, start a new session and re-share any relevant context (for example: goals, requirements, key decisions, and any important files or links) so Devin can continue effectively.
# Security at Cognition
Source: https://docs.devinenterprise.com/admin/security
We want Devin to be a core contributor in your organization, and have prioritized security, data privacy and compliance to make it possible
## Security
All data transmission is encrypted in transit and at rest. Production software is also routinely monitored via logging, error handling and monitoring dashboards of live metrics. Unusual application states (i.e. unusually high error rates, slowness, failures) trigger alerts which are quickly investigated by our team.
Access to our cloud environment in AWS is granted on an as-required basis based on business roles and only a small number of employees or contractors are granted direct access to production systems.
All employees and contractors are required to use multi-factor authentication on all main work applications. All employees and contractors also receive annual training about security best practices, including good password management and how to identify social engineering and phishing scams.
Cognition obtained SOC 2 Type II certification and conducted Security Training in March 2024 for all employees at Cognition. As part of the SOC 2 audit, Cognition's auditors reviewed all of Cognition's security policies, procedures, internal and third party controls related to data security, privacy, processing integrity, confidentiality and availability.
For more details about our security please visit our [Trust Center](https://trust.cognition.ai/).
If you have identified a potential security issue, we encourage you to share your findings with us. Please send your vulnerability reports to our security team at [security@cognition.ai](mailto:security@cognition.ai).
## Privacy & Intellectual Property
Cognition processes data based on the application Customers use to interact with Devin. Devin can be accessed via web application, integration with GitHub, or integration with Slack. For the web application, Cognition only processes data actively provided by the authorized user prompting Devin; for the GitHub and Slack integrations, the administrator installing the integration can review and manage all permissions granted to Devin.
Cognition uses Customer data to:
* Deliver, maintain and update services provided to the Customer per their configuration and type of Devin access (e.g. web application, integration with GitHub, or integration with Slack) to make sure the software is up-to-date and operational.
* Troubleshoot, prevent and resolve issues such as product-related issues, software bugs or security incidents to maintain service functionality and reliability.
Cognition only retains data processed through Devin for the duration of the relationship with a given Customer, unless otherwise specified by the Customers.
Any Feedback Data and User Interaction Data are retained as long as needed and as determined by Cognition.
By default, we may use your data for model training purposes to improve and enhance the Services. If you're on a paid plan, you can opt out at any time on the Data Controls settings page. After you opt out, your data will not be used for training and Zero Data Retention will be enabled with our model providers. On the Teams plan, only an administrator can exercise the opt-out. Devin can still learn to fit into your unique workflow via the [Knowledge](/product-guides/knowledge) feature. When you share Knowledge, Devin can become more reliable at working on your specific projects over time.
If you are an Enterprise customer, we will never train on your data without your express prior written consent. Please refer to the terms in your agreement with Cognition for details.
The output — code, work product, or other — produced by Devin is considered the user’s intellectual property and can be used for the Customer’s commercial purposes, with the exception of using the output to train models that would attempt to reverse engineer and/or build a competing product to Devin.
When setting up the GitHub integration, users can select which repositories Devin can access, with permissions adjustable through GitHub's App Settings during and post-installation.
For more details on the requested permissions and security considerations go to [GitHub Integration Guide](/integrations/gh).
In Slack, Devin doesn’t read, process or store any data in your Slack instance other than the information provided when @Devin is tagged, initially prompted and when any additional information is provided within the Slack thread while the session is ongoing.
For more details on the requested permissions and security considerations go to [Integration with Slack Guide](/integrations/slack).
## User Best Practices
While Devin’s performance is improving daily, it can still experience hallucinations, introduce bugs into code, or suggest insecure code or procedures. Like with any coding best practices, we recommend taking the appropriate precautions with the code written by Devin such as code reviews, enabling branch protections to ensure checks are enforced before Devin can merge any changes, and any practices currently adopted in your organization to review engineers’ work.
You may need to provide Devin with credentials and keys such as passwords, API keys, cookies or other for authentication. In all cases we advise users to leverage our Secrets feature under the Settings page to share and store those credentials securely.
We’re still learning and developing Devin to be a great AI software engineer, and our customers’ feedback is crucial for Devin’s development. We strongly encourage sharing feedback and feature requests directly with your Cognition account team or by emailing [support@cognition.ai](mailto:support@cognition.ai), and reporting incidents by emailing [security@cognition.ai](mailto:security@cognition.ai).
# JetBrains
Source: https://docs.devinenterprise.com/cli/acp/jetbrains
Run Devin inside JetBrains IDEs from AI Chat using the Agent Client Protocol (ACP), including JetBrains Remote Development.
JetBrains IDEs can run Devin as an agent inside **AI Chat** using the
[Agent Client Protocol (ACP)](https://agentclientprotocol.com/). The quickest way to
add Devin is to install it from the **ACP Registry**; you can also configure it
manually as a custom agent. Either way, you can drive Devin from the AI Chat panel in
IntelliJ IDEA, PyCharm, GoLand, and other JetBrains IDEs — including over
[JetBrains Remote Development](https://www.jetbrains.com/remote-development/).
This integration uses JetBrains' built-in ACP support in AI Assistant. For the
upstream reference, see the JetBrains docs on
[adding a custom agent](https://www.jetbrains.com/help/ai-assistant/acp.html#add-custom-agent).
## Prerequisites
* A JetBrains IDE with the **AI Assistant** plugin and AI Chat available.
## Setup
Install Devin directly from the **ACP Registry** — no CLI installation or manual
configuration required.
Click the **AI Chat** icon in the right-hand tool window bar.
Click the agent selector in the AI Chat footer to see the list of available
agents.
Choose **Install From ACP Registry...**, search for **Devin**, and click
**Install**. Devin is added to the list of available agents.
The first time you connect, you may be prompted to authenticate. Follow the
prompt to log in to your Devin account.
Select **Devin** in the agent selector and send a message to start a session.
## Manual setup (custom ACP)
If you'd rather run Devin from your own installation of the Devin CLI, you can add it
as a custom ACP agent instead of installing from the registry.
### Prerequisites
* Devin CLI installed and authenticated. If you haven't installed it yet, follow
the [Quickstart](/cli/index), then run `devin auth login`.
* The absolute path to the `devin` binary. You can find it with:
```bash theme={null}
which devin
```
This typically resolves to something like `~/.local/bin/devin`.
For **JetBrains Remote Development**, Devin CLI must be installed on the **remote
host** (where the backend runs), not on your local client. Run `which devin` in a
terminal on the remote host and use that path in the configuration below.
Click the **AI Chat** icon in the right-hand tool window bar.
Click the three-dots menu in the top-right of the AI Chat panel, then choose
**Add Custom Agent**. This opens the `acp.json` configuration file.
Add Devin to the `agent_servers` block in `acp.json`. Set `command` to the
absolute path of your `devin` binary (from `which devin`) and pass `acp` as
the only argument:
```json acp.json theme={null}
{
"default_mcp_settings": {},
"agent_servers": {
"devin": {
"command": "/home/you/.local/bin/devin",
"args": ["acp"]
}
}
}
```
Save the file. Devin now appears as a selectable agent in AI Chat.
Select **devin** as the agent in AI Chat and send a message to start a
session. The first time you connect, you may be prompted to authenticate;
Devin uses the credentials from `devin auth login` (or `WINDSURF_API_KEY` if
set).
## Managing the integration
The three-dots menu in the AI Chat panel includes a few helpful actions for the
Devin agent:
* **Reset ACP Authentication** — clear stored ACP credentials and re-authenticate.
* **Get ACP Logs** — open the ACP logs, useful for debugging connection issues or
inspecting what the agent is doing under the hood.
## Notes and limitations
* Devin's slash commands are advertised over ACP, so they appear in JetBrains AI
Chat's own command palette — see
[Slash commands in ACP hosts](/cli/reference/commands#slash-commands-in-acp-hosts).
* Devin CLI's terminal/shell output is surfaced through JetBrains AI Chat's ACP
rendering, which differs from the native Devin CLI terminal UI. Some richer
interactions are only available in the standalone CLI.
* The `devin acp` subcommand is intended to be launched by an ACP-aware client
(like JetBrains AI Chat) as a subprocess — it speaks JSON-RPC over stdio and is
not meant to be run interactively. See
[`devin acp`](/cli/reference/commands#devin-acp) in the command reference.
# Xcode
Source: https://docs.devinenterprise.com/cli/acp/xcode
Run Devin inside Xcode's coding assistant via the Agent Client Protocol (ACP), or give the Devin CLI access to your Xcode project through Xcode's MCP bridge.
Xcode 26.6's [coding intelligence](https://developer.apple.com/documentation/xcode/setting-up-coding-intelligence)
can run Devin as an agent inside the **coding assistant** using the
[Agent Client Protocol (ACP)](https://agentclientprotocol.com/). Devin isn't one
of the agents listed in Xcode's Intelligence settings, so you add it manually as
a custom ACP agent that runs from your local Devin CLI installation.
This integration uses Xcode's built-in ACP support in the coding assistant. For
the upstream reference, see Apple's docs on
[setting up coding intelligence](https://developer.apple.com/documentation/xcode/setting-up-coding-intelligence).
## Prerequisites
* **Xcode 26.6 or later** with the coding assistant available.
* Devin CLI installed and authenticated. If you haven't installed it yet, follow
the [Quickstart](/cli/index), then run `devin auth login`.
* The **absolute** path to the `devin` binary. You can find it with:
```bash theme={null}
which devin
```
This typically resolves to something like `/Users/you/.local/bin/devin`.
Xcode requires an **absolute** path for the agent command — it does not expand
`~` or use your shell's `PATH`. If `which devin` prints a `~`-prefixed path,
expand it first (for example, run `echo "$(cd ~ && pwd)/.local/bin/devin"`) and
use the full `/Users/...` result.
## Setup
Add Devin as a custom agent from the Intelligence settings.
Choose **Xcode > Settings**, then select **Intelligence** in the sidebar.
Under **Agents**, click **Add an Agent**. Xcode's built-in ACP support lets
you register any agent that speaks the Agent Client Protocol.
In the sheet that appears, enter the agent's details:
* **Name** — `Devin` (or any label you prefer).
* **Command** — the **absolute** path to your `devin` binary (from
`which devin`), for example `/Users/you/.local/bin/devin`. A relative path
or a `~`-prefixed path won't work.
* **Arguments** — `acp`. Add `--model ` (for example `acp --model opus`)
to pick the model Devin uses; see
[`devin acp`](/cli/reference/commands#devin-acp).
Click **Add**. Devin now appears as a selectable agent under **Agents**.
Select **Devin** in the coding assistant and send a message to start a
session. The first time you connect, you may be prompted to authenticate;
Devin uses the credentials from `devin auth login` (or `WINDSURF_API_KEY` if
set).
## Give Devin CLI access to your Xcode project (MCP)
Separately from running Devin *inside* Xcode, you can point the standalone Devin
CLI at your Xcode project so it can build, run tests, read and edit files, render
SwiftUI previews, and search Apple's documentation. Xcode ships an
[MCP](/cli/extensibility/mcp/overview) server, `xcrun mcpbridge`, that exposes
these Xcode tools to any external agent (the same mechanism
[Cursor uses](https://cursor.com/docs/integrations/xcode)). Add it to Devin like
any other MCP server.
The Xcode MCP bridge requires **Xcode 26.3 or later**. Confirm the binary is
available with `xcrun --find mcpbridge` (see [Troubleshooting](#troubleshooting)
if it isn't). See Apple's docs on
[giving external agents access to Xcode](https://developer.apple.com/documentation/xcode/giving-external-agents-access-to-xcode).
Choose **Xcode > Settings**, select **Intelligence**, and under **Model
Context Protocol** turn on **Allow external agents to use Xcode tools**.
Register `xcrun mcpbridge` as a stdio MCP server:
```bash theme={null}
devin mcp add xcode -- xcrun mcpbridge
```
Verify it was added with `devin mcp list`. See
[`devin mcp`](/cli/reference/commands#devin-mcp) for scope and configuration
options.
Open your project or workspace in Xcode (the bridge needs a running Xcode
session with a project open), then prompt Devin from the CLI. Xcode alerts
you when the external agent connects and while it's active.
## Troubleshooting
* **`xcrun: error: unable to find utility "mcpbridge"`** — your system is pointed
at the Command Line Tools instead of the full Xcode install. Fix it with:
```bash theme={null}
sudo xcode-select -s /Applications/Xcode.app/Contents/Developer
sudo xcodebuild -runFirstLaunch
```
Then confirm with `xcrun --find mcpbridge`, which should print a path.
* **Devin can't reach the Xcode tools** — make sure Xcode is running with a
project (not an empty window) open, and that **Allow external agents to use
Xcode tools** is enabled in Intelligence settings.
## Notes and limitations
* The model can't be switched from Xcode's UI. To use something other than your
team's default model, pass `--model ` in the agent's **Arguments** field
(see [`devin acp`](/cli/reference/commands#devin-acp)), which sets the model for
every session Xcode starts.
* When you select an agent in Xcode's coding assistant, it automatically gets
access to Xcode capabilities such as building and testing your app. You can
review and restrict which commands and tools agents may use under
**Agents > Permissions** in Intelligence settings — see Apple's docs on
[extending and customizing agents](https://developer.apple.com/documentation/xcode/extending-and-customizing-agents).
* Xcode's coding assistant does not surface Devin's slash commands.
* Devin CLI's terminal/shell output is surfaced through Xcode's ACP rendering,
which differs from the native Devin CLI terminal UI. Some richer interactions
are only available in the standalone CLI.
* The `devin acp` subcommand is intended to be launched by an ACP-aware client
(like Xcode's coding assistant) as a subprocess — it speaks JSON-RPC over stdio
and is not meant to be run interactively. See
[`devin acp`](/cli/reference/commands#devin-acp) in the command reference.
# Zed
Source: https://docs.devinenterprise.com/cli/acp/zed
Run Devin CLI inside the Zed editor as a custom ACP agent in the Agent Panel.
[Zed](https://zed.dev/) has native support for the
[Agent Client Protocol (ACP)](https://agentclientprotocol.com/), so you can run
Devin CLI as a custom external agent directly inside Zed's **Agent Panel** —
with real-time editing, syntax highlighting, and agent following.
This integration uses Zed's built-in support for external ACP agents. For the
upstream reference, see the Zed docs on
[external agents](https://zed.dev/docs/ai/external-agents).
## Setup
Open the ACP registry with `zed: acp registry` from the command palette (Cmd+Shift+P on macOS and Ctrl+Shift+P on Windows). Search for "Devin" and install it.
On the top left corner of the Threads Sidebar, click on the agent dropdown menu and select "Devin".
In the new Devin thread, open the agent menu in the top right corner and select "Authenticate" (or "Reauthenticate"). Then on the bottom of the thread panel, click on "API Key". A browser window will open, where you can log into your Devin Cloud account and authenticate. If you don't have an account you can sign up for free!
You can now start a conversation with Devin! By default, Devin will use Adaptive model selection, automatically choosing the best model for your task. You can also pick a specific model from the menu at the bottom of the thread panel.
## Notes and limitations
* Devin's slash commands are advertised over ACP, so they appear in Zed's own
command palette — see
[Slash commands in ACP hosts](/cli/reference/commands#slash-commands-in-acp-hosts).
* Devin CLI's terminal/shell output is surfaced through Zed's ACP rendering,
which differs from the native Devin CLI terminal UI. Some richer interactions
are only available in the standalone CLI.
* The `devin acp` subcommand is intended to be launched by an ACP-aware client
(like Zed) as a subprocess — it speaks JSON-RPC over stdio and is not meant to
be run interactively. See
[`devin acp`](/cli/reference/commands#devin-acp) in the command reference.
# Adaptive
Source: https://docs.devinenterprise.com/cli/adaptive
Adaptive is Cognition's intelligent model router that automatically selects the best AI model for each task.
## Selecting Adaptive
To select Adaptive, run `/model adaptive` during a session, pass `--model adaptive` when launching, or set it as your default in `~/.config/devin/config.json` (on Windows, `%APPDATA%\devin\config.json`):
```json theme={null}
{
"agent": {
"model": "adaptive"
}
}
```
You can switch away from Adaptive to a specific model at any time with `/model`.
Adaptive is an intelligent model router that automatically selects the best AI model for each task. Instead of manually choosing between dozens of models, Adaptive analyzes your prompt and routes it to the model that will deliver the best result.
## How it works
When you select **Adaptive**, Devin evaluates each request and dynamically chooses the right underlying model. Simple tasks get routed to fast, efficient models. Complex tasks get routed to more capable ones.
This means you get the right level of intelligence for every prompt without overspending on premium models for routine work. Adaptive helps your usage allowance last longer by avoiding unnecessary use of expensive models.
Adaptive is the best default for most users.
## Enterprise availability
For enterprise organizations, Adaptive is disabled by default. An admin must enable the **Adaptive model router** setting from the enterprise settings page before team members can select Adaptive in the model picker.
* **Devin Desktop**: Go to **Settings > Devin Desktop > Models** and toggle **Adaptive model router** on.
* **Windsurf**: Go to **Team Settings > Models** and toggle **Adaptive model router** on.
## Pricing
Adaptive pricing depends on your billing plan.
Adaptive draws down your quota at a **fixed per-token rate**, regardless of which underlying model is selected for a given request.
Currently, the Adaptive model consumes quota and overage at an introductory promotional rate (through July 7, 2026).
| Token type | Cost per 1M tokens |
| :---------------- | :----------------- |
| Input tokens | \$0.50 |
| Output tokens | \$2.00 |
| Cache read tokens | \$0.10 |
These rates also apply to extra usage beyond your included quota.
Because Adaptive routes simpler tasks to lighter models, it typically consumes fewer tokens overall than manually selecting a frontier model for every request. This makes it the most cost-effective option for most users.
For customers on the Cognition platform, Adaptive usage is metered in **ACUs** (Agent Compute Units). ACU consumption scales with the tokens used and the model selected by the router for each request.
For enterprise customers on credit-based billing, Adaptive uses **variable-token credit pricing**. Each request consumes credits based on the actual tokens used and the model that Adaptive selects for that request according to your credit rate.
This means cheaper models cost fewer credits per request, and Adaptive's routing naturally favors cost-efficient choices — so your credit pool lasts longer compared to always selecting a premium model.
## Tips for getting the most out of Adaptive
* **Be specific with your prompts.** Clear, focused instructions help Adaptive route to the right model and reduce unnecessary token usage.
* **Leverage prompt caching.** Staying on the same model across turns in a conversation enables caching, which significantly reduces input token costs. Adaptive takes this into account when routing.
* **Use Adaptive as your default.** For most workflows, Adaptive is the best starting point. Switch to a specific model only when you have a particular reason to — for example, if you need a specific model's reasoning capabilities for a complex task.
# Controls
Source: https://docs.devinenterprise.com/cli/enterprise/controls
Devin CLI is a local agent like Cascade, but does not yet implement all of the same features and controls.
Devin CLI is a local agent that runs on your machine with access to your local files, tools, and environment — similar to Cascade in Devin Desktop. It shares the same agent harness as the [Devin Local agent](/desktop/devin-local).
Because it is a newer agent, Devin CLI does not yet implement all of the same features and controls as Cascade. Many of Cascade's controls are replaced by more flexible mechanisms — for example, [permissions](/cli/reference/permissions), [hooks](/cli/extensibility/hooks/overview), and [team settings](/cli/enterprise/team-settings).
## Limitations
The gap runs both ways: [plugins](/cli/extensibility/plugins/overview) and [subagents](/cli/subagents) have no Cascade equivalent at all, and recent releases brought [plan mode](/desktop/devin-local#plan-mode) and [merging worktree sessions](/desktop/devin-local#worktree-sessions) to parity with Cascade. The list below covers the Cascade features this agent does not have yet.
The following features are not currently supported with the Devin Local agent:
* **Memories** — The Devin Local agent does not persist memories between sessions. Migrate your critical memories to [skills](/desktop/cascade/skills) with the **Devin: Open Cascade Migration Wizard** command.
* **Workflows** — Workflows are not available with the Devin Local agent. Migrate your workflows to [skills](/desktop/cascade/skills) with the **Devin: Open Cascade Migration Wizard** command.
* **Code Lenses** - Currently [code lenses](/desktop/command/windsurf-related-features) do not yet trigger the Devin Local agent.
* **App Deploys** - The Devin Local agent does not support app deploys.
* **Conversation Sharing** - Conversation sharing is not yet available with the Devin Local agent.
* **Arena Mode** - [Arena mode](/desktop/cascade/arena) is not available with the Devin Local agent.
The Devin Local agent does support [rules and AGENTS.md files](https://cli.devin.ai/docs/extensibility/rules) as well as [skills](https://cli.devin.ai/docs/extensibility/skills/overview) for providing persistent context and reusable workflows.
### Analytics
Devin Local activity is reported in the [`cascade_runs`](/desktop/accounts/api-reference/cascade-analytics) data source (model usage, messages sent, and credit consumption), the [`cascade_tool_usage`](/desktop/accounts/api-reference/cascade-analytics) data source (per-tool call counts such as Code Edit, Run Command, Search Web, and MCP Tool), the [`cascade_lines`](/desktop/accounts/api-reference/cascade-analytics) data source (daily lines of code written by the agent), and the [Cascade Data source](/desktop/accounts/analytics-api#cascade-data) of the Custom Analytics API.
Unlike Cascade, Devin Local does not track specific suggested lines or "modes" when operating: an edit only runs after you approve it, so accepted lines equal suggested lines, and the `mode` field in `cascade_runs` is not populated.
The Devin CLI does not report analytics for [hybrid deployments](https://devin.ai/blog/self-hosted-deployment-maintenance-mode).
### Enterprise controls
Enterprise admins can configure the Devin Local agent through [team settings](https://windsurf.com/team/settings), including [new controls only available with the Devin Local agent](https://cli.devin.ai/docs/enterprise/team-settings):
* **Sandbox enforcement** - Require sandbox mode for all users and configure organization-wide domain filtering rules
* **Granular permissions** - Control which actions the agent can take with more fine-grained permissions
* **Network enforcement** - Control network access with allowed and denied domains
Additionally, the "Enable Cascade" control can be used to disable the legacy Cascade agent entirely to ensure your team follows the new controls available with Devin CLI.
#### Unsupported enterprise controls
The following legacy enterprise controls are not available with the Devin Local agent:
* **Restrict Tool Calls to Workspace** - by default, the Devin Local agent can only read/edit files within the workspace.
Custom [permissions](https://cli.devin.ai/docs/reference/permissions) are a more flexible replacement that can be used to replicate the same rules.
* **App Deploys** - App deploys are not yet supported with the Devin Local agent.
* **Conversation Sharing** - Conversation sharing is not yet supported with the Devin Local agent.
* **Global tool calling disabled** - If you previously disabled tool calling entirely, write an equivalent [permission policy](https://cli.devin.ai/docs/reference/permissions) for Devin CLI instead.
The following legacy controls will still be enforced as a fallback if you haven't yet implemented an enterprise CLI permission config:
* **Auto Run Terminal Commands** - The Devin Local agent uses its own [permissions model](https://cli.devin.ai/docs/reference/permissions) instead of auto-execution levels; we recommend using this instead, but the old control will still be enforced as a fallback.
* **Terminal allow lists** - Implement an equivalent [permission policy](https://cli.devin.ai/docs/reference/permissions) for Devin CLI to allow specific terminal commands.
* **Terminal deny lists** - Implement an equivalent [permission policy](https://cli.devin.ai/docs/reference/permissions) for Devin CLI to deny specific terminal commands.
## Further reading
* [Team settings](/cli/enterprise/team-settings)
* [System configuration](/cli/enterprise/system-config)
* [Permissions](/cli/reference/permissions)
* [Hooks](/cli/extensibility/hooks/overview)
* [Devin Local agent](/desktop/devin-local)
# Devin Auth
Source: https://docs.devinenterprise.com/cli/enterprise/devin-auth
Authenticate to Devin CLI using your existing Devin account
## Overview
You can authenticate to Devin CLI using your existing Devin account. This provides a seamless experience for organizations already using Devin, with billing handled through the standard **Devin billing model**.
User management, team organization, SSO, RBAC, billing, and consumption are all inherited natively through the Devin dashboard. For most of your organizational needs, you should rely on the [Devin dashboard](https://app.devin.ai).
Devin authentication for Devin CLI is available to **Devin Enterprise** customers. Contact your account executive if you have questions about authentication, billing, or access.
## Getting Started
### Prerequisites
Before using Devin authentication, ensure that:
1. Your organization has a Devin enterprise account
2. Your administrator has configured Devin CLI access permissions (see [Configuring Access](#configuring-access) below)
3. You have been assigned a role with the **Use Devin CLI** permission
### Authenticating
To authenticate with your Devin enterprise account:
```bash theme={null}
devin auth login
```
Follow the prompts and be sure to select the **Log in with Devin for Enterprise** button to authenticate through your organization's identity provider.
### Credentials file location
After `devin auth login`, Devin CLI stores your API token in `credentials.toml`. By default, this token is persistent and does not expire. You can copy the credentials file between your own machines to reuse the same authentication, but treat it as sensitive: anyone with this file can authenticate as you. Do not share it or commit it to source control.
| Platform | Location |
| ------------- | ---------------------------------------------------------------------------------------------------------------------- |
| macOS / Linux | `$XDG_DATA_HOME/devin/credentials.toml` when `XDG_DATA_HOME` is set; otherwise `~/.local/share/devin/credentials.toml` |
| Windows | `%APPDATA%\devin\credentials.toml` (typically `C:\Users\\AppData\Roaming\devin\credentials.toml`) |
Run `devin auth logout` to remove stored credentials.
On MDM-managed devices, administrators can pin login to a specific enterprise host or account — skipping the login prompts entirely and rejecting out-of-policy accounts — with the [system configuration file](/cli/enterprise/system-config).
## Configuring Access
Devin CLI access is controlled through Devin's [custom roles and RBAC system](/enterprise/security-access/custom-roles). Administrators must create a custom role with the **Use Devin CLI** role permission and assign it to users who need access.
### Creating an Access Role
1. Navigate to **Enterprise Settings > Roles**
2. Click **Create a custom role**
3. Provide a descriptive name (e.g., "Devin CLI User")
4. Select the **Use Devin CLI** permission
5. Save the role
### Assigning the Role
* **Enterprise admins** or users with the **Manage Account Membership** permission can assign account-level roles via the "Enterprise members" page
* **Organization admins** or users with the **Manage Organization Membership** permission can assign organization-level roles via the "Organization members" page
You can automatically assign roles based on SSO IdP groups. See the [custom roles documentation](/enterprise/security-access/custom-roles) for details.
## Billing
Usage through Devin CLI is billed using the standard **Devin ACU (Agent Compute Unit) model**. All Devin CLI usage counts toward your organization's existing Devin enterprise allocation.
Enterprise admins can view their users' Devin CLI usage by accessing the **Cost** dashboard under the **Enterprise Analytics** tab in the Devin web app. This dashboard contains helpful visualizations of ACU consumption across all of the Cognition products, including Devin CLI.
For details about ACU billing and usage tracking, refer to your enterprise agreement or contact your account executive.
## Further Reading
For more information about Devin enterprise features, see the [Devin Enterprise documentation](/enterprise/getting-started/get-started):
* [Enterprise Setup](/enterprise/getting-started/get-started) — Initial configuration and onboarding
* [SSO Configuration](/enterprise/security-access/sso/guide) — Single sign-on setup
* [Custom Roles & RBAC](/enterprise/security-access/custom-roles) — Fine-grained access control
* [Enterprise Security](/enterprise/security-access/security/enterprise-security) — Security policies and controls
# System Configuration
Source: https://docs.devinenterprise.com/cli/enterprise/system-config
Pin Devin CLI login and proxy settings across managed devices with an MDM-distributed system.json policy
## Overview
`system.json` is an optional, machine-wide policy file that administrators distribute to managed devices (typically via MDM). It lives in a system directory that only an administrator can write, so — unlike the user config at `~/.config/devin/config.json` — the settings it carries cannot be changed or removed by the user.
Use it to:
* **Pin authentication** to your enterprise Devin host and/or account, so `devin auth login` skips the login-method menu and rejects any account outside your organization.
* **Force an outbound HTTP proxy** for the CLI and its updater. The enterprise setting takes precedence over the user config, and a user who also has a `proxy` section in their own config is asked to remove it before the CLI will start — see [proxy](#proxy) before rolling one out.
The file is optional and additive: when it is absent, Devin CLI behaves exactly as it does on an unmanaged device.
## File location
| Platform | Path |
| -------- | ------------------------------------------------ |
| macOS | `/Library/Application Support/Devin/system.json` |
| Linux | `/etc/devin/system.json` |
| Windows | `C:\ProgramData\Devin\system.json` |
These are the same machine-wide, administrator-writable directories Devin Desktop uses for system-level [rules](/desktop/cascade/memories) and [hooks](/desktop/cascade/hooks). Deploy the file with root/Administrator ownership and read-only permissions for regular users — the CLI reads it wherever it finds it, so a user-writable location defeats the purpose of the policy.
## Example
```json theme={null}
// /Library/Application Support/Devin/system.json
{
"enterprise_host": "acme.devinenterprise.com",
"account_id": "acct-acme",
"proxy": {
"mode": "manual",
"url": "http://proxy.corp.example.com:8080",
"no_proxy": "localhost,127.0.0.1,.internal.corp"
}
}
```
`system.json` is parsed as strict JSON — comments and trailing commas are **not** supported here, unlike the user `config.json`, which is JSON-with-comments. The comment above is shown only to indicate the file path.
## Options reference
| Option | Type | Default | Description |
| ----------------- | ------ | ------- | -------------------------------------------------------------------------------------------------------------------------------- |
| `enterprise_host` | string | unset | Devin enterprise host that users must authenticate against, e.g. `"acme.devinenterprise.com"`. Accepts a bare host or a full URL |
| `account_id` | string | unset | Devin account identifier the authenticated account must belong to |
| `proxy` | object | unset | Outbound HTTP proxy settings for the CLI and the updater (`mode`, `url`, `no_proxy`) |
Every field is independent — set only the ones you need. Unknown fields are ignored, so a policy written for a newer CLI still applies its known settings on an older one.
### enterprise\_host
When set, `devin auth login`:
1. Skips the login-method menu and the subdomain prompt, and drives authentication directly against the configured host.
2. Rejects any login whose resulting account belongs to a different host (or to no Devin enterprise at all) with a message pointing the user at the right host.
3. Refuses the legacy [Windsurf login](/cli/enterprise/windsurf-auth) path entirely.
The value is compared case-insensitively and ignores the scheme, so `acme.devinenterprise.com`, `ACME.DevinEnterprise.com`, and `https://acme.devinenterprise.com/` are equivalent. An explicit `http://` scheme is preserved when driving the login (useful only for testing); otherwise `https://` is assumed.
### account\_id
When set, the authenticated account must match this account identifier, even when the host already matches — use it to pin a specific tenant on a shared host. A login that resolves to another account, or to no account, is rejected after account verification.
Contact your Cognition account team if you are unsure which account identifier to use. Setting `account_id` also refuses the legacy Windsurf login path, since a Windsurf account cannot satisfy a Devin account policy.
### proxy
Configures how the CLI routes its own outbound HTTP/HTTPS traffic (API calls, updates, MCP servers). It uses the same shape as the `proxy` section of the [user config file](/cli/reference/configuration/config-file#proxy):
| Option | Type | Default | Description |
| ---------- | ----------- | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| `mode` | string | `"system"` | `"system"` (respect `HTTP_PROXY`/`HTTPS_PROXY`/`ALL_PROXY` and platform PAC), `"manual"` (route through `url`), or `"off"` (connect directly) |
| `url` | string/null | `null` | Proxy URL. Required when `mode` is `"manual"`. Supports `http://`, `https://`, and `socks5://` |
| `no_proxy` | string/null | `null` | Comma-separated bypass list, same syntax as the `NO_PROXY` environment variable. Applies in any mode |
The `devin-updater` binary reads the same setting, so background updates go through the same proxy as the CLI itself.
The enterprise proxy takes precedence over the user config, and it is an error for both files to configure one. If a user also has a `proxy` section in their `config.json`, the CLI exits at startup and asks them to remove it — rather than silently ignoring their setting. Tell your users to drop any local `proxy` section before you roll the policy out.
## Behavior and failure modes
A broken or partially understood policy file never disables the CLI — it degrades to no enforcement — while a valid policy is always enforced:
| Situation | Result |
| ------------------------------------------ | ---------------------------------------------------------------------------------------- |
| File absent | No enforcement; the CLI behaves as on an unmanaged device |
| File unreadable or malformed JSON | Treated as absent, with a warning in the logs |
| Unknown fields present | Ignored; the recognized fields still apply |
| Malformed `proxy` section | The proxy section is ignored; `enterprise_host` / `account_id` enforcement still applies |
| Malformed `enterprise_host` / `account_id` | Login enforcement is dropped; a valid `proxy` section still applies |
| Blank or whitespace-only value | Treated as unset |
Login enforcement runs during `devin auth login`. Credentials that are already stored on a device that signed in before the policy was deployed are not re-validated, so deploy `system.json` before rolling out the CLI — or have affected users run `devin auth logout` and sign in again.
The path to `system.json` cannot be redirected by an environment variable on stable, next, or enterprise builds, so users cannot point the CLI at a policy of their own.
## Verifying the policy
On a managed device:
```bash theme={null}
devin auth logout
devin auth login
```
With `enterprise_host` set, the login-method menu should not appear and the printed sign-in URL should be on your configured host. Then confirm the resulting session:
```bash theme={null}
devin auth status
```
A login with an account outside the policy fails with an explicit message naming the host or account your organization requires.
## Related settings
`system.json` covers device-level policy that must be in place before or during login. Most other organization-wide controls — models, MCP servers and registries, terminal permissions, sandbox enforcement, web search — are managed server-side in [Team Settings](/cli/enterprise/team-settings) and apply automatically once a user signs in.
## Further reading
* [Devin Auth](/cli/enterprise/devin-auth)
* [Team Settings](/cli/enterprise/team-settings)
* [Configuration File](/cli/reference/configuration/config-file)
* [Controls](/cli/enterprise/controls)
* [Devin Desktop Enterprise Policies](/desktop/enterprise-policies) — the equivalent MDM-distributed policy surface for the editor
# Team Settings
Source: https://docs.devinenterprise.com/cli/enterprise/team-settings
Configure team-wide settings to control your users' Devin CLI usage
## Overview
Team-wide settings allow enterprise admins to control Devin CLI usage across their organization.
* **Devin Enterprise admins** can manage these settings in the customer-facing Devin dashboard under **Settings → Enterprise → Windsurf** (`app.devin.ai/org/{orgName}/settings/windsurf`). This is self-service for admins with access to enterprise settings.
* **Windsurf Enterprise admins** can manage these settings in the Windsurf dashboard at [https://windsurf.com/team/cli-settings](https://windsurf.com/team/cli-settings).
Only the Devin CLI-specific settings on these pages apply to Devin CLI. General [Windsurf Team Settings](https://windsurf.com/team/settings) apply to Windsurf and do not necessarily apply to Devin CLI unless also listed on the Devin CLI settings page.
## Available Settings
### Models
Control which models your users can access through Devin CLI. You can:
* **Allowlist specific models** — Restrict users to a curated list of approved models
* **Allow all models** — Give users access to all available models
Click **Configure** to manage model access for each category.
#### Default model
You can also pin a **team-wide default model** that Devin CLI will use for new sessions. This is the same setting Windsurf uses for its default model, so configuring it once applies to both surfaces.
* If no team default is set, Devin CLI uses its built-in default model.
* If the pinned default is not present in the **allowed models** list above, Devin CLI falls back to the built-in default — the allowlist always takes precedence.
* Individual users can still switch models during a session; this setting only controls the starting model for new sessions.
Enterprise admins can configure the default model from the [Windsurf Team Settings](https://windsurf.com/team/settings) page, the [Devin CLI Settings](https://windsurf.com/team/cli-settings) page, or the customer-facing Devin Enterprise settings page at `app.devin.ai/org/{orgName}/settings/windsurf`.
### Enable Web Search
Allow the Devin CLI agent to perform web searches on the open Internet. This does not affect the agent's ability to read specific URLs, which is performed locally on the user's machine. This tool is **disabled by default** for enterprise teams.
### MCP Servers
Control whether your users can use MCP (Model Context Protocol) tools.
* **Toggle on/off** — Enable or disable MCP server usage entirely
* **Allowlisted MCP Servers** — Specify which MCP servers users are allowed to connect to. If no servers are added, all servers are allowlisted by default. Click **Add Server** to restrict access to specific servers.
The recommended way to manage approved servers is through an [MCP registry](#mcp-registry) rather than the explicit allowlist.
### MCP Registry
You can use the [official MCP registry](https://modelcontextprotocol.io/registry/about), a downstream registry built on it, or your own registry.
Configure registries in team settings:
* **MCP registry URLs** — Add one or more registry URLs. With multiple registries, a server is allowed if it appears in any of them (the union of all registries).
* **MCP registry enforcement** (toggle) — Choose whether to strictly enforce your registries. When on, users can only connect to servers from your registries; when off, they can also connect to other servers, including custom ones.
### Terminal Permissions
Configure team-enforced permission rules for Devin CLI usage. These rules have the **highest precedence** and cannot be overridden by individual users' local or project configurations.
Click **Configure** to open the permissions editor. The configuration requires a JSON object with three fields:
```json theme={null}
{
"deny": [
"exec"
],
"ask": [],
"allow": [
"Read(~/my-repository/**)"
]
}
```
* **`deny`** — Actions that are blocked entirely (takes highest priority)
* **`ask`** — Actions that always prompt the user for approval
* **`allow`** — Actions that are automatically approved without prompting
Permissions can be **scope-based** or **tool-based**:
| Type | Format | Example |
| ----------------- | -------------- | ------------------------------- |
| File read | `Read(/path)` | `Read(~/sensitive/**)` |
| File write | `Write(/path)` | `Write(.env*)` |
| Command execution | `Exec(cmd)` | `Exec(rm)`, `Exec(sudo)` |
| HTTP fetch | `Fetch(url)` | `Fetch(https://internal.api/*)` |
| Tool-based | Tool name | `read`, `edit`, `exec` |
Use team-enforced deny rules to prevent actions across your entire organization, such as blocking access to sensitive directories or dangerous commands like `rm -rf` or `sudo`.
For detailed information on permission syntax, glob patterns, and configuration examples, see the [Permissions documentation](/cli/reference/permissions).
### Sandbox Enforcement
Control sandbox behavior for your organization: **Enforcement mode** (whether `--sandbox` is **Optional** or **Required** for all CLI sessions), **Domain allowlist** and **Domain denylist** (organization-wide network filtering), and **Excluded allow** / **Excluded ask** / **Excluded deny** (rules for commands that may — or must never — run outside the sandbox). See the [Sandbox documentation](/cli/sandbox) for how the sandbox works, how these settings interact with user-level configuration, and examples.
Enforcement mode is re-read at the start of every prompt, not just at startup. If you switch it to **Required** while a user is in a session that was started without the sandbox, that session refuses further prompts and tells the user to restart — the sandbox is then enabled automatically at startup. Sessions already running with the sandbox are unaffected.
### Attribution Filtering
When attribution filtering is enabled for your team, code generated by Devin CLI is checked against a corpus of publicly available code: file edits that match public code are automatically reverted, and matching code blocks in chat responses are flagged while the agent is instructed to rewrite them. The setting applies to all Devin CLI users on the team.
This setting is available on **Enterprise plans** and has no self-serve toggle; to enable it, reach out to [support@cognition.ai](mailto:support@cognition.ai) or your Cognition account team. Attribution filtering is also available for Devin cloud sessions — see [Attribution Filtering](/enterprise/features/attribution-filtering).
### Show "Install Devin CLI" in the Devin Desktop Command Palette
Devin CLI is bundled with Devin Desktop but requires explicit activation by an admin. Toggle this setting **on** to allow your users to install Devin CLI directly from the Devin Desktop Command Palette.
Once enabled, users can open the Command Palette (Cmd+Shift+P on macOS or Ctrl+Shift+P on Windows/Linux) and run **Install Devin CLI** to add the `devin` binary to their PATH.
This setting is available on **Legacy Windsurf Enterprise** and **Devin Enterprise** plans and is **off by default**.
## Further Reading
To understand how to configure Devin CLI further, see the [Configuration documentation](/cli/reference/configuration/config-file).
Settings on this page are applied server-side once a user signs in. To enforce device-level policy that applies before or during login — pinning the enterprise host or account, or forcing an outbound proxy — see the [system configuration file](/cli/enterprise/system-config).
# Legacy Windsurf Auth
Source: https://docs.devinenterprise.com/cli/enterprise/windsurf-auth
Authenticate to Devin CLI using your existing legacy Windsurf enterprise account
## Overview
Enterprise users can authenticate to Devin CLI using their existing legacy Windsurf enterprise accounts. This provides a seamless experience for organizations already using Windsurf, with billing handled through the standard **Windsurf legacy credit model**.
User management, team organization, SSO, RBAC, billing, and consumption are all inherited natively through the Windsurf dashboard. For most of your organizational needs, you should rely on the [Windsurf dashboard](https://windsurf.com).
Legacy Windsurf authentication for Devin CLI is available to **legacy Windsurf Enterprise** customers. Contact your account executive if you have questions about authentication, billing, or access.
## Getting Started
### Prerequisites
Before using legacy Windsurf authentication, ensure that:
1. Your organization has a legacy Windsurf enterprise account
2. You have an active legacy Windsurf user account that can use the agentic tools
No additional permissions are required to access Devin CLI. If your legacy Windsurf enterprise users can use Windsurf, they can use Devin CLI.
### Installation via Devin Desktop
Devin CLI is bundled with Devin Desktop. An admin must first enable the option in [Devin CLI Team Settings](https://windsurf.com/team/cli-settings) — see [Team Settings](/cli/enterprise/team-settings#show-install-devin-cli-in-the-devin-desktop-command-palette) for details.
Once enabled, open the Command Palette (Cmd+Shift+P / Ctrl+Shift+P) and run **Install Devin CLI**.
Alternatively, you can install using the standalone installer — see the [Quickstart](/cli/) for instructions.
### Authenticating
To authenticate with your legacy Windsurf enterprise account:
```bash theme={null}
devin auth login
```
Follow the prompts and be sure to select the **Log in with Windsurf for Enterprise** option to authenticate through your organization's identity provider.
### Credentials file location
After `devin auth login`, Devin CLI stores your API token in `credentials.toml`. By default, this token is persistent and does not expire. You can copy the credentials file between your own machines to reuse the same authentication, but treat it as sensitive: anyone with this file can authenticate as you. Do not share it or commit it to source control.
| Platform | Location |
| ------------- | ---------------------------------------------------------------------------------------------------------------------- |
| macOS / Linux | `$XDG_DATA_HOME/devin/credentials.toml` when `XDG_DATA_HOME` is set; otherwise `~/.local/share/devin/credentials.toml` |
| Windows | `%APPDATA%\devin\credentials.toml` (typically `C:\Users\\AppData\Roaming\devin\credentials.toml`) |
Run `devin auth logout` to remove stored credentials.
## Billing & Analytics
Usage through Devin CLI is billed using the standard **Windsurf legacy credit model**. All Devin CLI usage counts toward your organization's existing legacy Windsurf enterprise allocation.
The analytics and billing systems are shared between Windsurf and Devin CLI. Use the [Team Members dashboard](https://windsurf.com/team/members) to manage team organization or view consumption metrics across both products.
On prompt-based plans, each subagent consumes additional credits, just like a user message does. The number of credits depends on the model the subagent uses, so tasks that spawn multiple subagents (or [nest](/cli/subagents#nesting-depth) them) consume more credits.
Enterprise admins can also access usage analytics programmatically through the [Analytics API](/desktop/accounts/api-reference/api-introduction) to monitor consumption across their organization.
For details about credit billing and usage tracking, refer to your enterprise agreement or contact your account executive.
## Further Reading
For more information about legacy Windsurf enterprise features, see the [Devin Desktop documentation](/desktop/getting-started):
* [Guide for Admins](/desktop/guide-for-admins) — Administration and team management
* [SSO & SCIM](/desktop/accounts/sso-scim) — Single sign-on and user provisioning
* [API Reference](/desktop/accounts/api-reference/api-introduction) — Access analytics and usage data
# Essential Commands
Source: https://docs.devinenterprise.com/cli/essential-commands
If you remember nothing else...
## Starting Devin CLI
By default, sessions happen in a REPL, a graphical terminal interface where you can chat back and forth and observe Devin's actions.
```bash theme={null}
devin # Start interactive REPL (no prompt)
devin -- your prompt here # Start REPL with initial prompt
devin -p "prompt" # Single-turn, no REPL: print response to stdout and exit
devin -p -- prompt words here # Same, using -- separator (still works)
```
Use `--` before your prompt so it is interpreted as a prompt and not a subcommand.
Single-turn mode (`-p`) is great for scripts and automations.
Type `@` in the prompt input to open autocomplete for local files/directories. Selecting one adds it as context for your message.
You can paste images from your clipboard with **Ctrl+V**. Attached images appear in the input area and can be managed with **Left/Right** to navigate and **Backspace** to remove.
## Running shell commands
Devin may run shell commands while working. If a command is still running after the default wait period, Devin moves it to the background and shows how long it waited along with the background shell ID. Devin can then continue working and check the command's output later.
***
## Modes
Devin CLI has 5 built-in permission modes: **Normal**, **Accept Edits**, **Smart**, **Bypass**, and **Autonomous**, and 3 agent-modes: **Normal**, **Plan**, and **Ask**. For plan and ask, use `/plan` and `/ask`.
Auto-approves read-only tools within the current directory, and asks for permission for write/execute operations.
```bash theme={null}
/normal
# or
/mode normal
```
This is the default mode.
Auto-approves file edits within the workspace while still prompting for shell commands and other actions. We expect people to spend most of their time here.
```bash theme={null}
/accept-edits
# or
/mode accept-edits
```
Auto-approves file edits within the workspace like Accept Edits, and for every other action — shell commands, web fetches, MCP tools — a fast model decides whether it is safe to run without asking. Anything it does not judge clearly safe still prompts, and high-risk categories (package installs, mutating `git`, `rm`, `sudo`, destructive cloud CLI operations, sensitive files) always prompt.
```bash theme={null}
/smart
# or
/mode smart
```
You can also start in smart mode:
```bash theme={null}
devin --permission-mode smart
```
Smart mode is rolling out gradually, so it may not be available on your account yet. See [Smart Mode](/cli/reference/permissions#smart-mode) for the full behavior.
Auto-approves **all** tool calls, including writes and shell commands.
```bash theme={null}
/bypass
# or
/mode bypass
```
You can also start in bypass mode:
```bash theme={null}
devin --permission-mode bypass
```
Aliases: `/yolo`, `/dangerous`
Bypass mode **never** overrides organization-level permissions configured by your admin via [Team Settings](/cli/enterprise/team-settings). Admin-enforced deny and ask rules **always** take priority.
Roughly equivalent to Accept Edits in the current workspace, with the additional ability to run any shell command within an [OS-level sandbox](/cli/reference/configuration/config-file#sandbox) (to contain what those commands can actually touch).
```bash theme={null}
devin --sandbox --permission-mode autonomous
```
Autonomous is the **only** permission mode available when running with `--sandbox`, and it is selected automatically — Normal, Accept Edits, Smart, and Bypass are hidden in sandbox sessions.
In Autonomous mode...
* You are prompted for **capabilities rather than commands**.
* Commands respect `Write` scopes and `Read(...)` deny rules via a filesystem sandbox.
* Commands prompt you when they try to connect to network resources.
* Read-only operations within the current directory auto-approve.
Autonomous relies on the sandbox for safety. Without `--sandbox`, the mode is unavailable — use Bypass if you want unattended execution without OS-level isolation. See [Bypass vs Autonomous](#bypass-vs-autonomous) below for a direct comparison.
### Bypass vs Autonomous
Bypass and Autonomous both reduce approval prompts, but they rely on different safety mechanisms:
| | Bypass | Autonomous |
| ------------------------------------------------------------- | --------------------------- | ----------------------------------------------------------------------------------------------------- |
| Requires `--sandbox` | No | Yes (only available in sandbox sessions) |
| Shell commands | Auto-approved, unrestricted | Auto-approved, contained by the sandbox |
| File writes via `edit`/`write` tools | Auto-approved anywhere | Still prompt (granting a scope expands the sandbox) |
| Network access | Unrestricted | Filtered by the sandbox's [domain allow/deny lists](/cli/reference/configuration/config-file#sandbox) |
| Respects admin [Team Settings](/cli/enterprise/team-settings) | Yes | Yes |
Pick Bypass when you trust the agent with your whole machine. Pick `--sandbox` (which selects Autonomous) when you want unattended execution with OS-enforced limits on what files and domains the agent can touch. If you like the feel of bypass but want the agent to have its own computer, try cloud Devin!
## Session History
Your conversation history is saved so you can resume a session later.
```bash theme={null}
devin -c # Continue the most recent session in the current directory
devin --continue
devin -r # Pick from recent sessions
devin --resume
devin -r brisk-otter # Resume a specific session by ID
```
***
## Slash Commands
You can use these commands while in an active session.
### Navigation & Control
| Command | Description |
| ------------------ | ---------------------------------------- |
| `/help` | See all available commands |
| `/exit` or `/quit` | Exit the application |
| `/clear` or `/new` | Clear conversation history (start fresh) |
You can also type `exit` or `quit` as plain text (without the `/` prefix) to exit.
### Mode Switching
| Command | Description |
| ----------------- | --------------------------------------------------------------------------------------------------- |
| `/mode` | Show current mode |
| `/mode ` | Switch mode (`normal`, `accept-edits`, `smart`, `plan`, `bypass`; `autonomous` in sandbox sessions) |
| `/normal` | Switch to Normal mode (default) |
| `/accept-edits` | Switch to Accept Edits mode |
| `/smart` | Switch to Smart mode |
| `/plan` | Switch to Plan mode |
| `/ask ` | Ask a question without making code changes (oneshot) |
| `/bypass` | Switch to Bypass mode (aliases: `/yolo`, `/dangerous`) |
### Model Switching
| Command | Description |
| -------- | ------------------- |
| `/model` | Show model selector |
### Session Management
| Command | Description |
| ------------------ | ------------------------------------------------------------------- |
| `/resume` | Open the interactive session picker |
| `/resume ` | Resume session by ID |
| `/ls` | List recent sessions in current directory (alias: `/list-sessions`) |
| `/ls --all` | List all sessions across all directories |
| `/continue` | Resume most recent session |
| `/continue ` | Resume session by ID |
| `/rm-session ` | Irreversibly delete a session by ID |
### Workspace
| Command | Description |
| ---------------------- | ------------------------------------------------- |
| `/workspace` | List workspace directories (alias: `/workspaces`) |
| `/add-dir ` | Add additional workspace directory |
| `/undo-add-dir ` | Remove a workspace directory |
### Automation
| Command | Description |
| ---------------- | ------------------------------------------------------------------------------------ |
| `/loop ` | Run a prompt then auto-review the diff in a loop (requires clean git state to start) |
### Extensibility
| Command | Description |
| -------- | ------------------------------------------------------------------- |
| `/hooks` | List all loaded hooks with their IDs, event types, and source paths |
### Account & System
| Command | Description |
| ---------- | ---------------------------------------- |
| `/login` | Authenticate with Devin |
| `/logout` | Clear stored credentials and exit |
| `/update` | Check for and install updates |
| `/upgrade` | Upgrade your subscription plan |
| `/bug` | Report a bug to the Devin CLI developers |
| `/compact` | Force conversation compaction |
If you installed Devin for Terminal via Homebrew, `/update` will direct you to use `brew upgrade devin` instead of performing a self-update.
***
## Keyboard Shortcuts
Here are the most important keyboard shortcuts. See [Keyboard Shortcuts](/cli/reference/keyboard-shortcuts) for more shortcuts.
| Shortcut | Description |
| -------------------------- | --------------------------------------------------------------------- |
| `Shift+Tab` | Cycle between modes (Normal, Accept Edits, Smart, Bypass, Autonomous) |
| `Ctrl+C` | Clear input text, or cancel the running agent |
| `Esc` | Cancel the running agent |
| `Shift+Enter` | Insert a newline (multi-line input) |
| `Ctrl+V` or `Shift+Insert` | Paste from clipboard |
| `Ctrl+G` | Open external editor |
| `Ctrl+O` | Open full-screen thinking trace viewer |
| `@` | Mention files to add as context |
# Configuration
Source: https://docs.devinenterprise.com/cli/extensibility/configuration
How to configure Devin CLI behavior with config files
Devin CLI is configured through JSON files (with comment support) at the user and project level. These config files control the agent's model, permissions, MCP servers, and more.
***
## Config File Locations
**Path:** `~/.config/devin/config.json`
Your personal defaults that apply across all projects. This is where you set your preferred model, theme, and global permissions.
You can also place an `AGENTS.md` file in this directory (`~/.config/devin/AGENTS.md`) to define [global rules](/cli/extensibility/rules#global-rules) that apply to every project.
On Windows, this path is `%APPDATA%\devin\config.json` (typically `C:\Users\\AppData\Roaming\devin\config.json`).
```json theme={null}
{
"agent": { "model": "claude-sonnet-4.5" },
"permissions": {
"allow": ["Read(**)", "Exec(git)"]
}
}
```
**Path:** `.devin/config.json` (at your project root)
Shared team configuration committed to version control. Use this for permission policies and import settings. Project-specific MCP servers go in `.devin/mcp_config.json` alongside it.
```json theme={null}
// .devin/config.json
{
"permissions": {
"allow": ["Exec(npm run)", "Read(src/**)"],
"deny": ["Exec(sudo)"]
}
}
```
```json theme={null}
// .devin/mcp_config.json
{
"mcpServers": {
"github": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-github"]
}
}
}
```
**Path:** `.devin/config.local.json`
Personal overrides for this project that aren't committed to git (automatically gitignored). Use this for secrets, API keys, and personal preference overrides. Personal MCP servers go in `.devin/mcp_config.local.json`.
```json theme={null}
// .devin/mcp_config.local.json
{
"mcpServers": {
"github": {
"env": { "GITHUB_TOKEN": "ghp_your_token" }
}
}
}
```
***
## What You Can Configure
Choose which AI model powers the agent — from Claude Opus to GPT 5.2 to Gemini 3.
Pre-approve safe actions, block dangerous ones, and control what the agent can do without asking.
Connect external tool servers for GitHub, Linear, databases, and any custom APIs.
Import rules, skills, and configuration from Cursor, Windsurf, and Claude Code.
***
## Quick Start
The fastest way to get started is to create a `.devin/config.json` in your project root:
```json theme={null}
{
"permissions": {
"allow": [
"Read(**)",
"Exec(git)",
"Exec(npm run)"
]
}
}
```
This pre-approves file reads and common commands so the agent doesn't prompt you for every action.
You can also configure Devin CLI interactively: when the agent asks for permission, choose to save the decision to your project or user config for next time.
***
## Project vs User Settings
Not all settings are available at every level. Project configs (`.devin/config.json` and `.devin/config.local.json`) support:
* **`permissions`** — allow, deny, and ask rules
* **`mcpServers`** — MCP server definitions (in the dedicated `.devin/mcp_config.json` / `.devin/mcp_config.local.json` files since v3000.3, the Local 3.6 release; in `config.json` in older versions)
* **`read_config_from`** — import settings from Cursor, Windsurf, and Claude
* **`hooks`** — lifecycle hooks ([see Hooks](/cli/extensibility/hooks/overview))
All other settings — including `agent` (model), `theme_mode`, `unicode_mode`, `show_path`, `sandbox`, and other display/behavior options — are **user-config only** and can only be set in the user config (`~/.config/devin/config.json`; `%APPDATA%\devin\config.json` on Windows).
***
## Configuration Precedence
For settings that support multiple levels, higher-priority sources win:
| Priority | Source | Shared? |
| ----------- | ------------------------------------------------------------------------------ | ---------------- |
| 1 (highest) | Organization / Team settings | Yes (enterprise) |
| 2 | Session grants (interactive approvals) | No (in-memory) |
| 3 | Project local (`.devin/config.local.json`) | No (gitignored) |
| 4 | Project (`.devin/config.json`) | Yes (committed) |
| 5 (lowest) | User (`~/.config/devin/config.json`; `%APPDATA%\devin\config.json` on Windows) | No (personal) |
Permissions are merged across levels, while MCP servers are merged by name (higher-priority source wins for same-named servers).
Organization-level (enterprise) settings can **never** be overridden by project or user config. See [Configuration Precedence](/cli/reference/configuration/global-vs-local) for full details on how merging works.
***
## Limitations
When run standalone, Devin CLI only respects `.gitignore` by default — it does not enforce `.devinignore`, `.codeiumignore`, or `.windsurfignore` files. When Devin CLI runs inside Devin Desktop, all four ignore files are enforced.
***
## Learn More
Complete list of every configuration option and its format.
How global, project, and local settings interact and merge.
# Lifecycle Hooks
Source: https://docs.devinenterprise.com/cli/extensibility/hooks/lifecycle-hooks
Understanding hook events and the data available at each stage
Each hook event fires at a specific point in the agent's lifecycle. Use the **matcher** field (a regex matched against the hook event's `tool_name`) to filter which tool invocations trigger your hook.
In addition to the event-specific fields below, every stdin payload includes a stable per-session `session_id` and a per-turn `prompt_id` (rotated on every user prompt; absent for events that fire before the first user prompt, e.g. `SessionStart`) — see [Command Hooks](/cli/extensibility/hooks/overview#command-hooks).
***
## PreToolUse
Fires **before** a tool executes. Use this to block, modify, or add context to tool calls.
**Stdin data:**
| Field | Description | Example |
| ------------ | ----------------------------- | ----------------------------------------------- |
| `tool_name` | Name of the tool being called | `exec`, `edit`, `mcp__github__create_issue` |
| `tool_input` | Arguments passed to the tool | `{ "command": "rm -rf /", "shell_id": "main" }` |
**Example — Block destructive commands:**
```json theme={null}
{
"PreToolUse": [
{
"matcher": "exec",
"hooks": [
{
"type": "command",
"command": "python3 -c \"import sys, json; data = json.load(sys.stdin); cmd = data.get('tool_input', {}).get('command', ''); sys.exit(2 if 'rm -rf' in cmd else 0)\""
}
]
}
]
}
```
**Example — Require confirmation for writes outside src/:**
Use a script that inspects the tool input and returns a decision:
```json theme={null}
{
"PreToolUse": [
{
"matcher": "edit",
"hooks": [
{
"type": "command",
"command": "./scripts/check-edit-path.sh",
"timeout": 5
}
]
}
]
}
```
**Example — Rewrite commands before execution:**
A hook can transparently rewrite the tool's input by printing `hookSpecificOutput.updatedInput` to stdout (see [Output format](/cli/extensibility/hooks/overview#output-format)). For example, a hook script that routes shell commands through a wrapper:
```json theme={null}
{
"hookSpecificOutput": {
"hookEventName": "PreToolUse",
"updatedInput": {
"command": "rtk git status"
}
}
}
```
The rewritten arguments are merged into the tool call before it runs — the agent executes the updated command instead of the original.
***
## PostToolUse
Fires **after** a tool finishes executing. Use this for logging, validation, or triggering follow-up actions.
**Stdin data:**
| Field | Description |
| --------------- | -------------------------------------------------------------------------------- |
| `tool_name` | Name of the tool that ran |
| `tool_input` | Arguments that were passed |
| `tool_response` | Object with `success` (boolean), `output` (string), and `error` (string or null) |
**Example — Log all shell commands:**
```json theme={null}
{
"PostToolUse": [
{
"matcher": "exec",
"hooks": [
{
"type": "command",
"command": "sh -c 'cat >> ~/.devin-command-log'"
}
]
}
]
}
```
***
## PermissionRequest
Fires when the agent needs a permission decision. Use this to implement custom approval logic.
**Stdin data:**
| Field | Description |
| ------------ | --------------------------- |
| `tool_name` | Tool requesting permission |
| `tool_input` | Arguments for the tool call |
**Example — Auto-approve git commands:**
```json theme={null}
{
"PermissionRequest": [
{
"matcher": "exec",
"hooks": [
{
"type": "command",
"command": "python3 -c \"import sys, json; data = json.load(sys.stdin); cmd = data.get('tool_input', {}).get('command', ''); print(json.dumps({'decision': 'approve'})) if cmd.startswith('git ') else sys.exit(0)\""
}
]
}
]
}
```
***
## UserPromptSubmit
Fires when the user submits a message. Use this to add context or trigger workflows.
**Stdin data:**
| Field | Description |
| -------- | ----------------------- |
| `prompt` | The user's message text |
**Example — Inject context on every prompt:**
```json theme={null}
{
"UserPromptSubmit": [
{
"matcher": "",
"hooks": [
{
"type": "command",
"command": "echo '{\"hookSpecificOutput\": {\"hookEventName\": \"UserPromptSubmit\", \"additionalContext\": \"Deploys require an approved change ticket.\"}}'"
}
]
}
]
}
```
The command prints `additionalContext` inside a `hookSpecificOutput` object on stdout, tagged with the event name. That text is injected into the agent's context:
```json theme={null}
{
"hookSpecificOutput": {
"hookEventName": "UserPromptSubmit",
"additionalContext": "Deploys require an approved change ticket."
}
}
```
***
## Stop
Fires when the agent decides to stop (finish its turn). Use this to add follow-up instructions or prevent premature stopping.
**Stdin data:**
| Field | Description |
| ------------------ | ------------------------------------- |
| `stop_hook_active` | Whether a stop hook is already active |
**Example — Remind agent to run tests:**
```json theme={null}
{
"Stop": [
{
"matcher": "",
"hooks": [
{
"type": "command",
"command": "echo '{\"decision\": \"block\", \"reason\": \"Please run the test suite before stopping.\"}'"
}
]
}
]
}
```
Be careful with stop hooks that block — they can cause the agent to loop if the condition isn't eventually satisfied.
***
## PostCompaction
Fires **after** context compaction completes successfully. Use this for logging, triggering follow-up actions, or re-injecting context that may have been lost during compaction.
**Stdin data:**
| Field | Description |
| --------- | -------------------------------------------------------------------------------- |
| `summary` | Summary text produced by the compactor (may be null if no summary was generated) |
**Example — Log compaction events:**
```json theme={null}
{
"PostCompaction": [
{
"matcher": "",
"hooks": [
{
"type": "command",
"command": "sh -c 'cat >> ~/.devin-compaction-log'"
}
]
}
]
}
```
***
## SessionStart
Fires when a new session begins. Use this for initialization, logging, or environment setup.
**Stdin data:**
| Field | Description |
| -------- | --------------------------- |
| `source` | How the session was started |
**Example — Run setup script:**
```json theme={null}
{
"SessionStart": [
{
"matcher": "",
"hooks": [
{
"type": "command",
"command": "./scripts/dev-setup.sh",
"timeout": 10
}
]
}
]
}
```
A SessionStart command can also inject context by printing `additionalContext` inside a `hookSpecificOutput` object on stdout:
```json theme={null}
{
"hookSpecificOutput": {
"hookEventName": "SessionStart",
"additionalContext": "Session started. Project uses ESM imports only."
}
}
```
***
## SessionEnd
Fires when a session ends. Use this for cleanup or final logging.
**Stdin data:**
| Field | Description |
| -------- | --------------------- |
| `reason` | Why the session ended |
***
## Matching Multiple Events
A single hooks file can define hooks for multiple events:
```json theme={null}
{
"PreToolUse": [
{
"matcher": "",
"hooks": [
{ "type": "command", "command": "./scripts/audit.sh" }
]
}
],
"PostToolUse": [
{
"matcher": "",
"hooks": [
{ "type": "command", "command": "./scripts/audit.sh" }
]
}
]
}
```
## Using the Matcher
The `matcher` field is a **regex** matched against the hook event's `tool_name`. It is available for tool-related events: `PreToolUse`, `PostToolUse`, and `PermissionRequest`.
For non-tool events (`UserPromptSubmit`, `Stop`, `PostCompaction`, `SessionStart`, and `SessionEnd`), there is no `tool_name`; use `""` or omit the matcher to run the hook for every event of that type.
The matcher is not a permission glob. Patterns like `mcp__github__*` are useful in permissions, but hook matchers are regexes. Use `mcp__github__.*` in a hook matcher.
| Matcher | Matches |
| ------------------------------- | ---------------------------------------------------- |
| `""` (empty) or omitted | All tool names for tool events |
| `"exec"` | Tool names containing `exec` |
| `"^exec$"` | Only the `exec` tool |
| `"^(exec\|edit)$"` | Only `exec` or `edit` |
| `"^mcp__.*"` | All MCP tools |
| `"^mcp__github__.*"` | All tools from the `github` MCP server |
| `"^mcp__github__create_issue$"` | The `create_issue` tool from the `github` MCP server |
### Tool names you can match
Hook matchers run against the same externally-visible tool names that hook scripts receive in stdin as `tool_name`. The exact tool names available can vary by CLI mode, model, and enabled integrations.
The core tool names, by category:
| Category | Tool names |
| ------------------ | -------------------------------------------------------------------------- |
| File operations | `read`, `write`, `edit`, `apply_patch`, `notebook_read`, `notebook_edit` |
| Search | `grep`, `glob` |
| Shell | `exec`, `get_output`, `write_to_process`, `kill_shell` |
| Web | `webfetch` |
| Planning and tasks | `todo_write`, `exit_plan_mode` |
| Skills | `skill` |
| Subagents | `run_subagent`, `read_subagent` |
| Permissions | `request_scope` |
| MCP management | `mcp_list_servers`, `mcp_list_tools`, `mcp_call_tool`, `mcp_read_resource` |
MCP server tools appear as `mcp____`. For example, a `github` MCP server tool named `create_issue` appears as `mcp__github__create_issue`.
For other tools, match the exact `tool_name` shown in hook stdin. To confirm the complete set available in your current session, add a temporary `PostToolUse` hook with `matcher: ""` and log the stdin payload.
# Hooks
Source: https://docs.devinenterprise.com/cli/extensibility/hooks/overview
Run custom logic when specific events occur during a session
Hooks let you run custom logic in response to events in the agent's lifecycle. You can use hooks to enforce policies, add context, log actions, modify permissions, or integrate with external systems.
Hooks are configured with a JSON format. Place them in your project's `.devin/` directory (or a user-level config) and Devin CLI runs them at the matching lifecycle events. Existing hooks in `.claude/` directories are also picked up automatically — see [Where Hooks Live](#where-hooks-live).
***
## What Can Hooks Do?
Block dangerous commands, require confirmation for specific actions, or restrict file access.
Inject additional instructions or information when specific tools are called.
Execute scripts, send notifications, or log events when things happen.
Dynamically grant or restrict permissions based on the situation.
***
## Quick Example
Create `.devin/hooks.v1.json` in your project:
```json theme={null}
{
"PreToolUse": [
{
"matcher": "exec",
"hooks": [
{
"type": "command",
"command": "./scripts/check-command.sh"
}
]
}
]
}
```
This runs `./scripts/check-command.sh` before every shell command execution. The script receives event data on stdin and can block the action by returning a non-zero exit code.
***
## Hook Events
Hooks can respond to these lifecycle events:
| Event | When it fires |
| ------------------- | ----------------------------------------------- |
| `PreToolUse` | Before a tool executes |
| `PostToolUse` | After a tool finishes |
| `PermissionRequest` | When a permission decision is needed |
| `UserPromptSubmit` | When the user submits a message |
| `Stop` | When the agent wants to stop |
| `PostCompaction` | After context compaction completes successfully |
| `SessionStart` | When a session begins |
| `SessionEnd` | When a session ends |
See [Lifecycle Hooks](/cli/extensibility/hooks/lifecycle-hooks) for details on each event and its available data.
***
## Hook Format
Each hook has a **type** (`command` or `prompt`), an optional **matcher** (regex on the hook event's `tool_name`), and configuration:
```json theme={null}
{
"PreToolUse": [
{
"matcher": "exec",
"hooks": [
{
"type": "command",
"command": "./scripts/validate.sh",
"timeout": 10
}
]
}
]
}
```
| Field | Description |
| --------- | -------------------------------------------------------------------------------------------------------------- |
| `matcher` | Regex matched against the hook event's `tool_name`. Empty string or an omitted matcher matches all tool names. |
| `type` | `"command"` to run a shell command, or `"prompt"` to evaluate an LLM prompt. |
| `command` | Shell command to run (for `command` type). |
| `prompt` | LLM prompt to evaluate (for `prompt` type). |
| `timeout` | Timeout in seconds (optional). |
### Command Hooks
Command hooks run a shell command. Event data is passed as JSON on **stdin**, and the command can return JSON on **stdout** to control the outcome (see [Output format](#output-format) below).
**Input** (stdin):
```json theme={null}
{
"hook_event_name": "PreToolUse",
"tool_name": "exec",
"tool_input": {
"command": "rm -rf /"
},
"session_id": "3f8d1c2a-...",
"prompt_id": "b71e9d40-..."
}
```
Every event payload also carries two correlation ids alongside the event fields:
| Field | Description |
| ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `session_id` | Stable id for the agent session. Use it to correlate hook invocations across a whole session. |
| `prompt_id` | Per-turn id, rotated on every user prompt. All hooks fired during the same turn share one `prompt_id`. Absent for events that fire before the first user prompt (e.g. `SessionStart`). |
The `DEVIN_PROJECT_DIR` environment variable is automatically set to the project root directory.
See [Using the Matcher](/cli/extensibility/hooks/lifecycle-hooks#using-the-matcher) for the built-in tool names and MCP tool name format you can match.
### Output format
A command hook can print a JSON object to **stdout** to control the outcome.
To approve or block an action, return a top-level `decision` (with an optional `reason`):
```json theme={null}
{
"decision": "block",
"reason": "Destructive command blocked by policy"
}
```
To inject text into the agent's context, return `additionalContext` inside a `hookSpecificOutput` object tagged with the event name:
```json theme={null}
{
"hookSpecificOutput": {
"hookEventName": "UserPromptSubmit",
"additionalContext": "Remember: deploys require an approved change ticket."
}
}
```
To transparently rewrite a tool's input before it executes, return `updatedInput` inside a `PreToolUse` `hookSpecificOutput`. Fields in `updatedInput` are merged into the tool's arguments, so you can update a subset (e.g. just `command`):
```json theme={null}
{
"hookSpecificOutput": {
"hookEventName": "PreToolUse",
"updatedInput": {
"command": "rtk git status"
}
}
}
```
| Output field | Description |
| -------------------------------------- | -------------------------------------------------------------------------------------------------- |
| `decision` | `"approve"` to allow the action, or `"block"` to deny it |
| `reason` | Explanation shown to the agent |
| `hookSpecificOutput.hookEventName` | Event the output applies to (e.g. `UserPromptSubmit`, `SessionStart`, `PreToolUse`, `PostToolUse`) |
| `hookSpecificOutput.additionalContext` | Text injected into the agent's context (for `UserPromptSubmit`, `SessionStart`, `PostToolUse`) |
| `hookSpecificOutput.updatedInput` | Object merged into the tool's arguments before execution (for `PreToolUse`) |
### Exit Codes
| Code | Meaning |
| ----- | --------------------------------- |
| 0 | Success — hook continues normally |
| 2 | Block — action is denied |
| Other | Error — logged but doesn't block |
***
## Where Hooks Live
Devin CLI reads hooks from the following locations. All use the same JSON format. Project-level hook files are discovered in the working directory and its ancestor directories up to the repository root, matching how skills and rules are loaded.
### Project-Level
| Location | Description |
| ----------------------------- | ------------------------------------------ |
| `.devin/hooks.v1.json` | Standalone hooks file (recommended) |
| `.devin/config.json` | `"hooks"` key in the config file |
| `.devin/config.local.json` | `"hooks"` key (local override, gitignored) |
| `.claude/settings.json` | `"hooks"` key (Claude Code format) |
| `.claude/settings.local.json` | `"hooks"` key (Claude Code format) |
### User-Level (Global)
| Location | Description |
| ------------------------------------------------------------------------ | ---------------------------------- |
| `~/.config/devin/config.json` (`%APPDATA%\devin\config.json` on Windows) | `"hooks"` key in user config |
| `~/.claude.json` | `"hooks"` key (Claude Code format) |
| `~/.claude/settings.json` | `"hooks"` key (Claude Code format) |
| `~/.claude/settings.local.json` | `"hooks"` key (Claude Code format) |
In `.devin/hooks.v1.json`, the hooks object is the **entire file** (no wrapper key needed). In all other locations, hooks are nested under the `"hooks"` key in a settings file.
Hooks from `.claude/` paths are loaded when `read_config_from.claude` is enabled (the default). You can disable this in your [user config](/cli/reference/configuration/read-config-from) if needed.
***
## Verifying Hooks
Use the `/hooks` slash command to see all currently loaded hooks and their source files:
```
/hooks
```
***
## Next Steps
Deep dive into each event type and what data is available.
Control which config locations Devin CLI reads hooks from.
# Extensibility Overview
Source: https://docs.devinenterprise.com/cli/extensibility/index
Customize and extend Devin CLI with rules, skills, and MCP servers
Devin CLI is designed to be deeply customizable. You can shape how the agent behaves, what tools it has access to, and how it responds to events — all through configuration files in your project or home directory.
Provide always-on context and instructions that guide the agent's behavior across every session.
Create reusable prompts and workflows the agent can invoke as slash commands or use autonomously.
Install and share bundles of skills across projects.
Define specialized subagent profiles with their own system prompts, tools, and models.
Connect external tool servers to give the agent access to APIs, databases, and more.
Run shell commands or LLM prompts at key points in the agent's lifecycle to enforce policies and automate workflows.
***
## How It All Fits Together
These features work at different layers:
* **Rules** shape the agent's personality and constraints — they're always active.
* **Skills** give the agent new capabilities it can invoke on demand.
* **Custom Subagents** define specialized worker profiles the agent can delegate tasks to.
* **MCP Servers** provide entirely new tools the agent can call.
* **Hooks** run shell commands or LLM prompts at lifecycle events (e.g., before a tool runs) to enforce policies or trigger workflows.
You can combine all of these in a single project. For example, you might have an `AGENTS.md` file with coding standards, a `review` skill for code review, an MCP server for your issue tracker, and hooks to block destructive commands.
***
## Where Configuration Lives
All project-level extensibility configuration lives in the `.devin/` directory at your project root:
```
my-project/
├── .devin/
│ ├── config.json # Project config (MCP, permissions)
│ ├── config.local.json # Personal overrides (gitignored)
│ ├── hooks.v1.json # Lifecycle hooks (Claude Code compatible)
│ ├── skills/
│ │ └── review/
│ │ └── SKILL.md # A custom skill
│ └── agents/
│ └── reviewer.md # A custom subagent profile (reviewer/AGENT.md also works)
├── AGENTS.md # Project rules
└── src/
```
User-level configuration lives in `~/.config/devin/` and applies to all projects. On Windows, this path is `%APPDATA%\devin\` instead.
Files with `.local.` in the name are automatically excluded from git, so you can have personal overrides without affecting your team.
***
## Importing From Other Tools
Devin CLI can read configuration from other AI coding tools you may already use:
| Source | What's Imported |
| -------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
| `AGENTS.md` / `AGENT.md` / `CLAUDE.md` | Rules (always-on context) |
| `.cursor/rules/*.md` / `.cursor/rules/*.mdc` | Rules |
| `.windsurf/rules/*.md` | Rules |
| `.claude/` directory | Commands, [custom subagents](/cli/subagents#custom-subagents), [hooks](/cli/extensibility/hooks/overview) |
This means you can start using Devin CLI without rewriting your existing configuration. Import is enabled by default and can be controlled in your config file:
```json theme={null}
{
"read_config_from": {
"cursor": true,
"windsurf": true,
"claude": true
}
}
```
Set any provider to `false` to disable importing from it.
# MCP Configuration
Source: https://docs.devinenterprise.com/cli/extensibility/mcp/configuration
How to add, configure, and manage MCP servers
## Adding MCP Servers
### Via Command Line
The quickest way to add an MCP server:
```bash theme={null}
# stdio server — just pass the command after --
devin mcp add -- [args...]
# HTTP server — pass the URL as a positional argument
devin mcp add
# HTTP server — or use the --url flag
devin mcp add --url
```
The transport type is inferred automatically: a URL implies HTTP (Streamable HTTP), and trailing args (or `--command`) imply stdio.
Remote MCP servers use Streamable HTTP by default. If the server responds with an HTTP 4xx error, the CLI falls back to SSE on the same URL. Set `"transport": "sse"` explicitly if needed — see [Legacy SSE fallback](#legacy-sse-fallback) below.
By default, servers are saved to **local** scope (`.devin/mcp_config.local.json`, gitignored). Use `-s`/`--scope` to change:
```bash theme={null}
devin mcp add -s project # shared via .devin/mcp_config.json
devin mcp add -s user # global (~/.config/devin/mcp_config.json; %APPDATA%\devin\mcp_config.json on Windows)
```
You can also manage servers from the command line:
```bash theme={null}
devin mcp list # List all configured servers
devin mcp get # Show details for a specific server
devin mcp remove # Remove a configured server
devin mcp login # Authenticate with a server via OAuth
devin mcp logout # Remove stored OAuth credentials
devin mcp enable # Enable a disabled server
devin mcp disable # Disable a server without removing it
```
### Via Config File
Add servers directly to your MCP config file's `mcpServers` section:
**The MCP config file location changed in v3000.3 (the Local 3.6 release).** Older versions (before v3000.3) store MCP servers in the `mcpServers` key of the main config files (`~/.config/devin/config.json`, `.devin/config.json`, `.devin/config.local.json`). Newer versions store them in dedicated files at the same locations: `~/.config/devin/mcp_config.json` (`%APPDATA%\devin\mcp_config.json` on Windows), `.devin/mcp_config.json`, and `.devin/mcp_config.local.json`. Any `mcpServers` entries found in the main config files are migrated to the dedicated files automatically on startup.
```json theme={null}
// .devin/mcp_config.json
{
"mcpServers": {
"server-name": {
"command": "npx",
"args": ["-y", "@company/mcp-server"],
"env": {
"API_KEY": "your-key"
}
}
}
}
```
Project-level servers are shared with your team via version control.
```json theme={null}
// ~/.config/devin/mcp_config.json
{
"mcpServers": {
"my-server": {
"command": "node",
"args": ["/path/to/my-server.js"],
"env": {}
}
}
}
```
User-level servers apply to all your projects.
```json theme={null}
// .devin/mcp_config.local.json
{
"mcpServers": {
"server-name": {
"command": "npx",
"args": ["-y", "@company/mcp-server"],
"env": {
"API_KEY": "my-personal-key"
}
}
}
}
```
Local configs are gitignored — use these for personal API keys.
***
## Server Configuration Options
MCP servers can be configured in two ways: as a **local command** (stdio transport) or as a **remote server** (HTTP transport).
### Local Command (stdio)
| Field | Type | Required | Description |
| ---------- | --------- | -------- | --------------------------------------------------------------------------------------------------------- |
| `command` | string | Yes | The executable to run |
| `args` | string\[] | No | Command-line arguments |
| `env` | object | No | Environment variables to set |
| `disabled` | boolean | No | Set to `true` to skip this server (see [Enabling and disabling servers](#enabling-and-disabling-servers)) |
### Remote Server (Streamable HTTP)
| Field | Type | Required | Description |
| ------------------- | ------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `url` | string | Yes | The URL of the MCP server endpoint |
| `transport` | string | No | `"http"` (Streamable HTTP, default for URL-based servers) or `"sse"` (legacy SSE). When set to `"http"` or omitted, the CLI tries Streamable HTTP first and falls back to SSE on 4xx errors ([per spec](https://spec.modelcontextprotocol.io/specification/2025-03-26/basic/transports/#backwards-compatibility)). Set `"sse"` explicitly if the server's SSE endpoint is at a different path. |
| `headers` | object | No | Custom HTTP headers to include in requests |
| `oauthClientId` | string | No | Pre-registered OAuth client ID, for servers that don't support dynamic client registration (DCR), e.g. GitHub. See the "Pre-registered OAuth clients" section below. |
| `oauthClientSecret` | string | No | OAuth client secret, for confidential clients. Pair with `oauthClientId`. |
| `oauthResource` | string | No | Override the RFC 8707 `resource` parameter sent in OAuth requests (default: the MCP server URL). Set to an empty string (`""`) to omit the parameter entirely, for providers that reject it. See [OAuth resource override](#oauth-resource-override). |
| `disabled` | boolean | No | Set to `true` to skip this server (see [Enabling and disabling servers](#enabling-and-disabling-servers)) |
### Examples
```json theme={null}
{
"mcpServers": {
"github": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-github"],
"env": {
"GITHUB_TOKEN": "ghp_..."
}
}
}
}
```
```json theme={null}
{
"mcpServers": {
"notion": {
"url": "https://mcp.notion.com/mcp",
"transport": "http"
}
}
}
```
After adding an OAuth-based server, run `devin mcp login notion` to authenticate. See [Authentication](#authentication) below.
```json theme={null}
{
"mcpServers": {
"linear": {
"url": "https://mcp.linear.app/mcp",
"transport": "http"
}
}
}
```
```json theme={null}
{
"mcpServers": {
"atlassian": {
"url": "https://mcp.atlassian.com/v1/mcp",
"transport": "http"
}
}
}
```
After adding, run `devin mcp login atlassian` to authenticate. Each MCP client (Windsurf, Claude Code, Devin CLI) maintains its own OAuth session, so you must log in separately even if you've already authenticated in another tool.
```json theme={null}
{
"mcpServers": {
"my-tools": {
"command": "python",
"args": ["./scripts/mcp-server.py"],
"env": {
"DB_URL": "postgres://localhost/mydb"
}
}
}
}
```
***
## Authentication
Some remote MCP servers require OAuth authentication. After adding an OAuth-based server to your config, authenticate using the `login` command:
```bash theme={null}
devin mcp login
```
For example:
```bash theme={null}
devin mcp login notion # Authenticate with Notion
devin mcp login linear # Authenticate with Linear
```
This opens a browser window where you can authorize access. The OAuth tokens are stored locally and refreshed automatically.
You can optionally request specific OAuth scopes:
```bash theme={null}
devin mcp login notion --scopes read,write
```
To remove stored OAuth credentials for a server:
```bash theme={null}
devin mcp logout
```
If the server supports OAuth, you will also be prompted to authenticate automatically when the server is first used.
### Re-authenticating
Stored OAuth credentials don't last forever — they expire, and an administrator can revoke them on the provider side. When that happens the server reports an **auth-required** state instead of connecting, and its tools (and [prompts](/cli/extensibility/mcp/overview#prompts-as-slash-commands)) stop being available until you sign in again.
To re-authenticate, clear the stored credentials and run the browser flow again:
```bash theme={null}
devin mcp logout
devin mcp login
```
`logout` deletes the persisted tokens for that server; `login` re-runs the OAuth flow and stores fresh ones. Do the same after changing `oauthClientId`, `oauthClientSecret`, or `oauthResource` — credentials issued under the old settings are not reused.
Editor integrations that drive Devin CLI over ACP surface the same auth-required state, with a re-authenticate action that clears the stored credentials and reopens the browser flow — equivalent to the `logout` + `login` pair above.
### Pre-registered OAuth clients
Most OAuth-based MCP servers support [dynamic client registration](https://datatracker.ietf.org/doc/html/rfc7591) (DCR), so Devin CLI registers itself automatically and you don't need to provide any client credentials.
Some providers (e.g. GitHub) don't support DCR and instead require a **pre-registered** OAuth client. For those, supply the client ID — and a client secret if it's a confidential client — via `oauthClientId` / `oauthClientSecret`:
```json theme={null}
{
"mcpServers": {
"my-server": {
"url": "https://mcp.example.com/mcp",
"transport": "http",
"oauthClientId": "Iv1.abc123def456",
"oauthClientSecret": "${env:MY_MCP_CLIENT_SECRET}"
}
}
}
```
When `oauthClientId` is set, Devin CLI skips dynamic client registration and uses your pre-registered client during the OAuth flow. Run `devin mcp login ` (or trigger first use) to authenticate as usual.
You can also set these from the command line when adding or logging into a server:
```bash theme={null}
devin mcp add my-server --oauth-client-id --oauth-client-secret
devin mcp login my-server --oauth-client-id --oauth-client-secret
```
`oauthClientId` / `oauthClientSecret` are OAuth client credentials used during the authorization flow. They are **not** generic per-request credentials — if a server expects a static token, use `headers` (HTTP) or `env` (stdio) instead.
Don't commit a client secret to a shared config. Reference it from an environment variable (`${env:VAR}`), read it from a file (`${file:/path}`), or put it in `.devin/mcp_config.local.json` (gitignored). See the "Managing Secrets" section below.
### OAuth resource override
During OAuth authorization and token exchange, Devin CLI sends an [RFC 8707](https://datatracker.ietf.org/doc/html/rfc8707) `resource` parameter so the authorization server can issue audience-restricted tokens. By default the value is the MCP server's URL. Override it with `oauthResource`:
```json theme={null}
{
"mcpServers": {
"my-server": {
"url": "https://my-server.example.com/mcp",
"transport": "http",
"oauthResource": ""
}
}
}
```
The field has three behaviors:
* **Unset** (default): sends `resource` set to the MCP server URL.
* **Non-empty value**: replaces the default with your value (e.g. a specific application ID URI).
* **Empty string (`""`)**: omits the `resource` parameter entirely from both the authorization URL and the token exchange.
You can also set it from the command line when adding or logging into a server:
```bash theme={null}
devin mcp add my-server --oauth-resource ""
devin mcp login my-server --oauth-resource ""
```
Like other OAuth fields, `oauthResource` supports `${env:VAR}` and `${file:/path}` expansion.
***
## Enabling and Disabling Servers
You can temporarily disable an MCP server without removing its configuration. A disabled server is skipped during tool discovery — its tools won't appear and the server process won't be started.
```bash theme={null}
devin mcp disable # Disable a server
devin mcp enable # Re-enable it
```
This sets the `"disabled": true` flag on the server entry in the config file. Use `-s`/`--scope` to target a specific scope:
```bash theme={null}
devin mcp disable -s project my-server
devin mcp enable -s user my-server
```
You can also set the flag directly in your config file:
```json theme={null}
{
"mcpServers": {
"my-server": {
"command": "npx",
"args": ["-y", "@company/mcp-server"],
"disabled": true
}
}
}
```
Disabling is useful when you want to keep a server's configuration (including environment variables and OAuth credentials) but temporarily stop using it — for example, to reduce startup time or isolate an issue.
***
## Managing Secrets
Never commit API keys or secrets to version control. Use `.devin/mcp_config.local.json` for sensitive values.
For team projects, the recommended pattern is:
1. Define the server in `.devin/mcp_config.json` with placeholder or no env vars
2. Each team member adds their personal keys in `.devin/mcp_config.local.json`
The local config file is automatically excluded from git.
***
## MCP Permissions
You can pre-approve, deny, or force-ask for specific MCP tools in your permissions config:
```json theme={null}
{
"permissions": {
"allow": [
"mcp__github__list_issues",
"mcp__github__create_issue"
],
"deny": [
"mcp__github__delete_repo"
],
"ask": [
"mcp__linear__*"
]
}
}
```
**Permission matcher patterns:**
| Pattern | Matches |
| ------------------- | ------------------------------------ |
| `mcp__server__tool` | A specific tool on a specific server |
| `mcp__server__*` | All tools on a specific server |
| `mcp__*` | All MCP tools on all servers |
***
## Prompts
Prompts need no configuration of their own: any connected server that declares the MCP `prompts` capability automatically contributes `/mcp____` slash commands. Because the command name embeds the server name, renaming a server in `mcpServers` renames its prompt commands too. See [MCP Overview — Prompts as slash commands](/cli/extensibility/mcp/overview#prompts-as-slash-commands).
***
## Organization restrictions
If you're on an enterprise team, your admin may restrict which MCP servers you can connect to. A server you've configured can be blocked if MCP is disabled for your team, or if it isn't on your team's allowlist or in an enforced **MCP registry** — in which case it won't connect and its tools won't be available. See [Team Settings — MCP Registry](/cli/enterprise/team-settings#mcp-registry) for details.
***
## Troubleshooting
If you see errors like `Auth required` or `AuthRequired` when connecting to a remote MCP server, the server requires OAuth authentication.
Run:
```bash theme={null}
devin mcp login
```
Each MCP client authenticates independently. Even if you've already authenticated in Windsurf or Claude Code, you need to run `devin mcp login` separately for Devin CLI.
To verify your auth status, try removing and re-adding credentials:
```bash theme={null}
devin mcp logout
devin mcp login
```
Verify the command works outside Devin CLI:
```bash theme={null}
npx -y @modelcontextprotocol/server-github
```
Check that all required environment variables are set.
Ask the agent to list MCP servers and tools. The server may need a moment to initialize.
Check your permissions config. MCP tools default to prompting for approval. Add them to `permissions.allow` to auto-approve.
Some authorization servers reject OAuth requests that include the RFC 8707 `resource` parameter. Set `oauthResource` to an empty string to omit the parameter:
```json theme={null}
{
"mcpServers": {
"my-server": {
"url": "https://my-server.example.com/mcp",
"oauthResource": ""
}
}
}
```
Then re-authenticate:
```bash theme={null}
devin mcp logout my-server
devin mcp login my-server
```
See [OAuth resource override](#oauth-resource-override) for the full set of `oauthResource` behaviors.
When connecting to an HTTP server, Devin CLI tries **Streamable HTTP** first. If the server responds with an HTTP 4xx error (e.g. 404 or 405), it automatically falls back to **legacy SSE** on the **same configured URL**. This follows the [MCP spec's backwards-compatibility guidance](https://spec.modelcontextprotocol.io/specification/2025-03-26/basic/transports/#backwards-compatibility).
The fallback only triggers on 4xx responses — connection errors, timeouts, and 5xx responses are reported directly without attempting SSE.
If your server's SSE endpoint is at a different path (e.g. `/sse` instead of `/mcp`), set `"transport": "sse"` with the SSE URL to connect directly without the Streamable HTTP attempt.
If both transports fail, the error message includes details from both attempts to help with troubleshooting.
# MCP Overview
Source: https://docs.devinenterprise.com/cli/extensibility/mcp/overview
Extend Devin CLI with external tool servers using the Model Context Protocol
MCP (Model Context Protocol) lets you connect external tool servers to Devin CLI, giving the agent access to APIs, databases, issue trackers, and any other service you can wrap in an MCP server.
When you configure an MCP server, its tools become available to the agent just like built-in tools. The agent can discover what tools are available and call them as needed.
***
## How It Works
You define an MCP server in your config file with a command, arguments, and optional environment variables.
Devin CLI starts the server process when needed. The server connects to the external API (GitHub, Linear, etc.).
The agent discovers what tools the server provides (e.g., `create_issue`, `list_repos`).
When the agent calls an MCP tool, the request flows through the server to the external service and the result is returned.
***
## Quick Example
Add a GitHub MCP server to your project:
```json theme={null}
// .devin/mcp_config.local.json (gitignored — keep tokens out of committed config)
{
"mcpServers": {
"github": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-github"],
"env": {
"GITHUB_TOKEN": "ghp_your_token_here"
}
}
}
}
```
Now the agent can create issues, read PRs, search repos, and more — all through natural language.
***
## Permission Control
Once configured, MCP tools appear with a namespaced format: `mcp____`. For example, a "github" server with a "create\_issue" tool becomes `mcp__github__create_issue`.
MCP tools are subject to the same permission system as built-in tools. You can control access at multiple levels:
```json theme={null}
{
"permissions": {
"allow": [
"mcp__github__*"
],
"deny": [
"mcp__github__delete_repo"
]
}
}
```
See [Permissions](/cli/reference/permissions) for the full permission syntax.
***
## Prompts as Slash Commands
Beyond tools, an MCP server can publish **prompts** — reusable, parameterized instructions declared through the MCP `prompts` capability. Devin CLI exposes each one as a slash command:
```
/mcp____ [arguments]
```
For example, a `linear` server that publishes a `bug_report` prompt becomes `/mcp__linear__bug_report`. Prompt commands are listed in the command palette under their own **MCP** category, described with the title or description the server publishes, and annotated with an argument hint built from the prompt's declared parameters — `` for required arguments and `[name]` for optional ones.
When you send the command, Devin CLI fetches the prompt from the server and substitutes the messages it returns as your message for that turn.
### How arguments map
Whatever you type after the command name is mapped **positionally** onto the prompt's declared arguments — first word to the first argument, second word to the second, and so on. The last declared argument receives all of the remaining text, so free-form trailing input survives intact:
```
/mcp__linear__bug_report ENG-1234 login page hangs after the SSO redirect
```
Here `ENG-1234` fills the first declared argument and the rest of the line fills the last one. If the prompt declares no arguments at all, anything you type is appended to the expanded prompt rather than dropped.
Only servers that have already connected contribute advertised commands (connections are warmed in the background at startup), but invocation resolves lazily — typing `/mcp____` works even when the command was never advertised, connecting to the server on demand.
Prompt expansion happens in the agent rather than in the terminal UI, so the same commands are advertised over ACP — editor integrations such as [Zed](/cli/acp/zed) and [JetBrains](/cli/acp/jetbrains) list them alongside built-in commands.
***
## Authentication
Some remote MCP servers (such as Atlassian, Notion, and Linear) require OAuth authentication. Each MCP client authenticates independently — tokens from Windsurf or Claude Code are **not** shared with Devin CLI.
After adding a remote server, authenticate with:
```bash theme={null}
devin mcp login
```
This opens a browser window for the OAuth flow. If stored credentials later expire or are revoked, the server reports an auth-required state and you re-authenticate with `devin mcp logout` followed by `devin mcp login` — see [MCP Configuration — Authentication](/cli/extensibility/mcp/configuration#authentication) and [Re-authenticating](/cli/extensibility/mcp/configuration#re-authenticating) for details.
***
## Disabling Servers
You can temporarily disable an MCP server without removing its configuration or credentials:
```bash theme={null}
devin mcp disable
devin mcp enable
```
See [MCP Configuration — Enabling and disabling servers](/cli/extensibility/mcp/configuration#enabling-and-disabling-servers) for details.
***
## Next Steps
Learn how to configure MCP servers in detail
Control which MCP tools the agent can use
# Plugins
Source: https://docs.devinenterprise.com/cli/extensibility/plugins/overview
Reference for installing, authoring, and governing plugins across Devin cloud sessions, the CLI, and Devin Desktop.
Plugins are in **closed beta**. To request access, contact [support@cognition.ai](mailto:support@cognition.ai). Behavior and configuration may change in future releases.
A **plugin** is a bundle of [skills](/cli/extensibility/skills/overview) and
optional rules, hooks, MCP servers, or custom subagents that you can install
from a GitHub repo, a git URL, a subfolder of a repo, or a local folder.
Plugins work across Devin cloud sessions, the [Devin CLI](/cli/index), and
Devin Desktop, subject to the surface-specific limitations described below.
Installing a plugin makes its skills available as `/:` slash
commands.
The **plugin is the unit of installation**. Installing a plugin installs all of
its skills and its `requiredPlugins`; you can't install individual skills from a
plugin. To offer skills separately, split them into separate plugins.
A plugin is just a source that contains:
```
my-plugin/
├── .devin-plugin/
│ └── plugin.json # The plugin manifest
├── AGENTS.md # Optional always-on rule
├── rules/ # Optional triggered rules
├── agents/
│ └── reviewer.md # Optional custom subagent (reviewer/AGENT.md also works)
├── hooks.json # Optional lifecycle hooks
├── .mcp.json # Optional MCP servers
└── skills/
└── review/
└── SKILL.md # An ordinary skill
```
The `skills/` directory holds ordinary skills — plugins introduce no new skill
format. See [Creating Skills](/cli/extensibility/skills/creating-skills) for the
`SKILL.md` format.
One repo (or one `git-subdir` subfolder) is one plugin. A single repo can host
many plugins as subfolders, each referenced with its own `git-subdir` source.
Beyond skills, a plugin can ship:
* **Rules** — an `AGENTS.md` at the plugin root is injected as an always-on
rule in every session, alongside your project's own rules. Markdown files in
a `rules/` folder are loaded too, with the same `trigger` frontmatter and
[activation types](/cli/extensibility/rules#rule-activation-types)
as [Windsurf rules](/cli/extensibility/rules#rules-from-other-tools).
* **Custom subagents** — `agents/.md` or `agents//AGENT.md`
profiles (the same
[custom subagent format](/cli/subagents#custom-subagents) as project
subagents), available
as `:`. Plugin subagents currently load in local Devin agents
only — the CLI and Devin Desktop — not in cloud Devin sessions.
* **Hooks** — a `hooks.json` at the plugin root registers
[lifecycle hooks](/cli/extensibility/hooks/lifecycle-hooks) that run in every
session where the plugin is installed. In cloud sessions, `command` hooks run
on the session's machine and only fire while that machine is up. They support
every event except `SessionStart` and `SessionEnd` — including `PreToolUse`,
`PostToolUse`, `PermissionRequest`, `UserPromptSubmit`, `Stop`, and
`PostCompaction`; `prompt`-type hooks are CLI/local-only.
* **MCP servers** — plugins can provide optional
[MCP servers](/cli/extensibility/mcp/overview) that start with the session.
Their tools are available to Devin, although plugin MCP servers don't yet
appear in the MCP settings UI. A plugin MCP config may set an OAuth client ID
and scopes, but never a client secret — a server config carrying one is
rejected at activation.
### Compatible formats
The layout above is Devin's own plugin format. Devin also loads plugins
packaged in two other layouts, with manifest precedence
`.devin-plugin/plugin.json` > `.claude-plugin/plugin.json` > root
`plugin.json`:
* **Claude plugins** — if there's no `.devin-plugin/plugin.json`, Devin falls
back to `.claude-plugin/plugin.json`. Claude plugins' root `.mcp.json` and
manifest `mcpServers` field are honored, and `${CLAUDE_PLUGIN_ROOT}` in
server configs expands to the plugin root.
* **Agent Plugins** — plugins packaged per the open
[Agent Plugins 1.0.0](https://github.com/agentplugins/agent-plugins-spec)
spec (a `plugin.json` manifest at the plugin root, MCP servers in a root
`mcp.json`, skills under `skills/`) load too. For these plugins the root
`mcp.json` is read as a conventional MCP source (after `.mcp.json`, which
wins on a server-name collision) — legacy Devin/Claude-layout plugins never
read it unless their manifest declares it explicitly. MCP entries may
declare their transport with the spec's `type` field (`stdio`,
`streamable-http`, or `sse`) instead of `transport`, and `${PLUGIN_ROOT}`
in server configs expands to the plugin root like `${CLAUDE_PLUGIN_ROOT}`.
An unrecognized `$schema` version is warned about and the plugin still
loads best-effort.
Agent Plugins MCP servers also get the spec's runtime conventions (these
apply only to plugins whose manifest is the root `plugin.json`; Devin and
Claude layouts behave exactly as before):
* `${PLUGIN_DATA}` in `args`, `env` values, and `cwd` expands to a
persistent, writable per-plugin data directory. The directory is keyed by
plugin identity — not version — so its contents survive plugin updates,
and it's deleted when the plugin is uninstalled.
* `stdio` server processes receive `PLUGIN_ROOT` and `PLUGIN_DATA`
environment variables alongside any `env` the config sets.
* A server may set `cwd` (relative to the plugin root); it defaults to the
plugin root. A `./`-prefixed `command` resolves against the plugin root,
so plugins can ship their own executables. Both are validated to stay
inside the plugin root or data directory.
***
## Installing a plugin
A plugin source can be a GitHub `owner/repo`, a git URL, or a local path:
```bash theme={null}
# From GitHub
devin plugins install acme/review-tools
# From any git host
devin plugins install https://gitlab.com/acme/review-tools.git
# From a local folder (great for authoring)
devin plugins install ./my-plugin
```
Before installing, Devin shows what the plugin adds — the skills it provides,
any required plugins that will be auto-installed, and any policy it introduces
(for example, if it forbids other plugins). Pass `-y` / `--yes` to skip the
prompt.
Plugins are installed at the **user** level and are available across all your
projects.
***
## Managing plugins
```bash theme={null}
# List installed plugins, their versions, and whether any are blocked by policy
devin plugins list
# Show a plugin's skills and its required/optional/forbidden lists
devin plugins info review-tools
# Re-fetch a plugin (or all plugins) at the latest version
devin plugins update review-tools
devin plugins update
# Remove a plugin (auto-installed required plugins are left in place)
devin plugins remove review-tools
```
Local plugins are linked directly to their source folder, so edits are live:
`devin plugins install ./my-plugin` → edit `skills//SKILL.md` → changes
apply on the next session, no `update` needed.
***
## Manifest
`.devin-plugin/plugin.json` describes the plugin. Only `name` is required, and
it must be unique among installed plugins (it is the `/:…` namespace).
Names are lowercase alphanumeric characters with single `-` or `.` separators
(e.g. `review-tools`, `acme.tools`).
```jsonc theme={null}
{
"name": "review-tools",
"version": "1.0.0",
"description": "Code-review skills for our team",
"requiredPlugins": [
"acme/secure-base",
{ "source": "github", "repo": "acme/audit-logging" }
],
"optionalPlugins": [
"acme/deploy-tools",
{ "source": "url", "url": "https://gitlab.com/acme/extra.git" }
],
"forbiddenPlugins": ["sketchy-org/bad-plugin", "acme/*", "*"]
}
```
### Metadata
`name`, `version`, `description`, `author` (`{ name, email }`), `homepage`,
`repository`, `license`, and `keywords`. Only `name` is used for the plugin's
identity and namespace; the rest are descriptive and shown by
`devin plugins info`.
### Skills & Rules
The `skills` field controls where skills load from, replacing the default
`skills/` directory. It accepts a single plugin-root-relative path or an array
of them:
```jsonc theme={null}
{ "skills": "custom-skills" }
{ "skills": ["skills", "extra/skills"] }
```
An empty array (`"skills": []`) disables skill loading entirely. Paths must
stay inside the plugin — absolute paths, `~`, and `..` traversal are rejected,
and an invalid entry fails the whole manifest.
Rules load independently of `skills`: an `AGENTS.md` at the plugin root is
always-on, and Markdown files in the `rules/` directory are loaded as triggered
rules. See [Rules](/cli/extensibility/rules) for activation details.
### MCP Servers
The `mcpServers` field adds [MCP server](/cli/extensibility/mcp/overview)
declarations. Plugins can also use the conventional root `.mcp.json` (and
`mcp.json` for plugins using the Agent Plugins root-manifest layout). Four
shapes are accepted:
```jsonc theme={null}
// One declaration file
{ "mcpServers": "config/mcp.json" }
// Several, read in the order listed
{ "mcpServers": ["config/mcp.json", "config/extra.json"] }
// Only these files — suppresses the root .mcp.json / mcp.json convention
{ "mcpServers": { "paths": ["config/mcp.json"], "exclusive": true } }
// Inline server map (suppresses the root convention when non-empty)
{ "mcpServers": { "linear": { "command": "npx", "args": ["-y", "linear-mcp"] } } }
```
Declared paths follow the same containment rules as `skills`, but unsafe
entries are dropped rather than failing the plugin. An invalid `mcpServers`
field only disables MCP loading, leaving skills, rules, and hooks usable. An
empty array adds no declaration files but does not suppress the root convention.
An empty inline map likewise leaves the root convention enabled. When the same
server name appears in more than one source, the first source wins.
### Dependencies
A dependency entry is a **source** — either a string shorthand or an object:
| Form | Meaning |
| ------------------------------------------------------------------ | ----------------------------------------------- |
| `"owner/repo"` | GitHub repository |
| `"https://…"`, `"git@…"`, `"ssh://…"` | any git URL |
| `{ "source": "github", "repo": "owner/repo" }` | GitHub, object form |
| `{ "source": "url", "url": "https://gitlab.com/team/plugin.git" }` | git URL, object form |
| `{ "source": "git-subdir", "url": "…", "path": "sub/dir" }` | a plugin living in a subfolder of a shared repo |
All GitHub forms for the same repo (`owner/repo`, the HTTPS URL, the `.git` URL, the SSH form) refer to the same plugin identity.
A plugin can declare three lists, which let a single plugin act as a curated,
governed collection of other plugins.
#### `requiredPlugins`
Auto-installed (recursively) when the plugin is installed. If a required plugin
is blocked by policy, the whole install fails — there is no partial install.
#### `optionalPlugins`
An **allow-list** of plugins this plugin endorses. They are **not**
auto-installed; the list only matters as a carve-out against a forbidden entry
(see below).
#### `forbiddenPlugins`
A **deny-list** of plugin identities and glob patterns.
`forbiddenPlugins` entries are matched against plugin identities:
* An **exact identity**, written as `owner/repo` or a git URL. All GitHub forms of the same repo (`owner/repo`, the HTTPS URL, the `.git` URL, the SSH form) refer to the same identity.
* A **glob pattern** — any entry containing `*`. The `*` matches any sequence of characters, including `/`: `acme/*` matches all of `acme`'s GitHub repos, `*/secrets` matches a repo named `secrets` under any owner, and `https://gitlab.com/acme/*` matches any repo under that path.
* The lone `"*"`, which matches everything else (a full lockdown).
The lists combine deny-wins:
* **Deny wins.** A plugin is blocked if any active manifest or installed plugin forbids it. If nothing forbids anything, nothing is blocked.
* **Self-override.** A manifest's (or plugin's) own `requiredPlugins` and `optionalPlugins` — and, for a plugin, the plugin itself — are exempt from its **own** forbidden list, so `"forbiddenPlugins": ["*"]` plus `"optionalPlugins": ["acme/approved"]` means "allow only what this manifest lists; forbid everything else." The carve-out covers only those direct entries, not a required plugin's transitive dependencies — list those explicitly under a lockdown.
* **No cross-scope re-permitting.** One manifest's or plugin's allow-list cannot re-permit what **another** forbids. A `"forbiddenPlugins": ["*"]` lockdown can't be defeated from a lower scope.
Enforcement happens at two points:
* **Install time** — installing a blocked plugin (or one whose required plugins can't be satisfied, or whose name collides with an installed plugin) is refused.
* **Load time** — a plugin blocked after it's already installed stays on disk, but its skills are skipped at session start with a warning naming the forbidder.
A forbidden identity can also be a **local path** (for plugins installed from a
local folder), in addition to the `owner/repo` and git-URL forms above.
***
## Inheritance and levels
Plugins aren't declared in one place. Beyond your own installs, plugins can be
required, endorsed, or forbidden by your repo and by your organization's admin.
Each source is a **level**, and the levels are ranked by **authority**, highest
first:
1. **Enterprise** — the account-wide managed manifest, configured by an admin.
2. **Org** — an org-level managed manifest, layered below its account (an org
can add to what its account declares, but can't overrule it). This applies
only to **cloud Devin sessions**: the CLI authenticates at the account level
and has no org context, so org-level requires and forbids don't reach CLI
users. Put anything you need enforced in the CLI in the enterprise/account
manifest.
3. **Repo** — the `requiredPlugins` / `optionalPlugins` / `forbiddenPlugins` in a
checkout's `.devin/config.json`, discovered by walking up from your working
directory.
4. **User** — plugins you install yourself with `devin plugins install`.
Every level declares the same three lists, and within a level they combine with
the same [deny-wins, self-override rules](#dependencies) as a
single manifest. What the levels add on top is one rule: **higher authority
wins**.
### Higher authority wins
* A lower level can never **re-permit** what a higher level forbids.
* A lower level can never **forbid** what a higher level requires — the forbid is
ignored and the plugin still loads.
So an admin can mandate a plugin no repo or user can opt out of, and forbid a
plugin no lower level can bring back.
### A denylist is only overridden at its own level
Because allow-lists don't cross levels, the **only** way to carve an exception
out of a denylist is at the same level that declared it. A level's `forbiddenPlugins`
is overridden only by that same manifest's own `optionalPlugins` (or
`requiredPlugins`) — never by a list at a lower level.
For example, an enterprise-level managed manifest can lock the account down to a
single approved plugin:
```jsonc theme={null}
// Enterprise-level managed manifest
{
"forbiddenPlugins": ["*"],
"optionalPlugins": ["acme/approved"]
}
```
This means "across the whole account, allow only `acme/approved` and forbid
every other plugin." No org, repo, or user can widen that allow-list — not by
installing a plugin, and not by adding it to a lower level's `optionalPlugins`.
The carve-out also covers only the entries this manifest lists directly; a
required plugin's own transitive dependencies aren't exempt, so list those
explicitly under a lockdown.
### Conflicts and dependencies
* A require and a forbid for the same plugin at the **same level** but from
**different manifests** (for example two separately installed user-level
plugins) resolve to the forbid — an allow-list only exempts entries in its
*own* manifest, so it can't rescue a plugin another manifest forbids. (Within
a single manifest, its own required/optional stay exempt from its own forbids,
as [above](#a-denylist-is-only-overridden-at-its-own-level).)
* A plugin blocked by governance **soft-fails**: at session start its skills are
skipped with a warning naming the forbidder, rather than aborting the session.
* Being depended upon grants no exemption. A plugin pulled in only as a
transitive dependency is still subject to every forbid that applies to it, and
it inherits the highest authority level of any plugin that requires it.
# Quickstart: team marketplace
Source: https://docs.devinenterprise.com/cli/extensibility/plugins/quickstart
Set up a shared Devin plugin marketplace for your team with reusable skills, rules, hooks, MCP servers, and governance.
Plugins are in **closed beta**. To request access, contact [support@cognition.ai](mailto:support@cognition.ai). Behavior and configuration may change in future releases.
This quickstart takes you from zero to a **team plugin marketplace**: one repo your org owns that bundles your skills, rules, hooks, and MCP servers, installed automatically for every Devin session and CLI user. For the full background, see [Set up your plugin ecosystem](/product-guides/plugin-ecosystem).
## 1. Fork the template
Fork [CognitionAI/team-marketplace-template](https://github.com/CognitionAI/team-marketplace-template). Its layout:
```
your-marketplace/
├── .devin-plugin/
│ └── plugin.json # the meta-plugin: your baseline + policy
├── AGENTS.md # always-on rule shipped with the baseline
├── plugins/
│ ├── engineering-baseline/ # each subfolder is its own plugin
│ ├── security-guardrails/
│ ├── frontend-standards/
│ └── docs-and-release/
└── scripts/validate-template.mjs # CI validation
```
The repo root is itself a plugin — the **meta-plugin**. Installing the repo installs your whole baseline: its manifest's `requiredPlugins` pulls in the plugins every teammate should have, `optionalPlugins` endorses extras, and `forbiddenPlugins` blocks what you don't want.
## 2. Make it yours
* In the root `.devin-plugin/plugin.json`, change every `git-subdir` URL to point at **your fork**, and edit the required/optional/forbidden lists.
* Add a plugin per team or concern under `plugins//` — each needs its own `.devin-plugin/plugin.json` and typically a `skills//SKILL.md`. Starting a plugin from scratch? Use [CognitionAI/plugin-template](https://github.com/CognitionAI/plugin-template).
* Have an existing repo of skills? Drop each skill folder into a plugin's `skills/` directory — skills inside plugins are ordinary [skills](/cli/extensibility/skills/creating-skills), no format change.
## 3. Test locally with the CLI
```bash theme={null}
node scripts/validate-template.mjs # structural validation (also runs in CI)
devin plugins install . # install the meta-plugin from your checkout
devin plugins list # see everything it pulled in
```
Local installs are linked, so edits apply on your next session — iterate on a skill, then start a session and invoke it as `/:`.
## 4. Distribute it to everyone
An org or enterprise admin adds one required plugin to the managed manifest at [Settings → Resources → Plugins](https://app.devin.ai/settings/marketplace):
```json theme={null}
{
"requiredPlugins": ["your-org/your-marketplace"]
}
```
Everyone in scope gets the baseline automatically — cloud sessions and, for the enterprise/account manifest, CLI and Devin Desktop users logged into the account too (org-level manifests reach cloud sessions only). A private repo works as-is: cloud fetches through your Git integration; CLI users fetch with their own git credentials.
## 5. Evolve and govern
* Merging to your marketplace repo's default branch **is** the release — new sessions pick it up automatically. See [how updates roll out](/product-guides/plugins#how-updates-roll-out).
* Teams add plugins by PR to the marketplace repo; CI validates the layout.
* To lock the account down to your approved set only, add `"forbiddenPlugins": ["*"]` to the managed manifest and list every approved plugin (including the meta-plugin's dependencies — transitive deps aren't exempt) in `requiredPlugins`/`optionalPlugins`. Full semantics: [dependencies and governance](/cli/extensibility/plugins/overview#dependencies).
## Next steps
* [Set up your plugin ecosystem](/product-guides/plugin-ecosystem) — the full org playbook
* [Plugins reference](/cli/extensibility/plugins/overview) — manifest format, install flows, governance levels
* [Plugin marketplace](/product-guides/plugins) — the web app side: manifests, scopes, uploads
# Rules & AGENTS.md
Source: https://docs.devinenterprise.com/cli/extensibility/rules
Provide always-on instructions and context that guide the agent in every session
Rules are persistent instructions that shape how Devin CLI behaves in your project. They're injected into the agent's context at the start of every session, ensuring consistent behavior across your team.
Common uses for rules include coding standards, architectural guidelines, preferred libraries, testing conventions, and project-specific constraints.
**To improve coding ability, speed of completion, and lower cost**, we highly recommend **using Skills instead whenever possible**. Skills are only injected into the context when relevant. **Rules and AGENTS should be kept as small as possible.**
**Our recommended pattern** is to use a rule to reference skills that the model should use in particular scenarios.
***
## AGENTS.md
The simplest way to add rules is with an `AGENTS.md` file at your project root:
```markdown theme={null}
# Project Rules
- Use TypeScript for all new files
- Follow the existing patterns in src/components/
- Always run `npm run lint` before committing
- Use pnpm, not npm or yarn
- Write tests for all new utility functions
```
Devin CLI reads this file automatically.
`AGENTS.md` is the recommended approach for project rules. It's easy to read, version-controlled, and works across multiple AI tools.
***
## Global Rules
You can also create rules that apply to **every project** by placing an `AGENTS.md` file in your user config directory:
```
~/.config/devin/AGENTS.md
```
```
%APPDATA%\devin\AGENTS.md
```
Global rules are loaded at the start of every session, regardless of which project you're working in. Use them for personal preferences that apply everywhere:
```markdown theme={null}
# My Global Rules
- Always write commit messages in conventional commit format
- Prefer functional patterns over imperative code
- Run tests before suggesting a task is complete
```
Global rules work alongside project rules — both are loaded and active at the same time. `AGENT.md` is also supported at this location.
If you use Claude Code, Devin CLI also reads `~/.claude/CLAUDE.md` as a global rule.
***
## Personal Rules with AGENTS.local.md
If you have personal instructions that shouldn't be shared with collaborators — such as preferred working style, testing habits, or review preferences — create an `AGENTS.local.md` file next to your `AGENTS.md`:
```markdown theme={null}
# My Personal Rules
- Always start by writing failing tests before implementing a fix
- Prefer functional patterns over imperative code
- Run the full test suite before marking a task as complete
```
This file is loaded alongside `AGENTS.md` with the same always-on behavior. Add it to your `.gitignore` so it stays local:
```gitignore theme={null}
AGENTS.local.md
```
This follows the same convention as `.devin/config.local.json` — the `.local.` suffix signals a personal override that shouldn't be committed.
***
## Supported File Names
Devin CLI reads rules from any of these files:
| File | Notes |
| ----------------- | ------------------------------- |
| `AGENTS.md` | Recommended |
| `AGENTS.local.md` | Personal rules (gitignored) |
| `AGENT.md` | Singular alternative |
| `.windsurfrules` | Legacy Windsurf workspace rules |
| `CLAUDE.md` | Compatible with Claude Code |
All of these are treated identically — their contents are loaded as always-on rules.
These files can exist at multiple levels in your project (not just the root). Files at the workspace root are loaded at session start. Files in subdirectories are discovered lazily when the agent accesses files in that directory, keeping the context focused on the relevant part of the codebase.
They can also be placed in the [global config directory](#global-rules) to apply across all projects, except `CLAUDE.md` which is read globally from `~/.claude/CLAUDE.md`.
Installed [plugins](/cli/extensibility/plugins/overview) can ship rules too: an always-on `AGENTS.md` at the plugin root plus `rules/*.md` files with `trigger` frontmatter.
***
## Rules in the .devin Directory
Devin CLI also reads rules from the `.devin/` directory, one rule per file:
| Path | Notes |
| ------------------------ | ------------------------------------------------- |
| `.devin/rules/*.md` | One rule per file. Supports `trigger` frontmatter |
| `.devin/global_rules.md` | Single always-on file |
These files use the same frontmatter as `.windsurf/rules/*.md`, so the `trigger` values `always_on`, `manual`, `model_decision`, `agent`, and `glob` all apply.
`.devin/` is the preferred location and takes precedence over `.windsurf/`. If both `.devin/global_rules.md` and `.windsurf/global_rules.md` exist, Devin CLI loads only `.devin/global_rules.md`. Rule files in `.devin/rules/` and `.windsurf/rules/` are both loaded.
Like other project rules, these directories are read at the workspace root and in each directory between the workspace root and your current directory. You can also place them in your home directory (`~/.devin/rules/*.md`, `~/.devin/global_rules.md`) to apply them to every project.
***
## Rules From Other Tools
If you're coming from another AI coding tool, Devin CLI can read your existing rules:
Devin CLI reads from `.cursor/rules/*.md` and `.cursor/rules/*.mdc`.
Cursor rules support frontmatter to control activation:
```markdown theme={null}
---
description: "React component guidelines"
globs: "src/components/**/*.tsx"
alwaysApply: false
---
Use functional components with hooks. Never use class components.
```
**Activation behavior:**
* `alwaysApply: true` — Always active
* `globs` specified — Active when working with matching files
* `description` only — Agent decides when to apply
* None of the above — User must invoke manually
Devin CLI reads from `.windsurf/rules/*.md` and `.windsurf/global_rules.md`. The Devin-native [`.devin/` equivalents](#rules-in-the-devin-directory) take precedence.
**Subdirectory support:** `.windsurf/rules/` directories can exist at multiple levels in your project, not just the root. Rules at the workspace root are loaded at session start. Rules in subdirectories are discovered lazily — when the agent accesses files in that directory, any `.windsurf/rules/` found there (and in parent directories up to the workspace root) are automatically loaded. This avoids polluting the agent's context with rules from unrelated parts of the project.
Windsurf rules support frontmatter:
```markdown theme={null}
---
description: "API design rules"
trigger: always_on
---
All API endpoints must return JSON with a consistent envelope format.
```
**Trigger values:** `always_on`, `manual`, `model_decision`, `agent`, `glob`
Devin CLI reads from the `.claude/` directory.
Devin CLI does not support `.codeiumignore` files. If you use Codeium's autocomplete and have configured ignore patterns, those patterns will not apply to Devin CLI.
***
## Controlling Imports
You can enable or disable reading from specific tool formats in your config file (`~/.config/devin/config.json` — or `%APPDATA%\devin\config.json` on Windows — or `.devin/config.json`):
```json theme={null}
{
"read_config_from": {
"agents_standard": true,
"cursor": true,
"windsurf": true,
"claude": true
}
}
```
Standard project rules from `AGENTS.md`, `AGENTS.local.md`, `AGENT.md`, and `.windsurfrules` are read by default. Set `"agents_standard": false` to disable importing them.
***
## Rule Activation Types
Rules loaded from external formats may have different activation behaviors:
| Type | Behavior |
| ------------------ | ----------------------------------------------------------------- |
| **Always-on** | Active in every session, no user action needed |
| **Glob-activated** | Active when the agent works with files matching specific patterns |
| **Agent-decided** | The agent chooses when to apply based on the rule's description |
| **User-invocable** | Only active when explicitly triggered by the user |
Rules from `AGENTS.md` are always "always-on".
***
## Best Practices
Long, verbose rules dilute the agent's attention. Focus on what matters most.
"Use pnpm" is better than "use the right package manager". Concrete instructions are easier to follow.
Show the pattern you want, not just a description of it.
Keep rules in your repo so the whole team benefits from the same guidelines.
For most common types of rules, consider using skills instead. Skills give you more control over when and how they're applied.
# Creating Skills
Source: https://docs.devinenterprise.com/cli/extensibility/skills/creating-skills
Full reference for the SKILL.md format and frontmatter options
Skills are defined as `SKILL.md` files inside a named directory. This page covers everything you need to know to write effective skills.
***
## File Structure
Place skills in the appropriate directory depending on scope:
```
# Project-specific (committed to git)
.devin/skills/
└── my-skill/
└── SKILL.md
# Global — available in all projects (not committed)
# Linux/macOS:
~/.config/devin/skills/
└── my-skill/
└── SKILL.md
# Windows:
%APPDATA%\devin\skills\
└── my-skill\
└── SKILL.md
```
The directory name is the skill's identifier (used for `/my-skill` invocation). The `SKILL.md` file contains optional YAML frontmatter and the skill's prompt content.
On Windows, `%APPDATA%` typically resolves to `C:\Users\\AppData\Roaming`.
***
## Frontmatter Reference
```yaml theme={null}
---
name: my-skill
description: What this skill does (shown in completions)
argument-hint: "[file] [options]"
model: sonnet
subagent: true
allowed-tools:
- read
- grep
- glob
- exec
permissions:
allow:
- Read(src/**)
deny:
- exec
ask:
- Write(**)
triggers:
- user
- model
---
Your prompt content goes here...
```
### All Frontmatter Fields
| Field | Type | Default | Description |
| --------------- | ------- | --------------- | ------------------------------------------------------------------------------------------------------- |
| `name` | string | directory name | Display name of the skill |
| `description` | string | none | Shown in slash command completions |
| `argument-hint` | string | none | Hint shown after the command name (e.g., `[filename]`) |
| `model` | string | current model | Override the model used when running this skill |
| `subagent` | boolean | `false` | Run the skill as a [subagent](/cli/subagents) instead of inline |
| `agent` | string | none | Run the skill as a subagent using a specific [custom subagent](/cli/subagents#custom-subagents) profile |
| `allowed-tools` | list | all tools | Restrict which tools the skill can use |
| `permissions` | object | inherit | Permission overrides for this skill |
| `triggers` | list | `[user, model]` | How the skill can be invoked |
***
## Model Override
Use the `model` field to run a skill with a different model than the one active in the current session. This is useful for using a faster model for simple tasks or a more capable model for complex ones:
```yaml theme={null}
---
name: quick-fix
description: Fast lint fix using a lightweight model
model: swe
---
Fix the lint errors in the current file.
```
The model name uses the same values as the `--model` CLI flag (e.g., `opus`, `sonnet`, `swe`, `codex`). See [Models](/cli/models) for the full list.
***
## Running Skills as Subagents
Running skills as subagents is **experimental**. The `subagent` and `agent` frontmatter fields may change in future releases.
By default, a skill's prompt is injected into the current conversation — the agent processes it inline. You can instead run a skill as a **subagent**, which spawns an independent worker with its own context window. This is useful for skills that perform focused, self-contained tasks where you don't want the output to clutter the main conversation.
There are two ways to run a skill as a subagent:
### `subagent: true`
Set `subagent: true` to run the skill as a subagent using the default `subagent_general` profile:
```yaml theme={null}
---
name: deep-research
description: Thorough codebase research on a topic
subagent: true
model: sonnet
allowed-tools:
- read
- grep
- glob
---
Research the topic the user asked about thoroughly.
Search broadly, follow references, and trace call chains.
Report all findings with specific file paths and line numbers.
```
When invoked, this skill spawns a foreground subagent that runs the skill's prompt as its task. The parent agent waits for the subagent to complete, then reads and summarizes the results.
### `agent: `
Use the `agent` field to run the skill as a subagent with a specific [custom subagent profile](/cli/subagents#custom-subagents):
```yaml theme={null}
---
name: review-pr
description: Review the current PR using the reviewer subagent
agent: reviewer
---
Review the staged changes for correctness, security, and style issues.
```
The `agent` value must match the name of a registered subagent profile (either built-in like `subagent_explore` / `subagent_general`, or a custom profile you've defined). The subagent inherits the profile's system prompt, tool restrictions, and model — while the skill's content becomes the task.
If both `agent` and `subagent` are set, `agent` takes precedence. The `model` field on the skill overrides the subagent profile's model when both are specified.
Skills running as subagents do not spawn nested subagents — if the skill is already executing inside a subagent, it runs inline instead to prevent infinite recursion.
### Orchestrating Subagents Using Skills
Because skills can run as subagents, you can use them to orchestrate multi-step work. Define a set of subagent skills that each handle a focused task, then write a regular skill that invokes them. The outer skill becomes the orchestrator — it calls each subagent, collects the results, and decides what to do next.
For example, here are two subagent skills and an orchestrator that coordinates them:
```markdown theme={null}
---
name: research-changes
description: Research recent code changes and their impact
subagent: true
allowed-tools:
- read
- grep
- glob
- exec
---
Analyze the recent changes in this repository:
1. Run `git log --oneline -20` to see recent commits
2. For each significant commit, examine what changed and why
3. Identify any patterns, risks, or areas that need attention
Report your findings with specific file paths and commit references.
```
```markdown theme={null}
---
name: validate-tests
description: Run tests and validate coverage for recent changes
subagent: true
allowed-tools:
- read
- grep
- glob
- exec
---
Validate the test suite for the project:
1. Identify the test framework and run command
2. Run the full test suite
3. Check for any failing tests
4. Review test coverage for recently changed files
Report which tests pass, which fail, and any coverage gaps.
```
```markdown theme={null}
---
name: health-check
description: Full project health check — research changes then validate tests
---
Perform a full health check on this project:
1. First, use the /research-changes skill to understand recent changes
2. Then, use the /validate-tests skill to verify the test suite
3. Finally, synthesize the findings from both into a summary:
- What changed recently and why
- Whether tests are passing
- Any risks or recommended actions
```
Invoking `/health-check` runs the orchestrator in the main agent. It calls `/research-changes`, which spawns a subagent to explore the repo. Once that finishes, it calls `/validate-tests`, which spawns another subagent to run the tests. The orchestrator then synthesizes both results into a final summary.
A subagent skill will **never** use a subagent when calling other skills, even if those skills have `subagent: true` — they run inline instead. This means you don't need to worry about unbounded nesting. The orchestration pattern is always one level deep: the orchestrator spawns subagents, and those subagents execute everything else inline.
***
## Prompt Content
The body of the SKILL.md file (after the frontmatter) is the prompt that gets injected when the skill is invoked.
***
## Permissions
Skills can define their own permission scope using the same syntax as the main permissions config:
```yaml theme={null}
permissions:
allow:
- Read(src/**)
- Exec(npm run test)
deny:
- Write(/etc/**)
- exec
ask:
- Write(src/**)
```
**How skill permissions work:**
* `allow` — These scopes are auto-approved during skill execution
* `deny` — These scopes are blocked during skill execution
* `ask` — These scopes always prompt the user
Skill permissions are additive to (not replacing) the session's base permissions. A skill cannot grant permissions that are denied at a higher level (project or organization config).
***
## Allowed Tools
Restrict which tools the skill can use:
```yaml theme={null}
allowed-tools:
- read
- grep
- glob
```
Available tool names: `read`, `edit`, `grep`, `glob`, `exec`
You can also allow MCP tools:
```yaml theme={null}
allowed-tools:
- read
- mcp__github__list_issues
- mcp__github__create_issue
```
If `allowed-tools` is not specified, the skill has access to all tools. For safety-critical skills, always restrict to the minimum needed.
***
## Examples
### Code Review Skill
```markdown theme={null}
---
name: review
description: Review staged changes for issues
allowed-tools:
- read
- grep
- glob
- exec
permissions:
allow:
- Exec(git diff)
- Exec(git log)
---
Run `git diff --staged` and review the changes for quality issues.
Evaluate:
1. **Correctness** — Any logic errors or edge cases?
2. **Security** — Any vulnerabilities introduced?
3. **Performance** — Any obvious inefficiencies?
4. **Style** — Consistent with the codebase?
Provide a summary with specific line references.
```
### Component Generator
```markdown theme={null}
---
name: component
description: Generate a React component from a description
argument-hint: ""
allowed-tools:
- read
- edit
- grep
- glob
model: sonnet
permissions:
allow:
- Write(src/components/**)
---
Create a new React component using the name the user provides:
1. Check existing components in src/components/ for style conventions
2. Create the component file at src/components//.tsx
3. Create a barrel export at src/components//index.ts
4. Add basic tests at src/components//.test.tsx
5. Follow the patterns you find in existing components
```
### Deployment Checklist
```markdown theme={null}
---
name: deploy
description: Run through the deployment checklist
triggers:
- user
allowed-tools:
- read
- exec
- grep
permissions:
allow:
- Exec(npm run)
- Exec(git)
---
Run through the deployment checklist:
1. Run the test suite: `npm run test`
2. Run the linter: `npm run lint`
3. Check for uncommitted changes: `git status`
4. Verify the build: `npm run build`
5. Show the current branch and last commit
Report the status of each step. If anything fails, stop and explain the issue.
```
### Search Expert
```markdown theme={null}
---
name: find
description: Find relevant code across the project
argument-hint: ""
allowed-tools:
- read
- grep
- glob
triggers:
- user
- model
---
Search the codebase thoroughly for what the user asked about.
Use grep for content search and glob for file discovery.
Provide relevant file paths and code snippets.
Explain how the pieces connect.
```
***
## Tips
A skill should do one thing well. Create multiple skills rather than one mega-skill.
Show the agent what good output looks like in your prompt.
Restricting tools makes skills safer and more predictable.
Invoke your skill and iterate on the prompt until the output is what you want.
# Skills Overview
Source: https://docs.devinenterprise.com/cli/extensibility/skills/overview
Create reusable prompts and workflows that extend the agent's capabilities
Skills are self-contained units of functionality that you can teach to Devin CLI. They bundle prompts, tool access, permissions, and workflows into a reusable package that can be invoked by either the agent or the human operator.
***
## What Are Skills?
Think of skills as expert knowledge you give the agent. A skill might teach it how to:
* Review code according to your team's standards
* Generate a specific type of component
* Run a deployment workflow
* Perform a security audit
* Set up a new service from a template
Users can invoke skills with `/skill-name` in the chat.
The agent can invoke skills on its own when relevant.
Skills can have their own permission grants and restrictions.
Restrict which tools a skill can use for safety.
Run skills as independent [subagents](/cli/subagents) with their own context window.
Use a different [model](/cli/models) for specific skills.
***
## Quick Example
Create a code review skill at `.devin/skills/review/SKILL.md` (or `.windsurf/skills/review/SKILL.md`):
```markdown theme={null}
---
name: review
description: Review code changes before committing
allowed-tools:
- read
- grep
- glob
- exec
---
Review the current git diff and provide feedback:
1. Run `git diff --staged` (or `git diff` if nothing is staged)
2. Check for:
- Logic errors or bugs
- Missing error handling
- Security issues
- Style inconsistencies
3. Summarize findings and suggest improvements
```
Now you can invoke it with `/review` in any session.
***
## How Skills Work
When a skill is invoked:
1. The skill's prompt is injected into the conversation
2. Tool access is restricted to the skill's `allowed-tools` (if specified)
3. Additional permissions from the skill's config are applied
4. The specified model is used (if different from the current one)
***
## Skill Triggers
Skills can be invoked in two ways:
| Trigger | Description | Default |
| ------- | ------------------------------------------- | ------- |
| `user` | User can invoke with `/skill-name` | Enabled |
| `model` | Agent can invoke autonomously when relevant | Enabled |
```yaml theme={null}
---
name: security-check
triggers:
- user
- model
---
```
Set `triggers: [user]` to prevent the agent from invoking a skill on its own.
***
## Third-party Skills
We support the `.agents` skills standards, so third-party skill installation tools work with Devin CLI.
Third-party skills can execute arbitrary code, so install them at your own risk.
***
## Where Skills Live
Skills can be scoped to a single project or shared across all projects:
| Location | Scope | Committed to git? |
| --------------------------------------------- | ---------------------------------------- | ----------------- |
| `.agents/skills//SKILL.md` | Project-specific | Yes |
| `.devin/skills//SKILL.md` | Project-specific | Yes |
| `.windsurf/skills//SKILL.md` | Project-specific | Yes |
| `~/.agents/skills//SKILL.md` | Global (all projects) | No |
| `~/.config/devin/skills//SKILL.md` | Global (all projects) | No |
| `~/.codeium//skills//SKILL.md` | Global (all projects, channel-dependent) | No |
**Project skills** live in the `.devin/skills/` or `.windsurf/skills/` directory at your project root and are committed to version control, making them shareable with your team. Both locations use the same `SKILL.md` format.
**Global skills** live in `~/.config/devin/skills/` (following [XDG conventions](https://specifications.freedesktop.org/basedir-spec/latest/)) or `~/.codeium//skills/` (where `` is `windsurf`, `windsurf-next`, or `windsurf-insiders` depending on your CLI channel) and are available in every project on your machine.
**Windows:** The global skills path follows your system's application data directory. On Windows, use `%APPDATA%\devin\skills\\SKILL.md` (typically `C:\Users\\AppData\Roaming\devin\skills\\SKILL.md`) instead of `~/.config/devin/skills/`.
***
## Next Steps
Learn the full skill format including frontmatter options, dynamic content, and examples.
Bundle skills into a plugin you can install and share across projects.
# Hand off to cloud Devins
Source: https://docs.devinenterprise.com/cli/handoff
Hand off a task from the Devin CLI to a cloud Devin session with /handoff.
When a task outgrows your local machine — or you want Devin to keep working while you step away — use the built-in `/handoff` command to transfer the current session to a cloud [Devin session](/get-started/first-run). The cloud session gets its own VM with a shell, browser, and full repo access, so it can keep going after you close your laptop.
```
/handoff fix the flaky integration tests in CI
```
The Devin CLI packages up the conversation context and your current git branch, then creates a cloud session that picks up where you left off. Track its progress from your terminal or in the [Devin web app](https://app.devin.ai).
Run `/handoff` without a task description and the cloud session continues from where you left off automatically.
## When to hand off
Hand a task off when it needs more than your local terminal, or when you want it to run in the background:
* **VM or server** — running a dev server, hitting endpoints, Docker builds
* **Browser** — screenshots, OAuth flows, end-to-end tests, scraping
* **CI/CD** — pipeline debugging, deployments, infrastructure changes
* **Long-running work** — migrations, batch jobs, large refactors
* **Parallel execution** — offload work to the cloud while you keep coding locally
## What carries over
The cloud session starts in a fresh VM, so the CLI includes everything it needs to pick up the thread:
* **Repo and branch** — so the cloud session clones the right repo and checks out the branch you're on.
* **Conversation context** — what you and Devin have been working on in the current session.
* **Uncommitted changes** — your work-in-progress diff carries over. Commit or stash anything you don't want sent.
Not using the Devin CLI? You can hand off from Claude Code, Codex, Cursor, or any coding agent — and from plain shell scripts — with the open-source [Devin Handoff](https://github.com/club-cog/devin-handoff) plugin. See [Hand off to Devin](/work-with-devin/devin-handoff) for setup and usage across every agent.
## Related resources
Hand off from any coding agent, not just the Devin CLI
Source, install guides, and the full script reference
# Quickstart
Source: https://docs.devinenterprise.com/cli/index
Get up and running in 2 minutes with Devin CLI, a local command-line coding agent with deep Devin Cloud integration.
```bash theme={null}
curl -fsSL https://cli.devin.ai/install.sh | bash
```
On macOS, install Devin CLI with [Homebrew](https://brew.sh):
```bash theme={null}
brew install --cask devin-cli
```
To upgrade to the latest version later, run:
```bash theme={null}
brew upgrade --cask devin-cli
```
Download and run the installer:
* [x86\_64 (most Windows PCs)](https://static.devin.ai/cli/devin-updater-x86_64-pc-windows.exe)
* [ARM64 (Windows on ARM)](https://static.devin.ai/cli/devin-updater-aarch64-pc-windows.exe)
Alternatively, open **PowerShell** and run:
```powershell theme={null}
irm https://static.devin.ai/cli/setup.ps1 | iex
```
`irm` and `iex` are PowerShell commands. Do not run this in Git Bash or CMD — it will fail with "command not found". Use PowerShell for installation only.
After installing, you can use Devin CLI from **PowerShell**, **Windows Terminal**, or **Git Bash**.
Devin CLI is bundled with **Devin Desktop**. This installation method is available for **Legacy Windsurf Enterprise** and **Devin Enterprise** plans.
**Admin setup:** For the Devin Desktop-bundled install, an admin must first enable the install option in Devin CLI team settings by toggling on **Show "Install Devin CLI" in the Devin Desktop Command Palette**.
**User installation:**
1. Open Devin Desktop
2. Open the Command Palette with Cmd+Shift+P
(macOS) or Ctrl+Shift+P
(Windows/Linux)
3. Search for and run **Install Devin CLI**
This adds the `devin` binary to your PATH so you can use it from any terminal.
That's it! After you restart your terminal, enter a project directory and type `devin` to activate Devin CLI. Also try preloading the session with a prompt for automation:
```bash theme={null}
devin -- check out this code and suggest a feasible, helpful feature
```
You're ready to go. For must-know tips, see [Essential Commands](/cli/essential-commands).
## What's next?
Devin CLI can implement new features, fix bugs, review code, answer questions, automate tasks, and more.
Must-know commands and slash commands
Choose the right model for your task
Connect MCP servers and skills
Explore all commands and flags
***
## Devin CLI vs. Devin
Devin CLI and [Devin](/get-started/devin-intro) are separate tools designed for different workflows.
**Devin CLI** is a local coding agent that runs directly in your terminal. It works with your local files and environment, giving you fast, interactive assistance right where you code.
**Devin** is our cloud-based AI software engineer that runs in a virtual machine. It includes features like Playbooks, Secrets, Knowledge, and other capabilities that are not available in Devin CLI.
Devin CLI does not yet support Knowledge, Playbooks, or Secrets from your Devin account. We're actively working on adding support for each of these and plan to roll them out soon.
# Models
Source: https://docs.devinenterprise.com/cli/models
Available models and how to configure them
Devin CLI supports multiple AI models. You can choose the best model for your task to optimize for maximum capability, speed, or cost efficiency.
For most users, we recommend **Adaptive** — our intelligent model router that automatically selects the best model for each task, delivering the right level of intelligence for every prompt.
***
## Available Models
Models release frequently. We typically support the latest and greatest models from **Anthropic**, **OpenAI**, **Google**, and **Cognition** within minutes of their launch. We also support a number of **leading open source models** like **DeepSeek**, **Kimi**, and **GLM**.
To stay up-to-date on model releases, consider following the [**Cognition** X account](http://x.com/cognition).
Short names like `opus`, `sonnet`, `swe`, `codex`, and `gemini` always resolve to the latest version in that model family.
### Reasoning / Thinking Levels
Some models support configurable reasoning levels, which control how much compute the model spends "thinking" before responding. You can cycle the thinking level with `Alt+T` (macOS: `Opt+T`) during a session.
***
## Setting the Model
```bash theme={null}
devin --model opus -- refactor this module
devin --model sonnet -- explain this code
```
Switch models during a session:
```text theme={null}
/model opus
/model sonnet
/model codex
```
Run `/model` with no argument to open the model selector.
Set a default in `~/.config/devin/config.json` (on Windows, `%APPDATA%\devin\config.json`):
```json theme={null}
{
"agent": {
"model": "swe-1-6-fast"
}
}
```
***
## Model Selection Tips
The correct choice of language model varies wildly from person-to-person and task-to-task. Many engineers working on the same project are convinced that their model is the best for the task, despite using different models. The fact of the matter is, AI can perform differently depending on your personal usage and writing style!
**As such, we strongly recommend trying multiple models to see which one you prefer.** At minimum we recommend trying `swe`, `gpt`, and `opus`. We find that the vast majority of use-cases can be covered by these three.
Use `opus` or `gpt` for multi-file refactors, architecture changes, and tasks requiring deep reasoning.
Use `swe` (fast) for straightforward edits, bug fixes, and questions. It's both fast and cheap at a reasonable level of intelligence.
Enterprise teams can restrict which models are available through [Team Settings](/cli/enterprise/team-settings).
# Sandbox
Source: https://docs.devinenterprise.com/cli/sandbox
OS-level isolation for Devin CLI sessions: how the sandbox works, network filtering, and enterprise enforcement.
The `--sandbox` flag runs the CLI with OS-level isolation, enforcing writable paths and `deny` rules at the operating-system level and optionally restricting network traffic.
## How the sandbox works
When the sandbox is active:
* **Writable paths** are derived from granted `Write(...)` permission scopes plus the workspace directory; everything else is read-only
* **Readable paths** are everything except paths covered by `Read(...)` rules in the `deny` list, which are hidden from sandboxed commands entirely
* `Write(...)` scopes granted mid-session dynamically expand the sandbox for subsequent commands. Mid-session `Read(...)` approvals affect only the agent's own tools — they cannot reveal a path hidden by a `Read(...)` deny rule, which stays hidden for the whole session
If sandbox resolution fails (e.g., the sandboxing tools are unavailable on the user's platform), the CLI will **refuse to start** rather than running unsandboxed. This fail-closed behavior applies whether sandbox was enabled by a [team setting](/cli/enterprise/team-settings#sandbox-enforcement) or by the user passing `--sandbox` directly, ensuring the security intent is never silently bypassed.
Common causes of sandbox resolution failure:
* **Windows**: OS-level sandboxing is not currently supported on Windows. Sessions on Windows will hard-fail when `--sandbox` is passed or when sandbox enforcement is **Required**, including when the CLI runs as an ACP server inside an IDE (e.g., Devin Desktop).
* **Linux**: Sandboxing requires `bubblewrap` (`bwrap`) and `socat` to be installed. Sessions hard-fail with installation instructions when these are missing.
* **Permission scope errors**: Invalid paths in permission scopes that can't be resolved.
## Network filtering
Sandbox network filtering is currently unstable. If you need this feature, please reach out to your account representative for stability timelines.
Configure domain-level network filtering for the sandbox in the [`sandbox` section of your config file](/cli/reference/configuration/config-file#sandbox) (user config only). When `--sandbox` is active and domain filtering is configured, a managed network proxy starts on loopback and the sandbox restricts all child traffic to route through it.
| Option | Type | Default | Description |
| ----------------- | --------- | -------- | ------------------------------------------------------------------------------------------------------------- |
| `allowed_domains` | string\[] | `[]` | Domain patterns allowed through the proxy. When non-empty, only matching domains are allowed (allowlist mode) |
| `denied_domains` | string\[] | `[]` | Domain patterns always blocked. Deny rules take precedence over allow rules |
| `network_mode` | string | `"full"` | `"full"` allows all HTTP methods; `"limited"` allows only GET/HEAD/OPTIONS |
**Domain pattern syntax:**
| Pattern | Matches |
| ---------------- | ----------------------------- |
| `example.com` | Exact match only |
| `*.example.com` | Any subdomain (not the apex) |
| `**.example.com` | Apex domain and any subdomain |
**Example:**
```json theme={null}
{
"sandbox": {
"allowed_domains": [
"github.com",
"**.npmjs.org",
"**.crates.io",
"**.pypi.org"
],
"denied_domains": ["evil.example.com"],
"network_mode": "full"
}
}
```
Domain filtering applies when the sandbox is active (`--sandbox`). Without `--sandbox`, the sandbox section is ignored.
## Excluded commands
Sometimes a specific command needs to run *outside* the sandbox — for example `git` commands that must access credentials or hooks the sandbox blocks. The `sandbox.excluded` config section lets you exclude matching commands from sandbox isolation using the same `Exec(...)` rule syntax as [permissions](/cli/reference/permissions):
| Option | Type | Description |
| ---------------- | --------- | -------------------------------------------------------------------------- |
| `excluded.allow` | string\[] | Matching commands run outside the sandbox automatically |
| `excluded.ask` | string\[] | Matching commands run outside the sandbox after the user approves a prompt |
| `excluded.deny` | string\[] | Matching commands are never excluded — they always stay inside the sandbox |
**Example:**
```json theme={null}
{
"sandbox": {
"excluded": {
"allow": ["Exec(git status *)"],
"ask": ["Exec(git push *)"],
"deny": ["Exec(git tag *)"]
}
}
}
```
**Rule resolution:** for each command, the most specific matching rule wins within a source (e.g., `Exec(git push *)` beats `Exec(git *)`), and when both user config and [team settings](#enterprise-excluded-commands) match, the more restrictive verdict wins (`deny` > `ask` > `allow`). Commands with no matching rule — including when `sandbox.excluded` is not configured at all — always run inside the sandbox.
* Only `Exec(...)` rules are supported in `sandbox.excluded`; any other rule type (e.g., `Read(...)`, `Write(...)`) is ignored with a warning.
* Exclusion is fail-closed: if a command can't be safely resolved (e.g., it can't be parsed), it stays inside the sandbox.
* Exclusions apply to the default per-command exec path. Commands run through a persistent PTY shell (interactive sessions, or when `pty_for_noninteractive_exec` is enabled) always stay inside the sandbox.
## Enterprise enforcement
Enterprise admins can control sandbox behavior for their entire organization via [Team Settings](/cli/enterprise/team-settings#sandbox-enforcement).
### Sandbox enforcement mode
Set the enforcement level for the `--sandbox` flag across your organization:
* **Optional** (default) — Users choose whether to pass `--sandbox`. No enforcement.
* **Required** — The `--sandbox` flag is forced on for all users, even if they don't pass it on the command line. All CLI sessions run with OS-level file system sandboxing that enforces writable paths and `Read(...)` deny rules.
A future **Strict** mode may lock down sandbox configuration entirely, preventing users from modifying sandbox settings.
Ensure all target machines are provisioned before setting sandbox enforcement mode to **Required** across your organization. If any users are on Windows, they will be unable to run the CLI until OS-level sandboxing is supported on Windows or the policy is relaxed to **Optional**.
### Enterprise domain filtering
Admins can also configure organization-wide domain allowlists and denylists:
* **Domain allowlist** — When set, **only** the domains in this list are reachable through the sandbox network proxy. This list is **authoritative**: it completely replaces any user-configured `allowed_domains`. Users cannot add additional domains to bypass admin restrictions.
* **Domain denylist** — Domains that are always blocked. Enterprise denied domains are **additive**: they are merged with the user's local `denied_domains`, making the combined list more restrictive.
**How enterprise and user domain lists interact:**
| Scenario | Enterprise config | User config | Effective result |
| -------------------- | --------------------------------- | --------------------------------- | ------------------------------------------------------------ |
| Admin sets allowlist | `allowed_domains: ["github.com"]` | `allowed_domains: ["npmjs.org"]` | Only `github.com` is allowed (enterprise replaces user list) |
| Admin sets denylist | `denied_domains: ["evil.com"]` | `denied_domains: ["risky.io"]` | Both `evil.com` and `risky.io` are blocked (merged) |
| No admin allowlist | `allowed_domains: []` | `allowed_domains: ["github.com"]` | User's allowlist is used |
Because the user's local `denied_domains` are preserved and merged additively, a user could deny a domain that appears in the enterprise allowlist. This is intentional: the combined effect is always more restrictive, never less. If this causes access issues, the user should remove the conflicting entry from their local config.
### Enterprise excluded commands
Admins can also set organization-wide [excluded command](#excluded-commands) rules in team settings:
* **Excluded allow / ask** — `Exec(...)` rules for commands that may run outside the sandbox across the organization, automatically or after a prompt.
* **Excluded deny** — `Exec(...)` rules for commands that must never run outside the sandbox. A team `deny` overrides any user-level `allow` or `ask` for matching commands, so users cannot exclude commands their admins have locked down.
Team and user rules are resolved together: the most specific matching rule wins within each source, and the more restrictive verdict wins across sources (`deny` > `ask` > `allow`).
**Example: lock down all exclusions except `gh`.** A wildcard `deny` with an `allow` carve-out keeps every command inside the sandbox except `gh`, regardless of what users configure locally. These values go into the team-settings excluded-commands configuration (not the user config file, so there is no enclosing `sandbox` key):
```json theme={null}
{
"excluded": {
"deny": ["Exec(**)"],
"allow": ["Exec(gh *)"]
}
}
```
Because the more specific `Exec(gh *)` rule beats the wildcard `Exec(**)`, `gh` commands run outside the sandbox while everything else stays inside — and the team-level wildcard `deny` overrides any user-level `allow` or `ask` rules for other commands.
## Further reading
* [Team Settings](/cli/enterprise/team-settings#sandbox-enforcement) — enterprise sandbox enforcement and domain filtering
* [Config file reference](/cli/reference/configuration/config-file#sandbox) — the user-level `sandbox` config section
* [Permissions](/cli/reference/permissions) — permission scopes that drive sandbox writable paths and deny rules
# Subagents
Source: https://docs.devinenterprise.com/cli/subagents
Delegate tasks to independent subagents that work in the foreground or background
Subagents let the main agent spawn independent workers to handle subtasks. A subagent shares tools and codebase context with the parent, but operates in its own conversation chain -- it does not inherit the parent's conversation history. This is useful for tasks that benefit from focused, independent work -- like exploring a codebase, running tests, or implementing a feature in parallel.
You can ask the agent to use subagents explicitly (e.g. "research how auth works in a subagent"), or the agent may decide to delegate on its own when it determines a task would benefit from independent work.
In our measurements, **subagents** **both** **improve overall coding performance** **and** **reduce cost**.
***
## How Subagents Work
When the agent spawns a subagent, it selects one of the available **subagent profiles** and chooses whether the subagent should run in the foreground or background. Subagents can run in two modes:
Runs inline in your session. The parent agent pauses and waits for the subagent to finish before continuing. You can approve or deny tool calls as they come up.
Runs in parallel while the parent agent continues working. The parent is automatically notified when the subagent completes. Unapproved tools are automatically denied.
You do not see the subagent's raw output directly. When a subagent finishes, the parent agent reads the result and summarizes the key findings and actions for you.
### Subagent Cost
Subagents run as their own agent sessions, each with its own context window and inference calls, so they consume cost independently of the parent. The parent's spend covers its own work; every subagent it spawns adds its own usage on top of that.
On prompt-based plans, each subagent consumes additional credits, just like a user message does. The number of credits depends on the model the subagent uses, so tasks that spawn multiple subagents (or [nest](/cli/subagents#nesting-depth) them) consume more credits.
Because cost scales with the number of subagents, tasks that fan out into many subagents (or [nest](#nesting-depth) them) cost more. Use subagents deliberately when the parallelism or focused context is worth the additional spend.
***
## Which Model Does a Subagent Use?
Subagents do not all run on the model you picked in the model picker. Each profile decides where its model comes from:
| Profile | Model used | Effect on quota / credits |
| ------------------ | ------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------- |
| `subagent_explore` | The **default subagent model** — a fast, cheap model (SWE-1.6 by default) | Cheap: SWE-1.6 usage is billed at SWE rates, not at your primary model's rate |
| `subagent_general` | **The same model as the parent agent** — whatever you selected in the model picker (e.g. Claude Opus, GPT-5) | Same rate as the parent: a general subagent costs like a full extra session on your selected model |
| Custom subagents | The `model` field in the definition file if set, otherwise the **default subagent model** | Depends on the model you pin |
`subagent_general` inherits the parent's model. If you are running a premium model, every general subagent runs on that premium model too, with its own context window and inference calls — so a task that fans out into several general subagents multiplies your spend. Ask for an explore subagent (or a [custom subagent](#custom-subagents) with a cheaper `model:` pinned) when the work is research rather than code changes.
The **default subagent model** is not a fixed model name — it resolves through a router at spawn time, and an admin can override it (see below). With the default **Subagent router** setting it resolves to SWE-1.6 (a faster or slower SWE-1.6 variant depending on your plan tier).
The CLI does not currently label which model a running subagent is using in the subagent panel.
### Influencing the Model
There is no way to name a model for a subagent in a prompt — the `run_subagent` tool takes a *profile*, not a model. You have two levers:
1. **Ask for a profile in natural language.** Requesting an explore subagent ("research how auth works in an explore subagent") keeps the work on the cheap default subagent model. Asking for code changes gets you `subagent_general`, which runs on your selected model.
2. **Pin a model in a [custom subagent](#custom-subagents) profile.** `model:` in the definition file is the only way to run a *write-capable* subagent on a model other than the parent's. A [skill](/cli/extensibility/skills) that runs in a subagent can also set `model:` in its frontmatter to override the profile's model.
### Enterprise Controls
Administrators can govern which model subagents use — and whether subagents run at all — through the **Default subagent model** setting in the org/enterprise settings. This setting controls the model for `subagent_explore` and for custom subagents that don't pin a `model:` — it does not change `subagent_general`, which always follows the parent agent's model.
It has three choices:
| Option | Behavior |
| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| **Subagent router (default)** | The default subagent model is chosen by a router at spawn time. Today it resolves to SWE-1.6 (the exact variant depends on your plan tier). |
| **A specific model** | Pins the default subagent model to the selected model, for every subagent that doesn't run on the parent's model. |
| **None** | Disables subagents entirely — Devin will not spawn any subagents. |
***
## Enabling and Disabling Subagents
Subagents are on by default. Set `subagents_enabled` to `false` in your [config file](/cli/reference/configuration/config-file#subagents_enabled) to remove the `run_subagent` and `read_subagent` tools so the agent does everything itself:
```json theme={null}
// ~/.config/devin/config.json
{
"subagents_enabled": false
}
```
The change applies live — a running session picks it up without restarting. In Devin Desktop, the same capability is the **Subagents (Preview)** toggle in settings.
Organization policy wins: if an admin has set **Default subagent model** to **None**, subagents stay disabled no matter what this setting says.
***
## Subagent Profiles
Each subagent runs with a specific profile that determines its capabilities. There are two built-in profiles:
| Profile | Description | Tool Access | Model |
| ------------------ | -------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------- |
| `subagent_explore` | Read-only codebase exploration and research | Read-only codebase tools plus web search; cannot edit files or fetch arbitrary URLs (regardless of foreground or background) | Default subagent model (SWE-1.6 by default) |
| `subagent_general` | General-purpose tasks including code changes | Full tool access (foreground) or pre-approved tools only (background) | Same model as the parent agent |
The agent automatically chooses the appropriate profile based on the task. Explore subagents are ideal for research and understanding, while general subagents can make changes. See [Which Model Does a Subagent Use?](#which-model-does-a-subagent-use) for how each profile picks its model — the two profiles do **not** run on the same model.
You can also define your own custom subagent profiles — see [Custom Subagents](#custom-subagents) below.
***
## Tool Permissions
How tool permissions work depends on whether the subagent is running in the foreground or background:
* **Foreground subagents** behave like the main agent -- you are prompted to approve or deny tool calls as usual. The prompt names the subagent that requested the action, so you know who is asking.
* **Background subagents** inherit any tool permissions you have already granted during the current session. Any tool that has not been pre-approved is automatically denied. Background subagents cannot prompt you for new permissions.
If a background subagent fails because a required tool was denied, you can resume it in the foreground to approve the necessary permissions. See [Resuming Subagents](#resuming-subagents) below.
***
## Monitoring Subagents
### Subagent Indicator
When background subagents are running, an indicator appears below the input area showing their status. You can navigate to the indicator by pressing ↓ from the input area, then press Enter to open the subagent panel.
When a foreground subagent is running, the spinner displays **"Subagent running · Ctrl+B to run in background"**.
### Subagent Panel
The subagent panel lets you view and manage all active and completed subagents. It shows each subagent's profile, title, status, elapsed time, and tool call count. Subagent activity survives a session reload, so the panel still reflects your subagents after resuming.
***
## Foreground / Background Switching
You can move subagents between foreground and background while they're running:
* **Background a foreground subagent:** Press Ctrl+B while a foreground subagent is running. The subagent continues working in the background, and the parent agent resumes.
* **Foreground a background subagent:** Open the subagent panel and press f on a running background subagent. The subagent's output will display inline.
When you move a subagent to the background, the parent agent's tool call has already returned, so the parent continues independently. The subagent's result won't feed back into the parent's current pipeline, but you'll be notified when it completes.
***
## Interrupting a Turn
Interrupting the agent does not kill its subagents. Running subagents **park** with their state intact and resume on your next message, so an interruption to redirect the parent agent doesn't throw away work in flight.
***
## Cancelling Subagents
You can cancel a running subagent in two ways:
1. **From the subagent panel:** Open the panel and press x on a running subagent.
2. **Foreground subagent:** Press Ctrl+C or Esc to cancel the currently running foreground subagent.
***
## Resuming Subagents
Cancelled, failed, or completed subagents can be resumed with a new prompt. You can ask the agent to resume a subagent, and it will continue where it left off. Resumed subagents always run in the **foreground**, so you can approve any tool calls that were previously denied.
This is especially useful when:
* A background subagent failed because a required tool was denied -- resume it in the foreground to grant the necessary permissions.
* A subagent completed but you want it to do additional follow-up work based on its findings.
* A subagent was cancelled prematurely and you want it to continue.
***
## Nesting Depth
By default, subagents cannot spawn their own subagents — only the root agent can. Subagent tools (`run_subagent` and `read_subagent`) are disabled inside a subagent to prevent unbounded nesting.
However, **custom subagent profiles** can opt in to nested spawning by setting the `max-nesting` field in their frontmatter. This value overrides the default maximum depth, allowing subagents to spawn children as long as the tree stays within that limit.
For example, `max-nesting: 3` allows the following chain:
```
Root agent (depth 0)
└── Custom subagent (depth 1) — can spawn children
└── Child subagent (depth 2) — can spawn children
└── Grandchild subagent (depth 3) — cannot spawn (depth limit reached)
```
Nested subagents can increase cost significantly. Each level of nesting spawns additional agents with their own context windows and inference calls. Use this feature deliberately.
***
## Custom Subagents
Custom subagents are **experimental**. The format, behavior, and configuration options may change in future releases.
Beyond the built-in `subagent_explore` and `subagent_general` profiles, you can define your own custom subagent profiles. Custom subagents let you create specialized workers with their own system prompts, tool restrictions, and model overrides — tailored to specific tasks in your workflow. This is also the way to get a write-capable subagent that does **not** run on your (possibly expensive) primary model: give it a `model:` and the tools it needs.
### Creating a Custom Subagent
Custom subagents are defined as markdown files under `agents/`, using either layout:
* **Flat file** — `agents/.md` (the same convention used by Claude Code, Cursor, and other tools). The file name (without `.md`) becomes the profile's identifier.
* **Directory** — `agents//AGENT.md`. The directory name becomes the profile's identifier. `AGENTS.md`, `agent.md`, and `agents.md` are also accepted as the file name (if multiple are present, `AGENT.md` takes precedence, then `AGENTS.md`, `agent.md`, `agents.md`).
In both layouts, a `name:` in the frontmatter overrides the identifier derived from the path.
```text theme={null}
.devin/agents/
├── reviewer.md
└── researcher/
└── AGENT.md
```
Also supported:
```text theme={null}
.agents/agents/
├── reviewer.md
└── researcher/
└── AGENT.md
```
```text theme={null}
# Linux/macOS
~/.config/devin/agents/
├── reviewer.md
└── researcher/
└── AGENT.md
# Windows
%APPDATA%\devin\agents\
├── reviewer.md
└── researcher\
└── AGENT.md
```
### Definition File Format
A subagent definition file uses the same YAML frontmatter as skills, followed by the subagent's system prompt:
```markdown theme={null}
---
name: reviewer
description: Reviews code changes for correctness and style
model: sonnet
allowed-tools:
- read
- grep
- glob
- exec
---
You are a code review subagent. Your job is to review code changes
thoroughly and report findings back to the parent agent.
Focus on:
1. Correctness — logic errors, edge cases, off-by-one mistakes
2. Security — potential vulnerabilities
3. Style — consistency with the rest of the codebase
4. Performance — obvious inefficiencies
Always cite specific file paths and line numbers in your findings.
```
### Frontmatter Fields
| Field | Type | Default | Description |
| --------------- | ------- | ------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------- |
| `name` | string | file or directory name | Identifier for the profile (must not conflict with built-in profiles) |
| `description` | string | none | Shown to the agent when selecting a profile |
| `model` | string | default subagent model (SWE-1.6 by default) — **not** the parent's model | Override the model used by this subagent |
| `allowed-tools` | list | all tools | Restrict which tools the subagent can use. Cannot grant `ask_user_question`, which is always withheld from subagents. |
| `max-nesting` | integer | none | Override the maximum nesting depth, allowing this subagent to spawn its own subagents |
### How Custom Subagents Are Used
Once defined, custom subagent profiles appear alongside the built-in ones. The agent sees a description of each available profile and chooses the most appropriate one when spawning a subagent. You can also ask the agent to use a specific profile by name (e.g., "review this code using the reviewer subagent").
Custom subagent profiles that conflict with a built-in profile name (e.g., `subagent_explore`, `subagent_general`) are skipped with a warning.
### Importing From Other Tools
Custom subagents are also imported from Claude Code's agent format:
| Source | File Pattern |
| --------------------- | ------------------------------------------ |
| `.claude/agents/*.md` | Each `.md` file becomes a subagent profile |
Claude Code agent files use `tools` instead of `allowed-tools` in their frontmatter. Both formats are supported automatically.
### Examples
#### Read-Only Research Agent
```markdown theme={null}
---
name: researcher
description: Deep codebase research and architecture analysis
model: sonnet
allowed-tools:
- read
- grep
- glob
---
You are a research subagent specializing in codebase exploration.
Your job is to thoroughly investigate a topic and report back with:
- Relevant files and their purposes
- Architecture patterns and dependencies
- Code flow traces with specific line references
Be exhaustive — search broadly and follow references.
```
#### Test Runner Agent
```markdown theme={null}
---
name: test-runner
description: Runs tests and reports results
allowed-tools:
- read
- grep
- glob
- exec
---
You are a test runner subagent. Run the relevant test suites and report:
- Which tests passed and failed
- Failure messages and stack traces
- Suggestions for fixing failures
```
# Troubleshooting
Source: https://docs.devinenterprise.com/cli/troubleshooting
Common issues and how to fix them
## Installation Issues
If the install script fails to download:
1. Check your internet connection
2. Verify curl is installed: `which curl`
3. Try with verbose output: `curl -fsSL -v https://cli.devin.ai/install.sh | bash`
If you're behind a corporate proxy, you may need to configure proxy settings:
```bash theme={null}
export https_proxy=http://your-proxy:port
curl -fsSL https://cli.devin.ai/install.sh | bash
```
If the PowerShell install script fails:
1. Check your internet connection
2. Ensure you are running PowerShell as a regular user (not as Administrator unless necessary)
3. If you see an execution policy error, try:
```powershell theme={null}
Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned
irm https://static.devin.ai/cli/setup.ps1 | iex
```
4. If you're behind a corporate proxy, configure proxy settings in PowerShell before running the install command
As an alternative to the PowerShell script, you can download and run the standalone installer directly:
* [x86\_64](https://static.devin.ai/cli/devin-updater-x86_64-pc-windows.exe)
* [ARM64](https://static.devin.ai/cli/devin-updater-aarch64-pc-windows.exe)
The installer needs write access to install the binary. If you see permission errors:
1. Check the install location has write permissions
2. Do not run the installer with `sudo` — this can cause ownership issues
3. If installing to a system directory, ensure your user has appropriate permissions
If the install completes but `devin` isn't found:
**macOS / Linux / WSL:**
1. Restart your terminal or run `source ~/.bashrc` (or `~/.zshrc`)
2. Check if the binary location is in your PATH: `echo $PATH`
3. Verify the binary exists: `ls -la ~/.local/bin/devin` (or the install location shown during setup)
**Windows:**
1. Restart your PowerShell session
2. Check if the binary location is in your PATH: `$env:PATH -split ';'`
3. Verify the binary exists in the install location shown during setup
`irm` and `iex` are PowerShell aliases. If you see this error, you're running the install command in Git Bash or CMD instead of PowerShell.
**Fix:** Open **PowerShell** and run the install command there:
```powershell theme={null}
irm https://static.devin.ai/cli/setup.ps1 | iex
```
Alternatively, from Git Bash or CMD you can invoke PowerShell explicitly:
```bash theme={null}
powershell -Command "irm https://cli.devin.ai/install.ps1 | iex"
```
After installation, you can use Devin CLI from **PowerShell**, **Windows Terminal**, or **Git Bash**.
***
## Authentication Issues
If browser-based login doesn't work:
1. Try the manual token flow for remote/SSH sessions:
```bash theme={null}
devin auth login --force-manual-token-flow
```
2. Check that your browser can reach the authentication URL
3. Verify your enterprise account has Devin CLI access enabled
If you see authorization errors after logging in:
1. Verify your account has the correct permission needed to access Devin CLI. You may need to ask your admin. For enterprises, see [Devin Auth](/cli/enterprise/devin-auth#configuring-access) or [Legacy Windsurf Auth](/cli/enterprise/windsurf-auth#prerequisites) on how to configure access.
2. Try logging out and back in: `devin auth logout && devin auth login`
3. Check your authentication status: `devin auth status`
Devin CLI API tokens do not expire by default. If a stored token has been revoked or is no longer accepted, remove it before logging in again:
```bash theme={null}
devin auth logout && devin auth login
```
to replace your stored credentials.
***
## Network & Proxy Issues
The CLI routes its own outbound HTTPS traffic (authentication, updates, model API calls, MCP servers) through a proxy when one is configured. There are two ways to set it:
**Environment variables** — the default `system` proxy mode respects these:
```bash theme={null}
export HTTPS_PROXY=http://proxy.corp.example.com:8080
export HTTP_PROXY=http://proxy.corp.example.com:8080
export ALL_PROXY=socks5://proxy.corp.example.com:1080 # optional, SOCKS5
export NO_PROXY=localhost,127.0.0.1,.internal.corp # hosts to bypass
```
**`config.json`** — applies regardless of environment:
```json theme={null}
{
"proxy": {
"mode": "manual",
"url": "http://proxy.corp.example.com:8080",
"no_proxy": "localhost,127.0.0.1,.internal.corp"
}
}
```
See the [`proxy` configuration reference](/cli/reference/configuration/config-file#proxy) for all options. On macOS and Windows, `system` mode also honors platform-native PAC (Proxy Auto-Configuration) settings.
If your proxy performs TLS inspection, the CLI uses your operating system's certificate store, so install the proxy's root CA at the OS level (Keychain on macOS, the Windows certificate store, or your distribution's CA bundle on Linux).
To get full visibility into the request lifecycle (DNS, connection pooling, TLS handshake, headers, redirects, and retries), raise the log level with `RUST_LOG` and mirror logs to your terminal with `CHISEL_LOG_STDOUT`:
```bash theme={null}
RUST_LOG="chisel=trace,windsurf_api_client=trace,connect_rpc=trace,reqwest=trace,hyper=trace,hyper_util=trace,rustls=trace" \
CHISEL_LOG_STDOUT=1 \
devin auth login
```
What each target adds:
* `chisel`, `windsurf_api_client`, `connect_rpc` — the CLI's own request and authentication logging
* `reqwest=trace` — high-level request/response and redirect handling
* `hyper=trace` / `hyper_util=trace` — connection establishment, pooling, and HTTP/1.1 & HTTP/2 framing
* `rustls=trace` — TLS handshake details (useful for proxy and certificate problems)
Use `CHISEL_LOG_STDERR=1` instead of `CHISEL_LOG_STDOUT=1` if you don't want logs interleaved with command output. (Stdout logging is suppressed automatically in the interactive REPL and ACP mode to avoid corrupting their output.)
Logs are also always written to a per-run log file under the CLI's data directory, regardless of these env vars:
* **macOS / Linux:** `~/.local/share/devin/cli/logs/devin__.log`
* **Windows:** `%APPDATA%\devin\cli\logs\devin__.log`
Log files from finished processes that have been untouched for 48 hours are gzipped at startup to keep the directory small, so older logs are `.log.gz`. Search them with `zgrep` (or `rg -z`) and read them with `zless`:
```bash theme={null}
zgrep "error" ~/.local/share/devin/cli/logs/*.log.gz
rg -z "error" ~/.local/share/devin/cli/logs/
```
Trace-level logs can include sensitive data such as `Authorization` headers and tokens. Scrub log output before sharing it.
`RUST_LOG` exposes the request lifecycle but not full payloads. To capture complete request and response bodies, route the CLI through an intercepting proxy such as [mitmproxy](https://mitmproxy.org/):
```bash theme={null}
# Terminal 1 — start the intercepting proxy:
mitmproxy --listen-port 8080
# Terminal 2 — point the CLI at it:
export HTTPS_PROXY=http://127.0.0.1:8080
devin auth login
```
Because the CLI trusts the OS certificate store, install mitmproxy's CA certificate (`~/.mitmproxy/mitmproxy-ca-cert.pem`) into your system trust store first — otherwise the TLS connection to the proxy will fail.
***
## Runtime Issues
If you see errors about a model not being available:
1. Check if your enterprise restricts available models in [Team Settings](/cli/enterprise/team-settings)
2. Verify the model name is correct — use `/model` to see available options
3. Try a different model: `devin --model sonnet -- your prompt`
If you hit usage limits:
1. Wait a few minutes before retrying
2. Check your organization's usage dashboard for quota status
3. Contact your admin if you need higher limits
Commands the agent runs inherit your login shell's environment on macOS and Linux, so tools installed through `nvm`, `pyenv`, `rbenv`, `direnv`, or `mise` are normally available. If the agent reports "command not found" for something that works in your terminal:
1. Confirm the tool is on the `PATH` exported by your shell profile, not only by an interactive-only alias or function
2. Restart Devin — the environment is snapshotted once at session startup, so profile changes made mid-session are not picked up
3. On Windows, the login-shell snapshot does not apply; make sure the tool is on the system `PATH`
At session startup, Devin runs `$SHELL` as an interactive login shell once and reads exported variables from your shell configuration, such as `.bash_profile`, `.bashrc`, `.zshrc`, `.zprofile`, or your fish config.
If the agent stops responding:
1. Press `Ctrl+C` to interrupt the current operation
2. Try `/clear` to start a fresh session
3. Check your network connection
4. Restart Devin CLI
***
## MCP Server Issues
If an MCP server fails to start:
1. Verify the command works outside Devin CLI:
```bash theme={null}
npx -y @modelcontextprotocol/server-github
```
2. Check that all required environment variables are set
3. Look for error messages in the server output
If MCP tools don't show up:
1. The server may need a moment to initialize — wait a few seconds
2. Check that the server is configured correctly in your config file
3. Verify your enterprise allows MCP servers in [Team Settings](/cli/enterprise/team-settings)
MCP tools default to prompting for approval. To auto-approve specific tools, add them to your permissions config:
```json theme={null}
{
"permissions": {
"allow": ["mcp__github__list_issues"]
}
}
```
***
## Getting Help
If you're still experiencing issues:
* **Email support:** [support@cognition.ai](mailto:support@cognition.ai)
* **Submit a bug report:** Use the `/bug` command inside Devin CLI to report issues directly to the Devin CLI developers
* **Check for updates:** Run `devin update` to ensure you're on the latest version
# Devin Outposts orchestration guide
Source: https://docs.devinenterprise.com/cloud/outposts/orchestration
Build a Devin Outposts orchestrator for your own infrastructure: watch the queue, claim sessions, provision machines, and run workers automatically.
An orchestrator watches the outposts API for sessions waiting on an outpost, provisions a VM or container for each one, and starts the worker inside it. This page describes the orchestration loop: polling the queue, claiming sessions, running workers, and tearing machines down.
If you just want to serve sessions from a machine you already have, start with the [quickstart](/cloud/outposts/quickstart) — no orchestrator is required. If you run on a supported platform, an [integration](/cloud/outposts/overview#integrations) may already implement this loop for you. For the full API and CLI surface, see the [reference](/cloud/outposts/reference).
Running on Kubernetes? [devin-outpost-k8s](https://github.com/CognitionAI/devin-outpost-k8s)
is an open-source operator that implements this loop for you: it watches the
queue, claims pending sessions, and runs each one as a worker pod on any
certified cluster (GKE, EKS, ...). Install it with its Helm chart instead of
building your own orchestrator.
## The core flow
### 1. Register an outpost
An outpost is a named queue of sessions served by many workers on your infrastructure (for example, `rhel`, `gpu-h200`, or `my-outpost`). Create one with `devin worker outpost create`:
```bash theme={null}
devin worker outpost create --platform --description "..."
```
Once registered, the outpost appears as a machine option in Devin Cloud (alongside Ubuntu, Windows, etc.) when starting a session. Sessions targeting it wait in its queue until a worker claims them.
In the fleet API, outposts are represented as `outposts` resources, scoped to
your account (shared across all of its organizations). See the
[outposts endpoints](/cloud/outposts/reference#outposts).
### 2. Watch the fleet API for waiting sessions
Your orchestrator lists pending sessions for the outposts it serves:
```bash theme={null}
curl -H "Authorization: Bearer $DEVIN_API_TOKEN" \
"https://api.devin.ai/opbeta/outposts/devins?outpost=&phase=pending"
```
Then it keeps its view current with a Server-Sent Events (SSE) watch, resuming from the list's final cursor:
```bash theme={null}
curl -N -H "Authorization: Bearer $DEVIN_API_TOKEN" \
"https://api.devin.ai/opbeta/outposts/devins?outpost=&watch=true&cursor="
```
This is the standard Kubernetes-style list-then-watch pattern: page through the list with the response cursor, then start a watch from where the list left off, persisting each event's cursor so you can reconnect without missing changes. Delivery is at-least-once, so upsert by `metadata.session_id` and tolerate duplicates. See [List queued sessions](/cloud/outposts/reference#list-queued-sessions) and [Watch for changes](/cloud/outposts/reference#watch-for-changes) for query parameters, response shapes, and full pagination semantics.
### 3. Claim before provisioning
Before starting a machine for a session, atomically claim it so no other worker picks it up. Pass an `acceptor_id` — a self-reported identity for your worker:
```bash theme={null}
curl -X POST -H "Authorization: Bearer $DEVIN_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{"acceptor_id": "worker-1"}' \
"https://api.devin.ai/opbeta/outposts/devins/{session_id}/claim"
```
Claims are atomic: if another worker claimed the session first, you get a `409`. Claiming promises that a worker will be ready within the server-assigned claim deadline (`status.claim_deadline`); expired claims return to the queue automatically. If provisioning fails, [release the claim](/cloud/outposts/reference#release-a-claim) so the session returns to the queue immediately.
### 4. Spawn a machine and run the worker
For each claimed session, provision a VM or container from your image. Inside it, run the worker from the directory you want the session to work in — its repositories live in that directory's `repos` subdirectory, i.e. `$(pwd)/repos/`:
```bash theme={null}
cd /path/to/worker/directory
devin worker start --session= --outpost= --acceptor-id=
```
Pass the same `--acceptor-id` you used for the API claim, and provide the token via `--token` or `DEVIN_OUTPOSTS_TOKEN` (see the [full flag list](/cloud/outposts/reference#devin-worker-start)). The worker connects out to Devin's cloud, marks the session ready, and begins executing tool calls.
### 5. Terminate the machine when the worker exits
When `devin worker start` exits, the session is over (or has been suspended). Terminate the VM or container. If your outpost is resumable, snapshot the machine before terminating so you can restore it if the session resumes.
Your orchestrator can track its claimed sessions and their states:
```bash theme={null}
curl -H "Authorization: Bearer $DEVIN_API_TOKEN" \
"https://api.devin.ai/opbeta/outposts/devins?phase=claimed&acceptor_id=worker-1"
```
Each entry reports a `status.session_status` of `pending`, `running`, `suspended`, or `terminated`.
## Centralization-free scheduling
Planning to run more than \~16 coordinators (workers or orchestrators
watching and claiming from an outpost)? Contact your account team first — larger
fleets amplify claim contention and queue read load, and we want to make
sure the outpost is provisioned for it.
You don't need a central scheduler to run a fleet. The queue API is designed so that many independent workers can serve the same outpost without talking to each other:
* **Claims are the only coordination primitive.** Every worker independently watches the queue and races to claim pending sessions. The claim is an atomic compare-and-swap on the server: exactly one worker wins, and every loser gets a `409` and simply moves on to the next pending session. Losing a claim race is normal operation, not an error.
* **Each worker has its own identity.** The `acceptor_id` scopes a worker's claims, renewals, and restart recovery to that worker alone. `devin worker start` generates and persists one automatically per machine, so a fleet needs no identity configuration. Never share an acceptor ID (or a copied worker data directory) across machines — colliding workers will steal each other's claims.
* **Failures self-heal.** If a worker dies after claiming, its claim expires at the claim deadline and the session returns to the queue for another worker to pick up. No fleet-level health tracking is required.
This means scaling out is just running the worker on more machines pointed at the same outpost: N machines serve N concurrent sessions, and the rest wait as pending.
## Building a custom orchestrator
Everything `devin worker start` does is available directly through the fleet API, so you can replace the CLI entirely: fetch the `devin-remote` binary from Devin's static distribution and launch it yourself with the documented environment. See [Remote binary distribution](/cloud/outposts/reference#remote-binary-distribution) and the [spawn contract](/cloud/outposts/reference#spawn-contract) in the reference.
# Devin Outposts: self-hosted infrastructure
Source: https://docs.devinenterprise.com/cloud/outposts/overview
Learn how Devin Outposts runs sessions on your own infrastructure, including self-hosted workers, networking, machine setup, and partner integrations.
Outposts lets you run Devin sessions inside infrastructure you control — your own VMs, containers, Kubernetes clusters, or even a Mac Mini on your desk. Devin's agent loop (inference and planning) continues to run in Devin's cloud, while all command execution, file edits, and repository access happen on machines you operate.
Use Outposts when you need:
* Sessions to run inside your network, next to internal services, registries, and secrets
* Custom hardware profiles (e.g. GPUs, large memory machines, specific OS images)
* Existing dev box, VM, or Kubernetes infrastructure to host Devin workloads
* Enterprise controls over network access, build outputs, and monitoring
## How it works
An **outpost** is a named queue of Devin sessions to be served on your own machines. Once you register an outpost (e.g. `gpu-h200` or `dev-boxes`), it appears as a machine option in Devin Cloud alongside Ubuntu, Windows, etc. — Cloud sessions started on an outpost wait in its queue until one of your machines picks them up.
Every machine that serves sessions from an outpost is a **worker**. To turn a machine into a worker, install the [Devin CLI](/work-with-devin/devin-cli) and run:
```bash theme={null}
devin worker start --outpost=
```
The worker opens an outbound connection to Devin's cloud and watches the outpost's queue. When a session is waiting, the worker claims it and executes its tool calls locally — every command, file edit, and repository operation runs on your machine. When the session ends, the worker goes back to watching the queue for the next session. Scaling out is just running the worker on more machines: N workers serve N concurrent sessions, and any further sessions wait in the queue until a worker becomes available.
Workers only need **outbound** HTTPS access. No inbound ports, public IPs, or VPN tunnels are required.
### Orchestration
Long-lived worker machines are the simplest setup, but with the Outposts API you can also write an **orchestrator**: software that watches the outpost's queue and, for each waiting session, spins up a fresh VM or container, starts the worker inside it, and tears the machine down when the session ends. See [Orchestration](/cloud/outposts/orchestration) to learn how, deploy [devin-outpost-k8s](https://github.com/CognitionAI/devin-outpost-k8s) — our open-source operator that runs the loop on any Kubernetes cluster — or run on a partner platform that already implements it for you (see [Integrations](#integrations)).
## Machine dependencies
Sessions execute directly on your machines, so the worker relies on tools you install there.
| Dependency | Required | Used for |
| --------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `git` (on `PATH`) | Yes | Cloning and all repository operations |
| `ffmpeg` (on `PATH`) | No | Devin's screen-recording features. Without it, sessions cannot record the screen. |
| Chrome or Chromium | No | Browser and computer-use features. The worker looks for Chrome in standard install locations by default; set `DEVIN_CHROME_PATH` in the worker's environment to the absolute path of the binary to override (e.g. `DEVIN_CHROME_PATH=/usr/bin/google-chrome`). Without it, browser tools are unavailable. |
| Graphical desktop / display | No | [Computer Use](/work-with-devin/computer-use#computer-use-on-outposts) (mouse, keyboard, screenshots). Linux machines need a running X session (`DISPLAY` set for the worker, e.g. Xvfb); macOS machines use the existing desktop session and need the **Screen Recording** (screenshots) and **Accessibility** (input) permissions granted to the worker. Without a display, computer actions return a clear error. |
| Passwordless `sudo` | No | Lets Devin install software it needs during a session (e.g. missing build tools or system packages). Only grant this when the machine is dedicated to Devin and recycled after each session — never on shared or long-lived machines. |
## Get started
Create an outpost and serve sessions from a single machine with `devin worker start` — no orchestrator required.
Scale to a fleet: poll the queue, claim sessions, provision machines, and run workers automatically.
The full surface area: CLI commands and flags, fleet API endpoints, binary distribution, and the spawn contract.
## Integrations
Partner platforms implement the orchestration loop for you — sessions run on their infrastructure with no worker to run and no orchestrator to build. Each partner documents its own setup:
| Platform | What you get | Docs |
| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------- |
| Namespace | First-class macOS environments on Apple silicon — with computer use, Devin builds, runs, and tests iOS apps end to end | [Devin Outposts on Namespace](https://namespace.so/docs/devbox/devin) |
| Modal | The same infrastructure you train and serve models on — reproduce failures and profile fixes on production hardware, scaling back to zero | [Devin Outposts on Modal](https://modal.com/docs/devin) |
| OpenShell | A sandbox for every session via the OpenShell runtime — from a single VM to a GPU cluster, built for secure and government environments | [Devin Outposts on NVIDIA OpenShell](https://github.com/NVIDIA/OpenShell#supported-agents) |
| Brev | GPU instances on NVIDIA Brev, deployed as a one-click Launchable | [Devin Outposts on NVIDIA Brev](https://brev.nvidia.com/launchable/deploy?launchableID=env-3Ge1ZXazlZQuJHfQed2od9IT8R5) |
| Daytona | Linux and Windows sandboxes that start in under 90 ms from snapshots — repos, dependencies, and toolchains already in place | [Devin Outposts on Daytona](https://www.daytona.io/docs/en/guides/devin/devin-outposts/) |
| E2B | Agent machines at any CPU/RAM configuration with sub-second starts — including access to your private cloud | [Devin Outposts on E2B](https://e2b.dev/docs/agents/devin-outposts) |
| Cloudflare | An isolated sandbox per session, with traffic flowing through customizable proxies and private connectivity to internal services — no VPN or public exposure | [Devin Outposts on Cloudflare](https://developers.cloudflare.com/sandbox/tutorials/devin-outposts/) |
## Limitations
* Devin Outposts is available on all Pro, Max, and Teams accounts.
* Devin Outposts is also available on [Dedicated Tenant deployments](/enterprise/deployment/overview) but is off by default, since a few Devin features behave differently when agents run on customer-managed infrastructure. Your account team can go over the details and enable it.
* Outposts shifts significant infrastructure and operational responsibility to the customer. Teams must secure and operate their remote development VMs at scale, including provisioning, isolation, access controls, capacity management, monitoring, and recovery. For security-conscious customers, we recommend [Dedicated Tenant (Dedicated SaaS)](/enterprise/deployment/overview), which provides a customer-isolated environment with security and orchestration managed by Cognition.
# Devin Outposts partner integrations
Source: https://docs.devinenterprise.com/cloud/outposts/partners
Connect Devin Outposts to your own infrastructure through a partner integration using PKCE, admin authorization, and secure server-to-server tokens.
Rough notes — this flow is in early development and the details below may
change.
Partner platforms (e.g. compute providers) can connect an outpost on behalf of a customer. The customer's Devin admin authorizes the connection in the browser; Devin then creates an outpost and a service user and hands the partner a token to run workers against the outpost.
The flow is an OAuth-light authorization-code exchange with [PKCE](https://datatracker.ietf.org/doc/html/rfc7636). The browser only ever carries a short-lived, single-use **code** — the service-user token is exchanged server-to-server and never transits the browser.
## Prerequisites
* **Callback allowlist.** Every `callback_url` you use must be on Devin's allowlist for your integration. This is configured by Cognition — send us the exact URLs ahead of time. A URL that is not on the list is rejected.
* **Outposts enabled.** The customer's account must have Outposts enabled.
* **Admin authorization.** Authorizing a connection requires a Devin admin with both enterprise-settings and service-user management rights. The partner never needs a Devin token — the admin authorizes it in their own browser session.
## Flow overview
```
Partner backend Admin's browser Devin
│ │ │
│ 1. gen code_verifier, │ │
│ derive code_challenge │ │
│ 2. redirect to app.devin.ai/outposts/connect?…code_challenge│
│───────────────────────────────> │
│ │ 3. admin confirms, "Connect"│
│ │──────confirm connection──────>
│ │ 4. redirect callback_url?code=… │
│<─────────────────────────────── │
│ 5. POST /outposts/connection-token (code + code_verifier) │
│────────────────────────────────────────────────────────────>
│ 6. { access_token, api_base_url, … } │
│<────────────────────────────────────────────────────────────
│ 7. run outpost workers with access_token │
```
### 1. Generate a PKCE verifier and challenge
On your backend, per connection attempt:
* Generate a high-entropy, random **`code_verifier`**: 43–128 characters from the unreserved alphabet `[A-Za-z0-9-._~]` (e.g. `base64url(random 32 bytes)` with padding stripped).
* Derive the **`code_challenge`** as the unpadded base64url of the SHA-256 of the verifier (PKCE "S256"):
```python theme={null}
import base64, hashlib, secrets
code_verifier = secrets.token_urlsafe(32) # 43+ chars, unreserved alphabet
code_challenge = (
base64.urlsafe_b64encode(hashlib.sha256(code_verifier.encode()).digest())
.rstrip(b"=")
.decode()
)
```
Store the `code_verifier` server-side (keyed to whatever state you use to correlate the eventual callback). Never send the verifier to the browser — only the challenge leaves your backend.
### 2. Redirect the admin to the connect page
Send the customer's admin to Devin's connect page with the challenge and your callback:
```
https://app.devin.ai/outposts/connect
?callback_url=https://partner.example.com/devin/outpost-callback
&outpost_name=my-outpost
&outpost_image=https://partner.example.com/logo.png
&platform=linux
&code_challenge=
```
| Param | Required | Notes |
| ---------------- | -------- | -------------------------------------------------------------------------------------- |
| `callback_url` | yes | Where Devin relays the one-time code. Must be on your allowlist. |
| `code_challenge` | yes | The PKCE S256 challenge from step 1. |
| `outpost_name` | no | Suggested outpost name. The admin can edit it before confirming. |
| `outpost_image` | no | URL of a PNG icon used to represent the outpost, such as your company logo. |
| `platform` | no | Preselected outpost platform: `macos`, `linux`, or `windows`. The admin can change it. |
If the admin isn't signed in, the connect page stashes these params and prompts them to sign in first, then resumes.
### 3. Admin confirms
The connect page shows a confirmation with an editable outpost name and platform (and your `outpost_image` if provided). When the admin clicks **Connect**, Devin validates permissions, the callback allowlist, and that the outpost name is free, stores an encrypted, single-use code (10-minute TTL), and redirects back to your app with the one-time code.
No outpost or service user exists yet — they are created only when the code is redeemed (step 5). An unredeemed code simply expires.
### 4. Devin redirects the code to your callback
The browser is redirected to your `callback_url` with the code appended:
```
https://partner.example.com/devin/outpost-callback?code=
```
### 5. Exchange the code server-to-server
From your backend, look up the `code_verifier` you stored in step 1 and redeem the code at the token endpoint. This is a form-encoded, OAuth-style token request:
```bash theme={null}
curl -X POST "https://api.devin.ai/outposts/connection-token" \
-H "Content-Type: application/x-www-form-urlencoded" \
--data-urlencode "grant_type=authorization_code" \
--data-urlencode "code=" \
--data-urlencode "code_verifier="
```
This endpoint needs no Devin auth — possession of the code plus the matching PKCE verifier is the proof. It is unauthenticated on purpose: the code is single-use (atomically consumed), short-lived, and bound to your challenge.
### 6. Receive the credentials
On success Devin creates the outpost and a service user scoped to run the outpost worker, and returns:
```json theme={null}
{
"outpost_id": "...",
"account_id": "...",
"outpost_name": "my-outpost",
"service_user_id": "...",
"api_base_url": "https://api.devin.ai",
"access_token": "cog_...",
"token_type": "bearer"
}
```
Responses carry `Cache-Control: no-store` — do not cache them.
### 7. Run outpost workers
Store `access_token` and `api_base_url` securely and use the token as a bearer credential to run outpost workers against the outpost.
## Error handling
The token endpoint follows [RFC 6749 §5.2](https://datatracker.ietf.org/doc/html/rfc6749#section-5.2). An unknown, expired, already-redeemed (replayed), or PKCE-mismatched code returns `400`:
```json theme={null}
{
"error": "invalid_grant",
"error_description": "Invalid or expired connection code"
}
```
Because codes are single-use and expire after 10 minutes, treat any `invalid_grant` as terminal: discard the stored `code_verifier` and restart the flow from step 1.
## Security notes
* **The token never touches the browser.** Only the single-use code is relayed via redirect; the service-user token is returned solely from the server-to-server exchange.
* **PKCE binds the code to you.** The code is useless without the `code_verifier` held only on your backend, so intercepting the redirect (or the code) is not enough to redeem it.
* **Codes are single-use and short-lived.** Redemption atomically consumes the code; it also expires after 10 minutes.
* **Callback URLs are allowlisted.** Devin only relays a code to a `callback_url` Cognition has pre-approved for your integration.
* **Verify the code is for the requesting user.** Confirm that the code returned to your callback belongs to the same user who originally requested the connection. This prevents an attacker from tricking a user into unsuspectingly binding Devin to a sandbox the attacker controls.
* **Keep `outpost_name` sensible.** The admin may override it; the name you pass is only a suggestion.
# Devin Outposts quickstart
Source: https://docs.devinenterprise.com/cloud/outposts/quickstart
Set up Devin Outposts on your own machines with a self-hosted worker, API token, and repository access to run sessions from one machine.
* An organization with Outposts enabled
* A [v3 API token](/api-reference/v3/overview) with the appropriate Outposts scopes:
* `account.outposts.write` ("Outposts write") for workers claiming/releasing sessions and orchestrators creating/deleting outposts (implies the read scope)
* `account.outposts.read` ("Outposts read") for listing outposts and reading the session queue
* A machine (VM or container) with:
* The Devin CLI installed
* The [machine dependencies](/cloud/outposts/overview#machine-dependencies)
* Your repositories cloned, with configured remotes
* Access to the build tools, package registries, secrets, and internal services your sessions need
Sessions execute directly on the machine with your user's permissions. We
recommend running the worker under a dedicated directory you're comfortable
letting an agent work in freely — or better yet, on a machine reserved for
long-running agentic work, like a Mac Mini on your desk.
Download and install the [Devin CLI](/cli):
```bash theme={null}
curl -fsSL https://cli.devin.ai/install.sh | bash
```
On [Devin Cloud](https://app.devin.ai) go to Settings → Environment → Outposts, and click on the "Create Outpost" button.
Give your Outpost a name, and choose the type of machines it will serve (e.g. Linux, Windows, or Mac). Then, click on the "Create" button.
After creating your Outpost, you will get an Outpost token that workers you want to assign to it will use to authenticate with Devin.
Copy the token and save it in a secure place for future use. **The token will only be shown once when you create the Outpost**.
Navigate to a directory where you want your worker to run:
```bash theme={null}
cd /path/to/worker/directory
```
Sessions get their repositories under a `repos` subdirectory of that directory — a session working on `your-org/app` uses `/path/to/worker/directory/repos/app`. Clone repositories there ahead of time to skip the clone at session start; anything missing is cloned on demand.
And run the `devin worker start` command with your Outpost's name and token you copied earlier:
```bash theme={null}
devin worker start --outpost= --token=
```
On [Devin Cloud](https://app.devin.ai), start a new session and configure it to run on your Outpost. Under "Configuration" → "Virtual environment", you will see your new Outpost listed. Select it to run your session on it.
Now you can ask Devin to start building on your machine! Try something simple like
```
Create a "hello world" python script for me
```
And watch the script appear in your worker's directory!
### Next steps
Start the worker in a directory where your code lives and ask Devin to build on top of it. Sessions see the repositories checked out under `repos/` in the worker's working directory. To serve more sessions concurrently, run the worker on more machines pointed at the same outpost: N workers serve N concurrent sessions, and the rest wait in the queue.
Provision machines automatically as sessions queue, instead of keeping long-lived workers around.
Run your outpost on the platform you already use — Namespace, Modal, E2B, and more.
On [Devin Cloud](https://app.devin.ai) go to Settings → Environment → Outposts, and click on the "Create Outpost" button.
Give your Outpost a name and choose Linux as its platform (your containers run Linux). Then, click on the "Create" button.
After creating your Outpost, you will get an Outpost token that workers you want to assign to it will use to authenticate with Devin.
Copy the token and save it in a secure place for future use. **The token will only be shown once when you create the Outpost**.
Build on the official Devin CLI image (`public.ecr.aws/e0h8a4b6/devin-cli`), adding the [machine dependencies](/cloud/outposts/overview#machine-dependencies) and any repositories or tools your sessions need:
```dockerfile Dockerfile theme={null}
# The Devin CLI is preinstalled and is the image's entrypoint.
# Use :stable, or pin a specific CLI version tag.
FROM public.ecr.aws/e0h8a4b6/devin-cli:stable
# git is required; ffmpeg unlocks screen-recording features
RUN apt-get update && apt-get install -y --no-install-recommends \
ca-certificates git ffmpeg \
&& rm -rf /var/lib/apt/lists/*
# The directory the worker runs in. Sessions get their repositories under
# its `repos` subdirectory, e.g. /workspace/repos/app.
WORKDIR /workspace
# Optionally, pre-clone the repositories your sessions need so they don't
# have to be cloned at session start:
# RUN git clone https://github.com/your-org/app.git repos/app \
# && git clone https://github.com/your-org/infra.git repos/infra
CMD ["worker", "start"]
```
Or tell Devin to make a Dockerfile for you:
```
Write a Dockerfile for a Devin Outposts worker image. Base it on
public.ecr.aws/e0h8a4b6/devin-cli:stable, which has the Devin CLI preinstalled
as the image's entrypoint. Install git and ffmpeg. Clone these repositories
into the `repos` subdirectory of the working directory the worker runs in:
. The default command should be ["worker", "start"].
```
Browser features need Chrome or Chromium in the image, with
`DEVIN_CHROME_PATH` pointing at the binary. The base image is Ubuntu, and
Ubuntu's `chromium` apt package is a snap stub that does not work in
containers — for amd64 images, install Google Chrome instead:
```dockerfile theme={null}
RUN apt-get update && apt-get install -y --no-install-recommends curl \
&& curl -fsSL https://dl.google.com/linux/direct/google-chrome-stable_current_amd64.deb -o /tmp/chrome.deb \
&& apt-get install -y --no-install-recommends /tmp/chrome.deb \
&& rm /tmp/chrome.deb && rm -rf /var/lib/apt/lists/*
ENV DEVIN_CHROME_PATH=/usr/bin/google-chrome
```
For private repositories, bake in credentials with your preferred mechanism (e.g. [build secrets](https://docs.docker.com/build/building/secrets/)) so the clones and remotes work at runtime.
When you're happy with your Dockerfile, build the image:
```bash theme={null}
docker build -t devin-worker .
```
Run a container from your image with the `worker start` command, passing your Outpost's name and the token you copied earlier (the image's entrypoint is the Devin CLI, so arguments go straight to `devin`):
```bash theme={null}
docker run devin-worker \
worker start --outpost= --token=
```
On [Devin Cloud](https://app.devin.ai), start a new session and configure it to run on your Outpost. Under "Configuration" → "Virtual environment", you will see your new Outpost listed. Select it to run your session on it.
Now you can ask Devin to start building in your container! Try something simple like
```
Create a "hello world" python script for me
```
And watch the script appear in the container's working directory!
### Next steps
Bake the repositories you want Devin to work on into the image and ask Devin to build on top of them — sessions see the repositories checked out under `repos/` in the worker's working directory. To serve more sessions concurrently, run more containers pointed at the same outpost: N workers serve N concurrent sessions, and the rest wait in the queue.
Provision containers automatically as sessions queue, instead of keeping long-lived workers around.
Run your outpost on the platform you already use — Namespace, Modal, E2B, and more.
# Devin Outposts API and CLI reference
Source: https://docs.devinenterprise.com/cloud/outposts/reference
Use the Devin Outposts reference for self-hosted workers: devin-remote, fleet API endpoints, CLI flags, binary downloads, and the spawn contract.
Complete reference for the Outposts surface area: the worker CLI, the fleet API, the `devin-remote` binary distribution, and the spawn contract for custom orchestrators.
## Authentication
Workers and orchestrators authenticate with a [v3 API token](/api-reference/v3/overview) belonging to a service user. The role assigned to the service user grants the token its Outposts scopes:
| Role permission | Token scope | Grants |
| ------------------------------------ | ------------------------ | ----------------------------------------------------------------------------------- |
| **Outposts read** (`ReadOutposts`) | `account.outposts.read` | Listing outposts and reading the session queue |
| **Outposts write** (`WriteOutposts`) | `account.outposts.write` | Claiming/releasing sessions and creating/deleting outposts (implies the read scope) |
The older `account.outposts.machine` and `account.outposts.orchestrator`
scopes are deprecated. Roles that were granted them still work (both imply
the write scope), but new roles should use **Outposts read** / **Outposts
write**.
Outposts are scoped to your **account** and shared across all of its organizations.
`devin worker start` can also run without a pre-provisioned token by using your existing CLI login — see [Starting without a token](#starting-without-a-token).
## CLI
### `devin worker start`
Polls an outpost's queue, claims sessions, downloads the correct `devin-remote` binary, and serves sessions. Run it from the directory you want sessions to work in: a session's repositories live under that directory's `repos` subdirectory, so `your-org/app` is checked out at `$(pwd)/repos/app`. Repositories already present there are reused; missing ones are cloned at session start.
```bash theme={null}
devin worker start --outpost=
```
| Flag | Environment variable | Description |
| ---------------------------------- | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `--outpost` | — | Only claim sessions from this outpost, given as its name or its id. If omitted in an interactive terminal, the worker prompts you to pick from your account's outposts. |
| `--session` (alias `--session-id`) | — | Claim and serve one specific session, then exit. |
| `--acceptor-id` | `DEVIN_WORKER_ACCEPTOR_ID` | Stable worker identity used for claims, renewals, and restart recovery. Defaults to a generated ID persisted under the worker data directory. Never share one across machines. |
| `--token` | `DEVIN_OUTPOSTS_TOKEN` | Auth token for the worker. Optional — if both are unset, the worker falls back to your CLI login (see [Starting without a token](#starting-without-a-token)). |
| `--once` | — | Exit after serving one session instead of returning to the queue. |
| `--api-url` | `DEVIN_API_URL` | Devin API base URL. Defaults to `https://api.devin.ai`. |
| `--cache-dir` | `DEVIN_WORKER_CACHE_DIR` | Directory where downloaded `devin-remote` binaries are cached. Defaults to `~/.devin/worker/cache`. |
| `--static-base-url` | `DEVIN_WORKER_STATIC_BASE_URL` | Base URL `devin-remote` binaries are published to. |
| `--gateway-url` | `DEVIN_OUTPOST_GATEWAY_URL` | Outpost gateway URL fallback when the claim response does not carry one. |
| `--remote-binary-sha` | `DEVIN_WORKER_REMOTE_SHA` | Fallback `devin-remote` git SHA when the session does not pin one. When neither is set, the latest published SHA is used. |
| `--pty-bridge-port` | `DEVIN_PTY_BRIDGE_PORT` | Fixed PTY bridge port. Defaults to a free port allocated per session. |
| `--poll-interval-secs` | — | Seconds between queue polls and session status checks. Defaults to `5`. |
The worker's environment can also carry `DEVIN_CHROME_PATH` to point sessions at a Chrome/Chromium binary for browser features.
#### Starting without a token
A pre-provisioned outposts token is not required. With no `--token` and no `DEVIN_OUTPOSTS_TOKEN`, `devin worker start` creates an outpost using your existing CLI login and reuses the saved worker token on later runs.
#### Platform validation
The worker checks that the machine's OS matches the outpost's platform and fails with a clear message on a mismatch, rather than repeatedly claiming and releasing queued sessions.
Windows x64 machines are supported: the worker downloads the correct `devin-remote` binary and passes the Windows system environment through to sessions.
### `devin worker outpost create`
Creates an outpost — a named queue of sessions served by your infrastructure. Requires the write scope.
```bash theme={null}
devin worker outpost create --platform --description "..."
```
| Argument / flag | Description |
| --------------- | ----------------------------------------------------------- |
| `` | Unique (per account) outpost name, e.g. `rhel`, `gpu-h200`. |
| `--platform` | Machine platform: `linux`, `macos`, or `windows`. |
| `--description` | Human-readable description shown in the web app. |
Prints the new outpost's ID (`outpost_env-...`). You can also create outposts in the web app under **Settings → Environment → Outposts**.
### `devin worker outpost delete`
Deletes an outpost. Requires the write scope.
```bash theme={null}
devin worker outpost delete
```
## Fleet API
All endpoints live under `https://api.devin.ai/opbeta/outposts/` and take a bearer token:
```bash theme={null}
curl -H "Authorization: Bearer $DEVIN_API_TOKEN" ...
```
Resources follow a Kubernetes-style `metadata` / `spec` / `status` shape, and the queue follows Kubernetes list-then-watch semantics with at-least-once delivery.
### Objects
#### Queue entry (`devins`)
Each queued session is represented by one queue entry:
| Field | Description |
| ------------------------ | ------------------------------------------------------------------------------------------------------- |
| `metadata.session_id` | The session (devin) ID. |
| `metadata.outpost_id` | The outpost the session is queued on. |
| `metadata.created_at` | When the session was enqueued (Unix timestamp). |
| `metadata.updated_at` | When this object last changed (Unix timestamp). |
| `spec.kind` | `new` or `resume`. |
| `spec.platform` | Machine platform, e.g. `linux`. |
| `spec.remote_binary_sha` | Short commit SHA of the `devin-remote` binary the worker should run; `null` means the worker's default. |
| `spec.network_policy` | The session's effective network policy (see below). |
| `status.phase` | Queue phase: `pending` or `claimed`. |
| `status.acceptor_id` | Worker that currently holds the claim, if claimed. |
| `status.claim_deadline` | When the current claim expires and the session returns to the queue. |
| `status.session_status` | Coarse status of the underlying session: `pending`, `running`, `suspended`, or `terminated`. |
| `status.connect_token` | Gateway connect token; only returned from a successful claim. |
| `status.gateway_url` | Public websocket URL of the outpost gateway; only returned from a successful claim. |
`spec.network_policy` reports whether the session's network access is restricted (`enabled`) and the allowed destinations (`allow`): hostname globs (`{"hostname": ...}`), IPv4 addresses/CIDRs (`{"ipv4": ...}`), or IPv6 addresses/CIDRs (`{"ipv6": ...}`).
#### Outpost
| Field | Description |
| ---------------------- | ---------------------------------------------------- |
| `metadata.outpost_id` | The outpost ID (`outpost_env-...`). |
| `metadata.account_id` | Account that owns the outpost. |
| `metadata.created_at` | When the outpost was created (Unix timestamp). |
| `spec.name` | Unique (per account) outpost name. |
| `spec.platform` | Machine platform; `null` means the default platform. |
| `spec.description` | Human-readable description. |
| `status.queue_depth` | Number of pending (unclaimed) sessions in the queue. |
| `status.active_claims` | Number of unexpired claims held by workers. |
### List queued sessions
```
GET /opbeta/outposts/devins
```
| Query param | Description |
| ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `outpost` | Filter by outpost ID. Applies to both list and watch. |
| `phase` | Filter by queue phase (`pending` or `claimed`). Ignored when watching. |
| `acceptor_id` | Filter by claiming worker. Ignored when watching. |
| `first` | Maximum rows per list page, 1–200. Defaults to 100. |
| `cursor` | Opaque cursor from a previous list response or watch event (the two are interchangeable). For a list, returns rows at or after this position; for a watch, replays changes after it before streaming live ones. |
| `watch` | Stream changes as SSE instead of listing. |
Example response:
```json theme={null}
{
"items": [
{
"metadata": {
"session_id": "devin-...",
"outpost_id": "outpost_env-...",
"created_at": 1781050000,
"updated_at": 1781050000
},
"spec": {
"kind": "new",
"platform": "linux",
"remote_binary_sha": null
},
"status": {
"phase": "pending",
"acceptor_id": null,
"claim_deadline": null,
"session_status": "pending"
}
}
],
"cursor": "djE6MTc4MTA1MDAwMC4w",
"has_next_page": false,
"total": 1
}
```
Pagination and delivery semantics:
* Pass each response's `cursor` into the next request while `has_next_page` is `true`.
* Delivery is at-least-once: a session at a page boundary can appear in both pages, so upsert entries by `metadata.session_id` rather than treating every item as new (the claim CAS makes duplicates harmless).
* When `has_next_page` becomes `false`, save the returned cursor as the starting position for a watch.
### Watch for changes
```
GET /opbeta/outposts/devins?watch=true&cursor=
```
Streams Server-Sent Events. `MODIFIED` events fire when a session's queue entry changes (newly queued sessions also arrive as `MODIFIED`); `DELETED` events fire when it is removed. Each SSE `data` field contains:
```json theme={null}
{
"type": "MODIFIED",
"object": {
"metadata": {
"session_id": "devin-...",
"outpost_id": "outpost_env-...",
"created_at": 1781050000,
"updated_at": 1781050100
},
"spec": {
"kind": "new",
"platform": "linux",
"remote_binary_sha": null
},
"status": {
"phase": "pending",
"acceptor_id": null,
"claim_deadline": null,
"session_status": "pending"
}
},
"cursor": "djE6MTc4MTA1MDEwMC4w"
}
```
Watch semantics:
* Persist each event's top-level `cursor` after processing it; reconnect with the last persisted cursor to replay changes that occurred while disconnected.
* Delivery is at-least-once — tolerate duplicate events.
* Streams end after at most five minutes; a reconnecting watch loop is expected.
* `phase` and `acceptor_id` filters are ignored when `watch=true`; filter watched events using the fields in each event's `object`.
* Omitting the cursor starts from the beginning, so use list-then-watch for normal reconciliation.
### Get a queue entry
```
GET /opbeta/outposts/devins/{session_id}
```
Returns the queue entry for one session.
### Claim a session
```
POST /opbeta/outposts/devins/{session_id}/claim
```
```json theme={null}
{ "acceptor_id": "worker-1" }
```
Atomically claims the session for the given worker identity. If another worker claimed it first, the request fails with `409`. A successful claim response includes `status.connect_token` and `status.gateway_url` — the credentials `devin-remote` needs to connect (see the [spawn contract](#spawn-contract)).
Claiming promises that a worker will be ready within the server-assigned claim deadline (`status.claim_deadline`); expired claims return to the queue automatically.
### Release a claim
```
POST /opbeta/outposts/devins/{session_id}/release
```
```json theme={null}
{ "acceptor_id": "worker-1" }
```
Releases the worker's claim so the session returns to the queue immediately (e.g. when provisioning fails).
### Outposts
```
GET /opbeta/outposts/outposts # list outposts
POST /opbeta/outposts/outposts # create an outpost
GET /opbeta/outposts/outposts/{outpost_id} # get an outpost
DELETE /opbeta/outposts/outposts/{outpost_id} # delete an outpost
```
Create request body:
```json theme={null}
{
"name": "my-outpost",
"platform": "linux",
"description": "Dev boxes in our VPC"
}
```
Create and delete require the write scope, get and list require the read scope; each outpost response reports live `status.queue_depth` and `status.active_claims`.
## Remote binary distribution
The `devin worker start` command automatically downloads the correct `devin-remote` binary. Custom orchestrators that do not use the Devin CLI can fetch it directly from:
```
https://static.devin.ai/devin-rs/remote/
```
**Determine the latest version:**
```bash theme={null}
# Returns the git SHA of the latest published binary for your platform
curl -fsSL "https://static.devin.ai/devin-rs/remote/latest_linux_x64"
```
**Download and verify:**
```bash theme={null}
SHA=$(curl -fsSL "https://static.devin.ai/devin-rs/remote/latest_linux_x64")
# Download the binary
curl -fL "https://static.devin.ai/devin-rs/remote/devin-remote_${SHA}_linux_x64" \
-o devin-remote
# Download and verify the checksum
curl -fsSL "https://static.devin.ai/devin-rs/remote/devin-remote_${SHA}_linux_x64.sha256" \
-o devin-remote.sha256
echo "$(cat devin-remote.sha256) devin-remote" | sha256sum -c
chmod +x devin-remote
```
**Available platforms:**
| Suffix | OS / Architecture |
| ----------------- | ------------------- |
| `linux_x64` | Linux x86\_64 |
| `linux_arm64` | Linux aarch64 |
| `macos_arm64` | macOS Apple Silicon |
| `windows_x64.exe` | Windows x86\_64 |
If the session's queue entry includes a `spec.remote_binary_sha`, use that SHA instead of `latest` — it pins the session to a specific tested version.
## Spawn contract
If your orchestrator launches `devin-remote` itself instead of using `devin worker start`, spawn it as:
```bash theme={null}
devin-remote serve
```
with the following environment variables:
| Variable | Required | Description |
| ----------------------------- | -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `DEVIN_OUTPOST_GATEWAY_URL` | Yes | Outpost gateway base URL, e.g. `wss://outpost-gateway.devin.ai`. |
| `DEVIN_OUTPOST_CONNECT_TOKEN` | Yes | Bearer connect token for the gateway, from the claim response. |
| `DEVIN_OUTPOST_SESSION_ID` | Yes | The session ID being served. All three `DEVIN_OUTPOST_*` variables must be set together. |
| `DEVIN_REMOTE_STATE_DIR` | Strongly recommended | Per-session state directory where the remote stores its credentials, tokens, and shell-integration files. Use a unique directory per session (e.g. `~/.devin/worker/sessions/`, which is what `devin worker` uses). If unset, the remote falls back to a shared system-wide default (`/opt/.devin` on Linux, `~/.devin` on macOS, `C:\ProgramData\devin` on Windows), which must then exist and be writable — and which leaks per-session state across concurrent sessions. Always set this. |
| `DEVIN_CHROME_PATH` | Optional | Path to a Chrome/Chromium binary on the box for the browser tool (there is no Devin-managed Chrome on Outposts). |
| `DEVIN_OUTPOST_DESKTOP` | Optional | Set to `true` to enable the desktop (VNC) stream. It is lazy on the remote side — nothing is captured until a viewer connects — so it is safe to enable unconditionally. |
Give the remote a clean environment containing only the variables above plus basic system variables (`PATH`, `HOME`, `USER`, `LOGNAME`, `TMPDIR`, `LANG`, `TZ`, and — for the desktop stream's screen capture on Linux/X11 — `DISPLAY`, `WAYLAND_DISPLAY`, `XAUTHORITY`). Do not leak anything the agent should not be able to see into the remote: it is inherited by the agent's shell.
Additional lifecycle expectations:
* **Working directory**: launch the remote from the directory you want the session to work in — repositories live under its `repos` subdirectory, i.e. `$(pwd)/repos/` (the same rule as `devin worker start`).
* **Session end**: when the session ends (sleeps or terminates), Devin notifies the remote and it exits with status 0 on its own. Treat a clean exit as the end of the session: confirm the queue entry's `status.session_status` is `suspended` or `terminated` (the status update can lag the exit by a few seconds, so re-read a few times), then release the claim. As a fallback, also poll `status.session_status` while the remote runs and kill the process yourself once it reaches `terminated` (or the queue entry disappears).
# Good vs. Bad Instructions
Source: https://docs.devinenterprise.com/essential-guidelines/good-vs-bad-instructions
What works and what doesn't
Make sure to read [When to Use Devin](/essential-guidelines/when-to-use-devin) and [Instructing Devin Effectively](/essential-guidelines/instructing-devin-effectively) for more essential tips.
**Good Approach**
"Create a new endpoint `/users/stats` that returns a JSON object with user count and average signup age. Use our existing users table in PostgreSQL. You can reference the `/orders/stats` endpoint in `statsController.js` for how we structure responses. Ensure the new endpoint is covered by the `StatsController.test.js` suite."
**Why This Works:**
* Clearly specifies the route and expected response format
* References existing code as a template
* Defines data source (users table)
* Includes test coverage requirements
***
**Bad Approach**
"Add a user stats endpoint."
**Why This Fails:**
* Unspecific about what stats to include
* No mention of data sources
* No reference to existing patterns
* Missing test requirements
**Good Approach**
"In `UserProfileComponent`, add a dropdown that shows a list of user roles (admin, editor, viewer). Use the styling from `DropdownBase`. When a role is selected, call the existing API to set the user role. Validate by checking that the selection updates the user role in the DB. Refer to your Knowledge for how to test properly."
**Why This Works:**
* Names specific components
* Lists exact roles to include
* References existing styling component
* Defines the user interaction flow
* Includes validation steps
***
**Bad Approach**
"Make the user profile page more user-friendly. Add some way for them to change roles and confirm it's working."
**Why This Fails:**
* "User-friendly" is subjective
* No specific UI components mentioned
* Unclear user interaction flow
* Vague validation criteria
## More Examples
### Good
"Add Jest tests for the AuthService methods: login and logout. Ensure test coverage for these two functions is at least 80%. Use `UserService.test.js` as an example. After implementation, run `npm test -- --coverage` and verify the coverage report shows >80% for both functions. Also confirm that tests pass with both valid and invalid credentials, and that logout properly clears session data."
**Why Good?** Clear success metric (80% coverage), references to guide Devin (`UserService.test.js`), and a well-defined scope with specific verification steps.
"Migrate `logger.js` from JavaScript to TypeScript. We already have a `tsconfig.json` and a `LoggerTest.test.js` suite for validation. Make sure it compiles without errors and make sure not to change the existing config! After migration, verify by: 1) running `tsc` to confirm no type errors, 2) running the test suite with `npm test LoggerTest.test.js` to ensure all tests pass, and 3) checking that all existing logger method calls throughout the codebase still work without type errors."
**Why Good?** There's a clear template (`tsconfig.json`) and test suite for immediate feedback, plus specific compilation and validation steps.
"We're switching from pg to sequelize (read [https://sequelize.org/api/v6/identifiers](https://sequelize.org/api/v6/identifiers)). Please update the UserModel queries to use Sequelize methods. Refer to `OrderModel` for how we do it in this codebase. After implementation, verify by: 1) running `npm run test:integration UserModel.test.js` to check all integration tests pass, 2) confirming query performance hasn't degraded by checking execution time on a test dataset of 1000 users, and 3) validating that all CRUD operations still maintain data integrity by running `npm run test:e2e user-flows.test.js`."
**Why Good?** Devin can mimic a known pattern and there are explicit references (`OrderModel.js`). Provides a link to docs so Devin knows to reference them, and includes specific performance and functionality verification steps with exact test commands.
"Implement the pricing page from this Figma file: [https://figma.com/file/abc123/Pricing-Page](https://figma.com/file/abc123/Pricing-Page). Focus on the 'Pricing Section' frame. Use our Tailwind config in tailwind.config.ts for colors and spacing. Reuse the existing Card and Button components from src/components/ui/. After implementing, spin up the dev server and take screenshots at desktop (1440px) and mobile (375px) widths. Do not open a PR until it matches the design."
**Why Good?** Links the specific Figma file, names the exact frame, references the project's design system and existing components, and tells Devin to visually verify its work before opening a PR. With the [Figma MCP](/work-with-devin/mcp) connected, Devin can read design tokens directly from the file.
"Users are reporting 500 errors on the checkout page. Use the Sentry MCP to pull the latest stack traces for the payments-api project. Check the database for any related data issues. Find the root cause, fix it, and add a regression test. Link the Sentry issue in the PR description."
**Why Good?** Points Devin to the right tools ([MCP integrations](/work-with-devin/mcp)), gives a clear investigation path, and defines the expected deliverable (fix + regression test + PR).
### Bad
"Find issues with our codebase and fix them"
**Why Bad?** The request is too vague and open-ended. There are no success criteria and no way for Devin to know when it's done.
**Instead:** Use [Devin Review](/work-with-devin/devin-review) for automated code review on specific PRs, or give Devin a targeted task like "Find and fix all uses of the deprecated `oldLogger` API in `src/services/`."
"Make the landing page look better"
**Why Bad?** "Better" is subjective and Devin has no criteria to aim for. Devin can build functional UIs and implement designs from specs, but it can't make aesthetic judgment calls on its own.
**Instead:** Provide a Figma design, a reference site, or specific changes: "Increase the hero section font size to 48px, add 32px padding, and use the `indigo-500` color from our Tailwind config."
"Build a new microservices architecture for our app."
**Why Bad?** This is a very large and unstructured task. It requires many architectural decisions, trade-offs, and context that isn't in the prompt.
**Instead, break it down:**
1. Use [Ask Devin](/work-with-devin/ask-devin) to investigate your codebase and map dependencies
2. Ask Devin to propose specific architectures with trade-offs
3. Create separate sessions for implementing each service — run them in parallel with [managed Devins](/work-with-devin/advanced-capabilities#managed-devins)
# Instructing Devin Effectively
Source: https://docs.devinenterprise.com/essential-guidelines/instructing-devin-effectively
Learn how to write clear Devin prompts, provide useful context, and define success criteria for reliable results across engineering tasks.
The most important thing to remember when instructing Devin is to **be as specific as possible**. Just as you would provide a detailed spec when asking a coworker to code something, you should do the same with Devin. This guide will help you structure your instructions/prompts to effectively use Devin. For broader strategies on working with coding agents effectively, also check out our [Coding Agents 101 guide](https://devin.ai/agents101).
## How to Write Effective Prompts
Here is an example prompt that demonstrates effective instruction:
In the Devin repo, I want you to build a tool that monitors the RAM and CPU usage of the remote machines that Devin runs on. To do that, please perform the following tasks:
* Create a background task that launches automatically when devin.rs starts.
* The task should open a connection to all forked remote machines used in this Devin session and monitor their RAM and CPU usage.
* If usage exceeds 80% of the available resource, emit a new type of Devin event to signal this (check how we use Kafka).
* Architect this in a smart way that doesn't block other operations. You should understand how all the containers for the Devin sub-agents interact with each other.
### Why This Works Well
* **Detail:** Specifies the Devin repo and the broader purpose (monitoring resource usage).
* **Benefit:** Devin knows the scope and domain clearly.
* **Detail:** Tasks like "create a background task" and "emit an event at 80% usage."
* **Benefit:** Breaks down the work into logical parts.
* **Detail:** Defines "success" as emitting a specific event upon 80% usage.
* **Benefit:** Devin knows exactly what to achieve.
* **Detail:** Mentions Kafka and container interactions.
* **Benefit:** Encourages reuse of established code or design approaches.
## Best Practices: Do's and Don'ts
**Do: Provide Clear Directives**
* **Why:** Devin can get stuck without a clear path or when faced with too many interpretations.
* **How:**
* Make important decisions and judgment calls for Devin.
* Offer specific design choices and implementation strategies.
* Define clear scope, boundaries, and success criteria.
* **Example:** "Optimize the getOrderDetails query in orderService.js by adding a composite index on the order\_id and product\_id columns in the order\_items table. Refactor the query to replace the existing correlated subquery with a JOIN to the products table for fetching product details."
**Don't: Leave Decisions Open-Ended**
* **Why:** Vague instructions can lead Devin to implement solutions that don't align with your actual needs.
* **How:**
* Avoid statements that require Devin to make significant design or implementation decisions without guidance. This can lead to unexpected results.
* **Example:** Don't: "Improve our database's performance."
**Do: Pick [tasks that Devin is good at](when-to-use-devin#evaluating-tasks-for-devin)**
* **Why:**
* **Maximize Results:** By assigning tasks that align with Devin's capabilities, you get the best results for the least amount of effort and ACUs spent.
* **How:**
* Read this guide: [When to use Devin](when-to-use-devin)
* Provide examples, modules, resources, and templates that Devin can follow.
* Share direct links to docs sites so Devin can read about details like API request bodies and features it might not know about.
* Share specific filenames that you want Devin to look at and learn from.
* Connect [MCP integrations](/work-with-devin/mcp) to give Devin access to Figma designs, databases, monitoring tools, and more.
* **Example:** Do: "Refactor state management in the Header component to use React's useReducer hook for better scalability and maintainability. Ensure that all existing functionality is preserved and add unit tests to cover the new state logic."
* **Example:** Do: "Use authTemplate.rs as a reference to maintain consistency in error handling."
* **Example:** Do: "Check out the official Sequelize docs at [https://sequelize.org/docs/v6/getting-started/](https://sequelize.org/docs/v6/getting-started/) for migration steps."
**Don't: Skip Providing Context for Complex Tasks**
* **Why:** Even though Devin can handle complex work, it performs best when you provide context and clear direction.
* **How:**
* For tasks requiring domain knowledge, provide relevant docs, examples, or references.
* For visual tasks, provide Figma files via the [Figma MCP](/work-with-devin/mcp), reference designs, or detailed specs — Devin can build from these but won't invent aesthetics on its own.
* For Android apps, Devin can build and test on an [Android emulator](/onboard-devin/environment/android-emulation). For iOS apps, Devin doesn't have access to a phone emulator, so provide clear testing criteria.
* **Example:** Don't: "Make the app look better" — instead, provide specific design specs or a Figma file.
* **Example:** Don't: "Improve our database's performance" — instead, specify which queries to optimize and what metrics to target.
**Do: Establish Clear and Frequent Checks**
* **Why:** Frequent feedback (both from you and from tests/checks/linters) ensures Devin corrects mistakes effectively.
* **How:**
* Use tests (unit/integration) to confirm correctness.
* Maintain build validations, lint checks, and static analysis for code quality.
* Enable [Devin Review](/work-with-devin/devin-review) with [Auto-Fix](/work-with-devin/devin-review#auto-fix) so Devin automatically responds to review comments and CI failures — creating a closed loop where PRs iterate toward merge-ready quality without you in the loop.
* **Example:** Do: "Run npm test after each iteration."
* **Example:** Do: "Ensure the pipeline on CircleCI doesn't fail."
* **Example:** Do: "Pass ESLint/Prettier checks before pushing any commits."
**Don't: Neglect Providing Feedback**
* **Why:** Without feedback, Devin won't know if its solutions meet your standards.
* **How:**
* Avoid assigning tasks without defining how you'll evaluate them.
**Do: Set Clear Checkpoints and Sub-Tasks**
* **Why:** Breaking down complex tasks into smaller checkpoints helps Devin stay focused and reduces errors.
* **How:**
* Split tasks into verifiable sub-tasks, and start one Devin session for each sub-task.
* Define what success looks like for each sub-task and optionally set checkpoints within each sub-task.
* Ask Devin to report back after completing each checkpoint or sub-task.
**Examples:**
* **Example:** Do: "When working with the dataset, verify that it has at least 500 rows and contains columns X, Y, Z."
* **Example:** Do: "When modifying the API, confirm the endpoint returns status 200 and includes all required fields."
* **Example:** Do: "When updating UI, check that the component renders without console errors and matches the design spec."
**Don't: Skip Specific Validation Requirements**
* **Why:** Without defined validation steps, Devin cannot confidently complete tasks.
* **How:**
* Avoid vague success criteria.
* Don't leave verification steps implicit or undefined.
* **Example:** Don't: "Make sure it works."
Devin has a full desktop environment — shell, IDE, and browser. Tell Devin to test its own work before opening a PR:
* **Spin up the app:** "Run `npm run dev` and verify the new page renders at `/settings`."
* **Browser testing:** "Open the browser, navigate to the login page, and confirm the OAuth flow completes successfully."
* **Visual verification:** "Take screenshots at desktop (1440px) and mobile (375px) widths and confirm the layout matches the design."
* **Screen recording:** "Record yourself testing the checkout flow end-to-end."
This lets Devin QA its changes the same way you would — before you ever need to look at the PR.
For repetitive or complex tasks, we suggest using and iterating on [Playbooks](/product-guides/creating-playbooks). Learn more about [using playbooks effectively](/product-guides/using-playbooks). Playbooks are reusable and shareable prompts that streamline task delegation. For example, if you want Devin to address ongoing CI build failures, create a playbook that includes the general steps Devin should follow each time.
For persistent context that Devin should remember across all sessions — such as coding standards, common bugs and fixes, [deployment workflows](/product-guides/deployment-capabilities), or how to use internal tools — use [Knowledge](/product-guides/knowledge). Knowledge items are automatically recalled when relevant, so you don't need to repeat the same instructions in every prompt. You can pin Knowledge to specific repos or apply it globally.
**Playbooks vs. Knowledge:** Use Playbooks for step-by-step procedures tied to specific tasks. Use Knowledge for general tips, conventions, and context that apply broadly across sessions.
# Prompt Templates Cheat Sheet
Source: https://docs.devinenterprise.com/essential-guidelines/prompt-templates-cheat-sheet
Ready-to-use prompt templates for common tasks
Use these templates as starting points for your prompts. Customize the bracketed sections `[like this]` to fit your specific needs.
## Bug Fixes
### Fix a Specific Bug
```
Fix the bug where `[describe the bug behavior]`.
Steps to reproduce:
1. `[Step 1]`
2. `[Step 2]`
3. `[Step 3]`
Expected behavior: `[what should happen]`
Actual behavior: `[what actually happens]`
Please:
1. Investigate the root cause in `[relevant file/directory]`
2. Implement a fix that addresses the root cause
3. Add a regression test to prevent this issue from recurring
4. Run the existing test suite to ensure no regressions
```
### Investigate Production Issue
```
Users are reporting `[describe the issue]` in production.
Please:
1. Use the `[Sentry/DataDog/Log monitoring tool]` MCP to pull recent error logs and stack traces
2. Identify the root cause of the issue
3. Implement a fix
4. Add appropriate error handling to prevent similar issues
5. Create a regression test
6. Link the monitoring/alert in the PR description
```
## Feature Implementation
### Add a New API Endpoint
```
Create a new API endpoint `[endpoint path]` that `[describe what it does]`.
Requirements:
- Method: `[GET/POST/PUT/DELETE]`
- Request body: `[describe request structure]`
- Response format: `[describe response structure]`
- Authentication: `[describe auth requirements]`
Please:
1. Reference the existing `[similar endpoint file]` for patterns
2. Implement the endpoint following our existing conventions
3. Add input validation and error handling
4. Write unit tests for the new endpoint
5. Update API documentation if applicable
6. Run the test suite to ensure everything passes
```
### Add a New UI Component
```
Add a new `[component type]` component to `[file/location]`.
Requirements:
- Component name: `[ComponentName]`
- Props: `[list props and their types]`
- Functionality: `[describe what it should do]`
- Styling: Use `[existing component/library]` as a reference
Please:
1. Create the component following our existing patterns
2. Implement the required functionality
3. Add proper TypeScript types
4. Style it to match our design system
5. Add unit tests for the component
6. Integrate it into `[parent component/page]`
7. Test it manually by running the dev server
```
### Implement a Feature from Design
```
Implement the `[feature name]` from this design file: `[Figma/link to design]`
Focus on the `[specific frame/section]` frame.
Requirements:
- Use our existing components from `[component library path]`
- Follow the styling in `[design system file]`
- Ensure responsive design at `[breakpoint 1]` and `[breakpoint 2]`
Please:
1. Implement the feature following the design specifications
2. Reuse existing components where possible
3. Test at desktop (1440px) and mobile (375px) widths
4. Take screenshots to verify it matches the design
5. Do not open a PR until it visually matches the design
```
## Code Refactoring
### Refactor a Module
```
Refactor the `[module/file name]` to improve `[specific aspect: maintainability/performance/readability]`.
Current issues:
- `[Issue 1]`
- `[Issue 2]`
- `[Issue 3]`
Requirements:
- Keep all existing functionality intact
- Follow the patterns in `[reference file]`
- Improve `[specific metric: code complexity/performance]`
Please:
1. Analyze the current implementation
2. Refactor following best practices
3. Ensure all existing tests still pass
4. Add tests for any new functions introduced
5. Run the full test suite
6. Measure and report performance improvements if applicable
```
### Convert to New Pattern
```
Convert `[file/directory]` to use `[new pattern/library/framework]`.
Reference: `[link to documentation or example file]`
Requirements:
- Maintain all existing functionality
- Follow the conventions in `[example file]`
- Update any dependent code
Please:
1. Review the documentation and examples
2. Convert the code step by step
3. Update imports and dependencies
4. Ensure all tests pass
5. Run `[build command]` to verify no errors
6. Test the functionality manually
```
## Testing
### Add Test Coverage
```
Add comprehensive test coverage for `[file/module/function]`.
Current coverage: `[current coverage %]`
Target coverage: `[target coverage %]`
Please:
1. Analyze the existing code to identify edge cases
2. Write unit tests for all public methods
3. Add integration tests if applicable
4. Reference `[existing test file]` for testing patterns
5. Run `npm test -- --coverage` and verify coverage meets target
6. Ensure all tests pass
```
### Debug Failing Tests
```
Fix the failing tests in `[test file or directory]`.
Test failures:
- `[Test name 1]`: `[error message]`
- `[Test name 2]`: `[error message]`
Please:
1. Investigate why these tests are failing
2. Determine if the tests or the implementation need fixing
3. Fix the root cause
4. Ensure all tests in the suite pass
5. Run the full test suite to check for regressions
```
## Documentation
### Document a Module
```
Add comprehensive documentation to `[file/module]`.
Please:
1. Add JSDoc/TypeDoc comments to all public functions
2. Document parameters, return values, and exceptions
3. Add usage examples for complex functions
4. Create a README if this is a new module
5. Follow our documentation style guide in `[style guide link]`
6. Update the main API documentation if applicable
```
### Update API Documentation
```
Update the API documentation for `[endpoint/function]`.
Changes made:
- `[Change 1]`
- `[Change 2]`
Please:
1. Update the `[OpenAPI/Swagger]` specification
2. Update any inline code comments
3. Add usage examples if the behavior changed
4. Update the `[documentation file]`
5. Verify the documentation builds successfully
```
## Performance Optimization
### Optimize Database Queries
```
Optimize the database queries in `[file/module]`.
Performance issues:
- `[Specific query]` is slow (takes `[time]`)
- `[Specific operation]` causes N+1 queries
Please:
1. Analyze the query execution plans
2. Add appropriate indexes to `[table/column]`
3. Refactor queries to use joins instead of N+1
4. Benchmark before and after performance
5. Ensure all tests still pass
6. Document the performance improvements
```
### Optimize Frontend Performance
```
Optimize the performance of `[component/page]`.
Performance issues:
- Slow initial load time
- Large bundle size
- Unnecessary re-renders
Please:
1. Analyze the bundle size using `[bundle analyzer]`
2. Implement code splitting for `[large module]`
3. Add memoization where appropriate
4. Optimize images and assets
5. Lazy load components below the fold
6. Measure performance improvements using Lighthouse
7. Ensure functionality remains intact
```
## Security
### Fix Security Vulnerability
```
Fix the security vulnerability identified in `[file/module]`.
Vulnerability type: `[e.g., SQL injection, XSS, CSRF]`
Severity: `[High/Medium/Low]`
Please:
1. Review the security advisory: `[link to advisory]`
2. Implement the recommended fix
3. Add input validation and sanitization
4. Add a security test to prevent regression
5. Run the security audit: `[audit command]`
6. Ensure no other similar vulnerabilities exist
```
### Add Security Headers
```
Add security headers to the `[application/API]`.
Required headers:
- `[Header 1]`: `[value]`
- `[Header 2]`: `[value]`
- `[Header 3]`: `[value]`
Please:
1. Configure the headers in `[config file]`
2. Test that headers are set correctly using `[tool/method]`
3. Ensure existing functionality is not broken
4. Document the security improvements
```
## Migration & Upgrades
### Upgrade Dependency
```
Upgrade `[package/library]` from version `[old version]` to version `[new version]`.
Please:
1. Review the changelog for breaking changes: `[changelog link]`
2. Update the dependency in `[package.json/requirements.txt]`
3. Update any deprecated API usage
4. Run the migration script if applicable: `[migration command]`
5. Run all tests to ensure compatibility
6. Test the application manually
7. Update documentation if APIs changed
```
### Migrate to New Service
```
Migrate from `[old service]` to `[new service]`.
Reference documentation: `[link to new service docs]`
Please:
1. Set up the new service following the documentation
2. Migrate existing data/configuration
3. Update all code to use the new service
4. Reference `[example file]` for implementation patterns
5. Run integration tests to verify functionality
6. Gradually roll out and monitor for issues
7. Decommission the old service after verification
```
## Code Review
### Review a Pull Request
```
Review the pull request: `[PR link or number]`
Focus areas:
- Code quality and maintainability
- Performance implications
- Security considerations
- Test coverage
- Documentation
Please:
1. Review each file changed
2. Leave specific, actionable comments
3. Verify the changes address the PR description
4. Check for edge cases and error handling
5. Ensure tests are adequate
6. Approve or request changes with clear feedback
```
## General Purpose
### Research and Implement
```
I need to implement `[feature/functionality]` using `[technology/library]`.
Please:
1. Research the best practices for `[technology/library]`
2. Find and review documentation: `[expected doc sources]`
3. Look at open-source examples if applicable
4. Propose an approach before implementing
5. Implement the solution following best practices
6. Add tests and documentation
7. Verify it works as expected
```
### Debug and Fix
```
Something is wrong with `[feature/component]`.
Symptoms:
- `[Symptom 1]`
- `[Symptom 2]`
Please:
1. Investigate the issue in `[relevant files]`
2. Add logging/debugging statements as needed
3. Identify the root cause
4. Implement a fix
5. Test the fix thoroughly
6. Remove any temporary debugging code
7. Ensure no regressions
```
**Pro tip**: For recurring tasks, consider creating a [Playbook](/product-guides/creating-playbooks) with these templates so you can reuse them easily.
# How does Devin fit into my existing SDLC?
Source: https://docs.devinenterprise.com/essential-guidelines/sdlc-integration
See how Devin supports software development lifecycle work, from code planning and testing through review, security, and deployment.
## Overview
Devin integrates across the entire software development lifecycle—from understanding existing code and planning changes to testing, reviewing, and deploying updates.
For details on Devin's built-in app deployment options and their limitations, see the [Devin app deployments guide](/product-guides/deployment-capabilities).
## Where Engineers Spend Their Time
Research shows that less than 20% of an engineer's time is spent writing code ([1](https://www.software.com/reports/code-time-report), [2](https://www.microsoft.com/en-us/research/wp-content/uploads/2024/11/Time-Warp-Developer-Productivity-Study.pdf)). The majority of time is dedicated to understanding codebases, planning changes, reviewing work, and testing. Devin helps accelerate each of these phases while keeping human engineers in control.
## Working Within Existing Engineering Processes
Devin contributes to existing codebases by creating Pull Requests containing its suggested code changes. Devin is subject to the exact same branch protections and SDLC policies as any human engineer. Human engineers review PRs created by Devin before choosing whether to merge the code changes.
## SDLC Integration Points
### Understanding Code & Planning
Before writing any code, engineers need to understand existing systems and plan their approach. Devin accelerates this phase significantly:
Use [DeepWiki](/work-with-devin/deepwiki) to navigate architecture and code with auto-generated documentation. DeepWiki provides conversational documentation for your repositories, making it faster to understand complex systems and dependencies.
Use [Ask Devin](/work-with-devin/ask-devin) to query your codebase directly. Ask Devin can answer questions about code structure and dependencies, and help you scope and plan tasks before implementation. With advanced code search capabilities, Ask Devin produces detailed, accurate, and well-cited answers, reducing the time spent reverse-engineering and tracing dependencies.
Devin can scope and plan tasks by analyzing requirements against your codebase. When integrated with [Jira](/integrations/jira) or [Linear](/integrations/linear), Devin automatically analyzes tickets and provides confidence scores to help prioritize work.
Devin can triage alerts and backlog items, categorizing issues and suggesting approaches. This helps engineering teams prioritize effectively and reduces time spent on initial investigation.
### Development
Devin handles development tasks asynchronously, allowing engineers to delegate work while focusing on higher-value activities:
Delegate well-defined tasks to Devin asynchronously. Devin works in its own environment, preparing code changes and submitting PRs for review. This is particularly effective for repetitive tasks that can be parallelized across multiple Devin sessions.
Devin excels at large-scale modernization projects. For example, customers have used Devin to migrate multi-million-line ETL monoliths to modular components, achieving 8x human time savings. Devin can execute end-to-end migrations across hundreds of repositories, including legacy stacks like COBOL.
Devin prepares and submits PRs following your team's conventions. Devin automatically discovers [PR templates](/integrations/pr-templates) in your repository — including Devin-specific templates (`DEVIN_PR_TEMPLATE.md`) and standard GitHub/GitLab templates. You can customize the template Devin uses without changing your human-facing default.
### Testing
Devin runs self-driven test loops in its own environment, improving test coverage and catching issues early:
Devin writes tests from human-provided [playbooks](/product-guides/creating-playbooks), following your team's testing patterns and conventions. When Devin generates tests, coverage typically increases 1.5-2x, often reaching 90%+ coverage.
Devin runs tests in its own environment, iterating on code until tests pass. This includes running your existing test suites, linting, and type checking before submitting PRs.
### Code Review
Devin can provide automated first-pass reviews on pull requests:
[Devin Review](/work-with-devin/devin-review) provides automated first-pass reviews on pull requests, checking for correctness and conformance with organizational best practices. You can enable it on all PRs or only Devin-authored PRs via your organization settings.
With [Auto-Fix](/work-with-devin/devin-review#auto-fix) enabled, Devin automatically responds to code review comments, fixes flagged bugs, and iterates on CI failures — creating a closed loop where PRs iterate toward merge-ready quality without you in the loop.
Devin checks PRs against your coding standards, style guides, and security requirements, flagging potential issues for human reviewers to address.
### Security and Compliance
Devin integrates into CI/CD pipelines to address security findings automatically:
Integrate Devin into your CI/CD pipeline to respond to findings from static analysis tools like SonarQube, Fortify, or Veracode. When these tools flag an issue, Devin can review and fix it automatically.
Customers report approximately 70% of vulnerabilities are resolved automatically—clearing historical backlogs and reducing security risk.
Devin can execute compliance-related changes across your codebase. For example, when new regulations require updates across hundreds of thousands of files, Devin can implement the changes systematically across all affected repositories.
## Getting Started
To integrate Devin into your SDLC:
1. **Connect your repositories** via [GitHub](/integrations/gh), [GitHub Enterprise Server](/enterprise/integrations/github-enterprise-server), [GitLab](/integrations/gitlab), [Bitbucket](/integrations/bitbucket), or [Azure DevOps](/enterprise/integrations/azure-devops)
2. **Configure branch protections** to ensure Devin's PRs go through your standard review process
3. **Set up integrations** with [Jira](/integrations/jira) or [Linear](/integrations/linear) for ticket-based workflows, and [Slack](/integrations/slack) or [Microsoft Teams](/integrations/microsoft-teams) to chat and collaborate with Devin
4. **Create [playbooks](/product-guides/creating-playbooks) and [knowledge](/product-guides/knowledge)** to codify your team's patterns and standards for Devin to follow
5. **Connect MCPs** to extend Devin's capabilities with [custom tools and integrations](/work-with-devin/mcp)
6. **Configure CI/CD integration** to enable automated security remediation and testing
# When to Use Devin
Source: https://docs.devinenterprise.com/essential-guidelines/when-to-use-devin
**TLDR:** Devin can handle the majority of engineering tasks, including medium and hard complexity work. The clearer and more specific your instructions, the higher the success rate — especially for complex tasks. For more comprehensive guidance on working effectively with coding agents, see our [Coding Agents 101 guide](https://devin.ai/agents101).
## Best Practices
**Scope tasks with [Ask Devin](/work-with-devin/ask-devin) before implementation:**
* Explore your codebase with Ask Devin's advanced code search, scope the approach, and let Devin auto-generate a high-context prompt, all before a single line of code is written.
**Run multiple Devins in parallel:**
* Carve out independent tasks and run them simultaneously. [Ask Devin to delegate to managed Devins](/work-with-devin/advanced-capabilities#managed-devins) to launch many sessions at once, or the [Devin API](/api-reference/overview) for programmatic orchestration.
* Return to draft PRs waiting for review.
**Tag Devin on [Slack](/integrations/slack) or [Teams](/integrations/microsoft-teams):**
* Start sessions directly from conversations about bugs, feature requests, or questions. Devin responds in-thread with updates.
**Let Devin close the loop:**
* Enable [Devin Review](/work-with-devin/devin-review) with [Auto-Fix](/work-with-devin/devin-review#auto-fix) so Devin automatically responds to code review comments, fixes flagged bugs, and iterates on CI failures — without you needing to be in the loop. The result: PRs that are ready to merge by the time you look at them.
**Extend Devin's reach with [MCP integrations](/work-with-devin/mcp):**
* Connect Devin to Datadog, Sentry, databases, Figma, Notion, Stripe, and hundreds of other tools via the MCP Marketplace. Devin can investigate production issues, query data, read designs, and more — all within a single session.
**Let Devin test its own work:**
* Devin has a full desktop environment with a shell, IDE, and browser. It can spin up your app locally, click through the UI, take screenshots, record screen recordings, and QA its own changes before opening a PR.
**Automate recurring tasks with [Scheduled Sessions](/product-guides/scheduled-sessions):**
* Set up daily or weekly sessions to triage Sentry errors, update dependencies, generate reports, or any other repeatable work.
**Use [Devin CLI](/cli) for local coding:**
* Work with Devin directly from your terminal without leaving your editor. Perfect for quick fixes, code exploration, and tasks that benefit from your local environment context. Use [`/handoff`](/work-with-devin/devin-cli#handoff-to-cloud-devin) to seamlessly transfer work to a cloud Devin session when needed. Install with `curl -fsSL https://cli.devin.ai/install.sh | bash`.
## Evaluating Tasks for Devin
When deciding if a task suits Devin, ask yourself:
1. **Can I describe clear success criteria?** Tasks with test suites, CI checks, or verifiable outcomes yield the best results.
2. **Is there enough context?** Provide relevant files, patterns, docs, or examples. The more context, the better.
3. **Would breaking this down help?** For very large projects, split the work into focused sessions that build on each other. You can run them in parallel with [managed Devins](/work-with-devin/advanced-capabilities#managed-devins).
As a rule of thumb: if a task would take you three hours or less, Devin can most likely do it. For longer tasks, break them into smaller sessions.
## Pre-Task Checklist
**Task Definition and Scope**
* Good tasks have a clear start and end, plus explicit success criteria (e.g., passing tests, matching an existing pattern, CI green)
* For complex tasks, use [Ask Devin](/work-with-devin/ask-devin) to collaboratively scope the work before starting a session. Ask Devin can help you investigate the codebase and outline your approach.
**Available Context**
* Are there examples or patterns for Devin to follow?
* Can you provide prototypes, partial code, or existing patterns from the codebase or docs?
* Are there links, filenames, or design files for Devin to reference?
* Have you connected relevant [MCP integrations](/work-with-devin/mcp) (databases, monitoring, design tools)?
**Success Validation**
* Tasks with test suites, lint checks, or compilation steps yield better results
* Devin can test its own work by launching your app and verifying behavior in the browser
* Enable [Devin Review](/work-with-devin/devin-review) to catch bugs before you even look at the PR
**Review Effort**
* With [Auto-Fix](/work-with-devin/devin-review#auto-fix) enabled, Devin responds to review comments and CI failures automatically
* Ideally, you just need to see that CI passes and the PR is approved
**Task Size**
* For large tasks, consider breaking them down into sub-tasks or [asking Devin to run them in parallel](/work-with-devin/advanced-capabilities#managed-devins)
* Splitting large requests into smaller, manageable chunks helps Devin stay on track
* Try to keep sessions focused (XS, S, or M as measured by [Session Insights](/product-guides/session-insights))
## Post-Task Review
**Monitor Session Trajectory**
* Leverage [Session Insights](/product-guides/session-insights) to investigate the session timeline and identify actionable feedback for future sessions
* If Devin repeatedly encounters session usage limits, the task assigned to it might be too complex
* If Devin is struggling with its dev environment, revisit the [Workspace setup](/onboard-devin/environment)
**Learning from Devin's Mistakes**
* In your future sessions, provide more context or instructions to help Devin get past previous obstacles
* Consider adding or approving [Knowledge](/product-guides/knowledge) so Devin remembers things it learned from previous sessions
* Use the improved prompt suggested by [Session Insights](/product-guides/session-insights) as a starting point for similar future tasks
# Introducing Devin
Source: https://docs.devinenterprise.com/get-started/devin-intro
Devin is the AI software engineer, built to help ambitious engineering teams crush their backlogs.
Devin is an autonomous AI software engineer that can write, run and test code. Devin can handle most tasks, excluding extremely difficult tasks. As a rule of thumb, if you can do it in three hours, Devin can most likely do it. Ask Devin to tackle Linear/Jira tickets, implement entirely new features, repro and fix bugs, build internal tools, and more!
See what's new with Devin in our [release notes](/release-notes/overview)!
In some cases Devin may not function exactly as referenced, or documentation may be out of date.
## Already Signed Up? Get Started Now:
[Browse use cases](/use-cases/gallery/index)
## What are Devin's strengths?
Here are the types of tasks where Devin excels:
1. **Tackling many tasks in parallel, before they end up in your backlog**
* Linear/Jira tickets
* Entire features from scratch
* Bug reports
* App testing
2. **Code migrations, refactors, and modernization**
* Language migrations (e.g. JavaScript to TypeScript)
* Framework upgrades (e.g. Angular 16 -> 18)
* Monorepo to submodule conversions
* Removing unused feature flags
* Extracting common code into libraries
3. **Common, repetitive engineering tasks**
* PR Review
* Codebase Q\&A
* Reproducing & fixing bugs
* Writing unit tests
* Maintaining documentation
4. **Customer engineering support**
* Building new integrations and working with unfamiliar APIs
* Creating customized demos
* Prototyping solutions
* Building internal tools
**To get the best results from Devin:**
* Write clear prompts with explicit completion criteria — the clearer the task, the higher the success rate, especially for complex work.
* Make tasks easy to verify — e.g. checking that CI passes or testing an automatic deployment.
* For harder tasks, break them into well-scoped steps and provide relevant context or examples.
* Follow our [best practices and pre-task checklist](/essential-guidelines/when-to-use-devin).
**The most successful workflows include:**
* Tagging Devin on a [Slack](/integrations/slack) or [Teams](/integrations/microsoft-teams) thread about a bug you're discussing with coworkers
* Delegating a more complex task via the web application and taking over in Devin's IDE once it gives you a good first draft.
* Running [Devin for Terminal](https://cli.devin.ai) in your local environment for quick fixes, code exploration, and interactive coding right from the command line — then using [`/handoff`](/work-with-devin/devin-cli#handoff-to-cloud-devin) to send longer tasks to cloud Devin.
* Carving out tasks from your todo list at the start of your day and returning to draft PRs waiting for review.
Devin is most effective when it's part of your team and your existing workflow.
## General Product Features
### The Devin Interface
Devin is designed to be a conversational user interface, and allows you to follow and take over Devin's development process in the embedded IDE. Devin is also available via the [Devin API](/api-reference/overview).
In Devin's Workspace, you'll find [developer tools](/work-with-devin/devin-session-tools) that Devin will use to complete your task.
Devin's terminal, where you can watch commands being executed and view output logs. You can also copy the shell output for debugging purposes. To run commands directly, use the IDE's shell.
Devin's embedded code editor equipped with all the IDE tools and shortcuts you're familiar with. Follow Devin's work real-time and take over to run commands, make direct code edits or test Devin's code.
Watch Devin browse through documentation, test web applications it builds, download/upload information, and more. You can jump in to help Devin navigate through browsing tasks via the Interactive Browser.
## Getting Access
To access Devin, sign up at [app.devin.ai](https://app.devin.ai). Individual and Teams plans are available.
You can also install [Devin for Terminal](https://cli.devin.ai) to use Devin directly from your command line:
* Tagging Devin on a [Slack](/integrations/slack) or [Teams](/integrations/microsoft-teams) thread about a bug you're discussing with coworkers
* Delegating a more complex task via the web application and taking over in Devin's IDE once it gives you a good first draft.
* Running [Devin CLI](/cli) in your local environment for quick fixes, code exploration, and interactive coding right from the command line — then using [`/handoff`](/work-with-devin/devin-cli#handoff-to-cloud-devin) to send longer tasks to cloud Devin.
* Carving out tasks from your todo list at the start of your day and returning to draft PRs waiting for review.
Devin's terminal, where you can watch commands being executed and view output logs. You can also copy the shell output for debugging purposes. To run commands directly, use the IDE's shell.
Devin's embedded code editor equipped with all the IDE tools and shortcuts you're familiar with. Follow Devin's work in real time and take over to run commands, make direct code edits or test Devin's code.
Watch Devin browse through documentation, test web applications it builds, download/upload information, and more. You can jump in to help Devin navigate through browsing tasks via the Interactive Browser.
You can also install [Devin CLI](/cli) to use Devin directly from your command line:
```bash theme={null}
curl -fsSL https://cli.devin.ai/install.sh | bash
```
If your company is already working with Cognition, you can request permissions from your Administrator or Cognition directly and access Devin via the web application at [app.devin.ai](https://app.devin.ai).
## Feedback
We're learning and our customers' input is crucial! You can share your feedback to [support@cognition.ai](mailto:support@cognition.ai), [via Slack Connect](https://app.devin.ai/settings/support) (available to Teams users), or directly via the "Feedback" button on the far right edge of the web app.
We log all feedback provided by customers and use it to make quick improvements to Devin and inform our product priorities and roadmap.
## Demo
To learn more check out our [blog](https://cognition.com/blog/devin-generally-available).
## About Cognition
We are an applied AI lab building end-to-end software agents.
We're building AI software engineers that help ambitious engineering teams crush their backlogs.
# Your First Session
Source: https://docs.devinenterprise.com/get-started/first-run
Start your first session and see what Devin can do
Before you start your first session, make sure you've [indexed](/onboard-devin/index-repo) and [set up](/onboard-devin/environment) your repositories. These are the foundational steps that help Devin understand and work with your codebase.
Now that you're all set up, kick off your first Devin session! This guide will walk you through the new session interface and help you understand the best ways to interact with Devin.
Prefer working from your terminal? [Devin CLI](/cli) lets you start sessions right from the command line. Install in 2 minutes with `curl -fsSL https://cli.devin.ai/install.sh | bash`.
## Understanding the Devin Session Page
When you start a new session, you'll see two primary modes: **Ask** and **Agent**.
Unless you already have a fully scoped plan, we recommend starting with Ask to work with Devin on constructing a plan, then moving to Agent mode to execute it.
### Ask Mode
**Ask Devin** is a lightweight mode for exploring your codebase and planning tasks with Devin, without making changes to the actual code. Ask Devin now supports both asking questions and planning:
* **Ask questions** about how your code works. Uses advanced code search to produce detailed, accurate, and well-cited answers.
* **Plan tasks** by scoping and planning work before implementation. Devin generates context-rich prompts for Agent sessions.
When you start a Devin session from Ask Devin, the session status is visible directly in the conversation.
#### Triggering Ask Mode
You can trigger Ask mode from the main page or from a DeepWiki page.
For Ask mode from the main page, toggle to Ask mode and select the repository/repositories you want to ask about.
For Ask mode from a DeepWiki page, type a query in the chat input at the bottom of the page and click Ask. This will automatically scope Devin's knowledge to that repository specifically.
Learn more in our [Ask Devin guide](/work-with-devin/ask-devin).
Once you've worked with Devin to understand the problem and create a plan, you're ready to move to Agent mode.
### Agent Mode
Agent mode is Devin's full autonomous mode where it can write code, run commands, browse the web, and complete complex tasks end-to-end. Use Agent mode when you're ready to:
* Implement features or fix bugs
* Create pull requests
* Run tests and debug issues
* Perform multi-step tasks that require code changes
#### Triggering Agent Mode
You can trigger Agent mode from the main page or from an Ask Devin session. When a session is started from Ask Devin, its status is displayed in the Ask Devin conversation so you can track progress.
For tasks that are not fully scoped, we recommend:
* Start with **Ask mode** to plan out the task
* **Construct a Devin Prompt**, which will draw from your Ask session to create a scoped plan
* Click **Send to Devin** to move to Agent mode and execute the task
This flow is shown below:
For Agent mode from the main page, toggle to Agent mode and select the repository/repositories you want to work with.
When starting an Agent session, you'll configure a few options: selecting a Repository and selecting an Agent.
#### Selecting a Repository
Select the repository you want Devin to work with. Click the repository selector to see all repositories that have been [added to Devin's machine](/onboard-devin/environment).
Selecting a repository ensures Devin:
* Has access to your codebase and can make changes
* Uses the correct branch as a starting point
* Can create pull requests to the right repository
#### Selecting an Agent
You can choose which agent configuration Devin uses for your session. Different agents may have different capabilities or be optimized for specific types of tasks.
Available agents include:
* **Devin** (default) — A general-purpose AI software engineer for building features, fixing bugs, refactoring code, and most development tasks.
* **Fast Mode** — An optimized mode for quick, well-scoped tasks.
* **[Dana](/work-with-devin/data-analyst)** — A data analyst agent optimized for querying databases, analyzing data, and creating visualizations.
If you're unsure which agent to use, the default Devin agent works well for most tasks.
You don't need to start a new session to change modes. You can switch the agent mid-session using the agent toggle next to the message input on the session page — the change takes effect with your next message. In Slack, you can switch modes mid-session by starting a message with `!ultra`, `!fast`, `!lite`, `!fusion`, `!swe`, or `!normal` (see [Slack mode keywords](/integrations/slack)).
## Using @ Mentions
Use `@` mentions to give Devin specific context about files, repositories, or other resources. When you type `@` in the chat input, you'll see a dropdown of available mentions:
* **@Repos** - Reference a specific repository
* **@Files** - Reference a specific file in your codebase
* **[@Macros](/product-guides/knowledge)** - Reference a macro for a Knowledge entry
* **[@Playbooks](/product-guides/creating-playbooks)** - Reference a team or community playbook, which are detailed prompt templates that can be used to guide Devin's behavior
* **[@Skills](/product-guides/skills)** - Reference a skill defined in your repository (reusable procedures committed as `SKILL.md` files)
* **[@Secrets](/product-guides/secrets)** - Reference a specific secret (e.g. API keys, credentials, etc.) from Devin's session manager
* **@Sessions** - Reference a previous Devin session for context
@ mentions help Devin understand exactly what you're working with and reduce ambiguity in your prompts.
## Scoping Your First Session
Start with tasks that have **clear success criteria** and **provide Devin with the context it needs** — just as you would when handing off work to a teammate. As you get comfortable, try progressively more complex tasks. We've seen users work with Devin on everything from fixing small bugs to targeted refactors to large-scale migrations and building entire features from scratch.
As a rule of thumb: if a task would take you three hours or less, Devin can most likely do it. For larger projects, break them into focused sessions and run them in parallel with [managed Devins](/work-with-devin/advanced-capabilities#managed-devins).
## First-time Prompt Ideas
```Adding a new API endpoint theme={null}
Create a new endpoint /users/stats that returns a JSON object with user count and average signup age.
Use our existing users table in PostgreSQL.
You can reference the /orders/stats endpoint in statsController.js for how we structure responses.
Ensure the new endpoint is covered by the StatsController.test.js suite.
```
```Small frontend features theme={null}
In UserProfileComponent, add a dropdown that shows a list of user roles (admin, editor, viewer).
Use the styling from DropdownBase.
When a role is selected, call the existing API to set the user role.
Validate by checking that the selection updates the user role in the DB. Refer to your Knowledge for how to test properly.
```
```Write unit tests theme={null}
Add Jest tests for the AuthService methods: login and logout.
Ensure test coverage for these two functions is at least 80%.
Use UserService.test.js as an example.
After implementation, run `npm test -- --coverage` and verify the coverage report shows >80% for both functions.
Also confirm that tests pass with both valid and invalid credentials, and that logout properly clears session data.
```
```Migrating or refactoring existing code theme={null}
Migrate logger.js from JavaScript to TypeScript.
We already have a tsconfig.json and a LoggerTest.test.js suite for validation.
Make sure it compiles without errors and make sure not to change the existing config!
After migration, verify by:
1) running `tsc` to confirm no type errors
2) running the test suite with `npm test LoggerTest.test.js` to ensure all tests pass
3) checking that all existing logger method calls throughout the codebase still work without type errors.
```
```Updating APIs or database queries theme={null}
We're switching from pg to sequelize (read https://sequelize.org/api/v6/identifiers).
Please update the UserModel queries to use Sequelize methods.
Refer to OrderModel for how we do it in this codebase.
After implementation, verify by:
1) running `npm run test:integration UserModel.test.js` to check all integration tests pass
2) confirming query performance hasn't degraded by checking execution time on a test dataset of 1000 users
3) validating that all CRUD operations still maintain data integrity by running `npm run test:e2e user-flows.test.js`
```
```txt Quick PR theme={null}
## Overview
The task is to make a quick pull request to a repository.
Since this is a 'quick' PR, you will not need to run any code or test anything; simply make a PR and the user will handle the testing. Your only responsibility is reading and writing code.
## What's Needed From User
- The repository to create a pull request
## Procedure
### Prepare your workspace
1. Navigate to the relevant repository on your machine (clarify with the user if you can't figure it out).
- Check out the main branch and note down the name of the main branch.
- Checkout to a new branch since you'll be making a pull request. The name of the branch has to be of the format `devin/-`. For example `devin/1700000000-fix-popup`. Run `git remote -v && git pull && git checkout -b devin/$(date +%s)-{branch-name}` and replace `{branch-name}` with the name of the branch you want to create.
2. Study the request, codebase, and plan out the changes
- Review the most relevant files and code sections, identifying relevant snippets.
- Inform the user of your plan
### Work on the PR itself
3. Make the code changes
- Don't change anything that wasn't specifically requested by the user
4. Make the PR
- Commit and push the changes and tell the user.
- See advice section for the exact command to make the PR
- Make a pull request & review the pr to make sure it looks OK.
- Ensure all GitHub actions pass successfully & make necessary changes until they do
- Send the PR link to the user and summarize what you changed.
5. Address any feedback from the review; send the PR link again every time you make any changes
- If you need to make updates, just push more commits to the same branch; don't create a new one
## Task Specification
- PR link is included in your messages to the user
- PR was reviewed after creation
- PR does not include any stray changes
- PR does not change anything that wasn't specifically requested by the user
- PR description should include a summary of the changes, formatted as a checklist
- PR description should mention that the code was written without testing, and include - [ ] Test the changes as an item
- PR description should include the following footer: "This PR was written by [Devin](https://devin.ai/) :angel:"
- PR description should include any metadata that the user has provided (e.g. linear ticket tags in the appropriate syntax)
- PR description should not be malformatted (use --body-file instead of --body if the newlines are garbled!)
## Forbidden Actions
- Do NOT try to access github.com through the browser, you will not be authenticated.
- NEVER force push on branches! Prefer merging over rebasing so that you don't lose any work.
- Do NOT push directly to the main branch.
## Advice and Pointers
- Double check the name of the main branch (which could be `main` or `master`) using `git branch`.
- For repos with CI/CD on github actions, you can check build logs using the gh cli. if you're asked to fix a build/fix lint, you should start by looking at recent build logs
- Check `git status` before committing or adding files.
- Use `git diff` to see what changes you have made before committing.
- If you're updating an existing repo, use `gh cli` to make pull requests.
- Send the PR link to the user every time you update & ask them to re-review so that it's convenient for them
- You should already be authorized to access any repositories the user tells you about. If not, ask the user for access.
```
If you'd like to dig in to some more detailed examples of what Devin can do (and how), check out our **use cases**.
Explore practical examples across engineering workflows — each includes prompts you can try immediately.
## After Your Session
Once Devin finishes, open [Session Insights](/product-guides/session-insights) and click **Generate Analysis** — you'll get a timeline of what happened, actionable feedback, and an improved prompt you can use for similar tasks in the future.
## Next Steps
Once you're comfortable with basic sessions, explore these resources to get more out of Devin:
Connect Devin to your existing tools like GitHub, Slack, Jira, and more.
Learn how to use Playbooks to implement tasks.
Add knowledge to help Devin understand your team's practices.
# Bitbucket
Source: https://docs.devinenterprise.com/integrations/bitbucket
Work with Devin directly in your Bitbucket repositories
## Why integrate Devin with Bitbucket?
Integrating Devin with your Bitbucket repositories allows Devin to create pull requests, read and respond to your PR comments, and collaborate effectively with your team. This lets Devin be a true collaborator on your engineering team.
## Prerequisites
Before setting up the Bitbucket integration, we recommend:
* **Dedicated service account** - Create a new Bitbucket account specifically for Devin (e.g., `devin@yourcompany.com`) rather than using an existing user account for cleaner access management and audit trails
Using a dedicated service account makes it easier to track Devin's activity, manage permissions, and maintain security best practices across your organization.
## Setting up the Integration
### Bitbucket Cloud
**The setup is easy!** Here's how to get started:
1. Create a new Bitbucket account specifically for Devin (just like you'd create a personal account). You'll use this account, not your personal one, during the integration process.
2. In your Devin account, go to [Settings > **Connections** > **Bitbucket**](https://app.devin.ai/settings/connections) and click "Connect".
3. You'll be redirected to Bitbucket where you should:
* Log in with the Bitbucket account you created for Devin (not your personal account)
* Grant the necessary permissions for Devin to work with your repositories
4. Once completed, you'll return to the Devin settings page where you can confirm the integration is active.
### Bitbucket Data Center
For organizations using Bitbucket Data Center (self-hosted), follow these steps:
1. Create a dedicated service account in your Bitbucket Data Center instance for Devin.
2. In your Devin account, go to [Settings > **Connections** > **Bitbucket**](https://app.devin.ai/settings/connections) and select "Bitbucket Data Center".
3. Configure the connection by providing:
* Your Bitbucket Data Center URL
* Authentication credentials for the service account
4. Grant the service account appropriate project and repository permissions in your Bitbucket Data Center instance.
5. Once configured, you'll see the integration status confirmed in your Devin settings.
## Using Devin with the Bitbucket Integration
After connecting Bitbucket, set up your repositories on [Devin's Machine](https://app.devin.ai/machine).
While Devin can see and address comments you leave on its pull requests if you ask directly, Devin will not wake up automatically to respond to these comments.
## Best Practices
* Create a dedicated Bitbucket account for Devin
* Enable branch protections on main/master branches
* Grant the service account appropriate workspace and repository permissions
# GitHub
Source: https://docs.devinenterprise.com/integrations/gh
Work with Devin directly in your repos
## Why integrate Devin with GitHub?
Integrating Devin with your GitHub organization enables Devin to create pull requests, respond to PR comments, and collaborate directly within your repositories. This allows Devin to function as a full contributor on your engineering team.
To get started, navigate to [app.devin.ai](http://app.devin.ai) > **Settings** > **Integrations** > **GitHub**, click **Add Connection**, and follow the prompts. You will select which repositories Devin can access and review the required permissions.
**Using GitHub Enterprise Server or GitHub Enterprise Cloud with Data Residency?** See the [GitHub Enterprise Server Integration guide](/enterprise/integrations/github-enterprise-server) for setup instructions.
## Setting up the Integration
You must be an admin of your GitHub organization to create and manage the Devin integration. Having trouble? Check out our [Common Issues](/admin/common-issues#i-m-unable-to-connect-my-github-organization).
1. In your Devin account at [app.devin.ai](http://app.devin.ai), navigate to **Settings** > **Integrations** > **GitHub** and click **Add Connection**.
2. If you are not already logged in to GitHub, you will be prompted to authenticate.
3. Select the GitHub organization you want to connect to Devin.
4. Choose whether to grant Devin access to **All repositories** or **Select repositories** to control which repositories Devin can access.
5. After completing the GitHub authorization, you will be redirected to Devin settings where you can confirm the integration is active.
We recommend enabling branch protection rules on your main branch to ensure all required checks pass before Devin can merge changes.
## Using Devin with the GitHub Integration
### For Core and Teams users
Once the integration is configured, you can @mention repositories directly in your prompts within the Devin web application.
### For Enterprise users
Once the integration is configured, you can delegate repositories to specific organizations from **Enterprise Settings** > **Repository Permissions**.
If you are working with a repository for the first time, we recommend completing the [development environment setup in the onboarding flow](/onboard-devin/environment) to ensure Devin has accurate, up-to-date information about your codebase.
Devin automatically responds to PR comments as long as the session has not been archived.
## Managing Devin’s Permissions in GitHub
During setup, you can grant Devin access to **all repositories** in your organization or limit access to **specific repositories**.
You can adjust repository access at any time through GitHub's settings:
1. Navigate to your GitHub organization's **Settings** > **GitHub Apps** (e.g., `https://github.com/organizations//settings/installations`)
2. Select **Configure** for the Devin.ai integration
3. Under **Repository access**, choose to grant access to all repositories or select specific repositories
4. Click **Save** to apply your changes
Devin requires the following permissions:
**Read** access to:
| Permission | Description |
| -------------------------------- | ------------------------------------------------------------------------------------------------------------- |
| `dependabot alerts` | Allow Devin to resolve dependabot alerts on your behalf (i.e. bumping dependency versions) |
| `actions` | Allow Devin to view the actions configured for a repository in order to understand if Devin’s changes pass CI |
| `deployments` | Allow Devin to view which versions of a repository were deployed |
| `metadata` | Allow Devin to view crucial metadata about a repository such as who owns it |
| `packages` | Allow Devin to view which versions of a repository were shipped as a package |
| `pages` | Allow Devin to consult pages associated with a repository, e.g. to view documentation |
| `repository security advisories` | Allow Devin to view security advisories related to a repo in order to help fix security issues |
| `members` | Allow Devin to view members of an organization |
| `webhooks` | Allow Devin to view the hooks configured for a repository, e.g. linting and type checking |
**Read** and **write** access to:
| Permission | Description |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| `checks` | Allow Devin to view and report check results for a repository in order to understand and communicate if Devin’s changes pass CI |
| `commit statuses` | Allow Devin to view and set commit statuses to indicate if a commit passes CI |
| `contents` | Allow Devin to contribute to the codebase |
| `discussions` | Allow Devin to contribute to discussions |
| `issues` | Allow Devin to open new issues |
| `pull requests` | Allow Devin to create new PRs |
| `projects` | Allow Devin to view and manage projects associated with a repository, e.g. to retrieve information about a task |
| `workflows` | Allow Devin to set up new workflows, e.g. to help configure CI/CD |
These permissions enable Devin to work in your repositories as a regular contributor—pushing branches, opening pull requests, and participating in PR discussions.
## Pull Request Templates
When Devin creates a pull request, it uses a template from your repository to structure the PR description. If you provide a template, Devin follows its format when submitting PRs to GitHub.
### Devin-specific template (recommended)
You can provide Devin with its own template without modifying your default human-facing template by adding a file named `devin_pr_template.md` in one of the supported `PULL_REQUEST_TEMPLATE` locations below. This is useful if you want Devin to include additional context, such as a reviewer checklist or a Mermaid diagram of modified files.
### Template search order
Devin searches for templates in the following order and uses the first match:
1. PULL\_REQUEST\_TEMPLATE/devin\_pr\_template.md
2. docs/PULL\_REQUEST\_TEMPLATE/devin\_pr\_template.md
3. .github/PULL\_REQUEST\_TEMPLATE/devin\_pr\_template.md
4. pull\_request\_template.md
5. docs/pull\_request\_template.md
6. .github/pull\_request\_template.md
If no template is found, Devin uses its default PR description format.
If you want Devin to use your existing `pull_request_template.md`, copy or symlink it to one of the `devin_pr_template.md` paths listed above.For more on GitHub pull request templates (supported locations, multiple templates, query parameters, etc.), see the GitHub Docs: Creating a pull request template for your repository.
### Commit Signing
To sign Devin's commits with GPG, configure the key in your [environment](/onboard-devin/environment/blueprints) so it persists across sessions. Generating the key in a session terminal will not work — every Devin session boots from a fresh copy of the machine image, so any keys created mid-session are discarded when the session ends.
GPG signing via environment config only produces **Verified** commits when Devin is the *commit author*. GitHub verifies signatures against the author identity, but in any **Commit authoring** mode where the author is the requesting user (e.g., "Co-authored", "User only", "User as author, Devin as committer"), Devin overrides `user.email` per-session with each user's own email — which won't match a single shared GPG key. Set your org's [Commit authoring](https://app.devin.ai/settings/profile) mode to **"Devin only"** or **"Devin as author, user as committer"** before relying on this setup.
Set this up at the **org-wide** layer (or **enterprise** layer, if all of your orgs need it) so that every repo gets a signed-commit configuration:
1. Create (or pick) a dedicated GitHub user account that will own both the commit author identity *and* the credentials Devin pushes with — e.g., `devin@company.com`. Using one account for both makes the signing setup straightforward; using two splits the configuration described below across both.
2. Generate a GPG key locally with that account's email as the UID, following [GitHub's instructions](https://docs.github.com/en/authentication/managing-commit-signature-verification/generating-a-new-gpg-key).
3. Upload the **public** key to the GitHub account whose verified email matches the GPG UID, under [GitHub Settings > SSH and GPG keys](https://github.com/settings/keys). GitHub verifies signatures against the *commit author* identity, not the pushing identity — the public key must live on the account that owns the email in `user.email`. (If that's the same dedicated account you're pushing as, you only need to do this once.)
4. Export the **private** key, base64-encode it, and add it (along with the matching `GIT_USER_NAME` / `GIT_USER_EMAIL`) as secrets in [Settings → Resources → Secrets](https://app.devin.ai/settings/secrets).
5. In your [org-wide environment config](https://app.devin.ai/settings/environment), import the key and enable signing on every session start. See the copy-paste [GPG commit signing example](/onboard-devin/environment/templates#gpg-commit-signing) for the full YAML.
The committer email (`user.email`) must match a UID on the GPG key, and that same email must be a verified email on the GitHub account where you uploaded the public key. If any of these three don't match, GitHub will show the commit as **Unverified** even though the signature itself is valid.
### Security Considerations
* **Branch protection:** We recommend enabling branch protection rules on your main branch to ensure all required checks pass before Devin can merge changes.
* **Organization-level permissions:** Devin uses the permissions granted at the organization level, not the permissions of the individual user running a session.
* **Consistent access:** All users with access to both the GitHub and Devin organizations share the same Devin integration permissions.
* **Repository creation:** Devin cannot create new repositories in your GitHub account.
## IP Allowlisting
If your organization requires IP allowlisting for GitHub access, add the following IP addresses:
* 100.20.50.251
* 44.238.19.62
* 52.10.84.81
* 52.183.72.253
* 20.172.46.235
* 52.159.232.99
* 4.204.199.103
* 140.232.64.0/26
These IP addresses may change in future updates. We recommend monitoring our release notes for any changes.
## Troubleshooting: GitHub organization connected to the wrong Devin organization
If your GitHub organization is already connected to a Devin organization you don't have access to, a GitHub org admin can remove the existing installation and reinstall it under a different Devin organization.
We recommend confirming with the owner of the current Devin organization before removing the installation.
1. Go to [github.com/settings/installations](https://github.com/settings/installations) and click **Configure** next to **Devin.ai Integration**.
If needed, switch to the correct GitHub organization context using the **Go to settings page** dropdown in the top right.
2. On the installation page, scroll to the **Danger zone** section and click **Uninstall** to remove the Devin.ai Integration from the GitHub organization.
3. Return to [app.devin.ai](https://app.devin.ai) and refresh the page. You can now reinstall the GitHub integration under your Devin organization.
## GitHub Integration FAQs
Yes, you can connect either a GitHub Organization or a personal GitHub account to your Devin organization. However, we recommend connecting the account that has the appropriate permissions for Devin to access the repositories your team needs.
Only users who are members of the organization that installed the GitHub integration can use it in their Devin sessions. Devin inherits access to the GitHub integration based on the user's organization membership.
Encryption keys are managed by AWS KMS and rotated periodically.
# GitLab
Source: https://docs.devinenterprise.com/integrations/gitlab
Work with Devin directly in your GitLab repositories
## Why integrate Devin with GitLab?
Integrating Devin with your GitLab repositories allows Devin to create merge requests, read and respond to your MR comments, and collaborate effectively with your team. This lets Devin be a true collaborator on your engineering team.
**Using a self-hosted GitLab instance?** We support GitLab Self-Managed for users on our Enterprise plan. Simply click the dropdown on the "Connect" button and select "Self-Hosted". See the [GitLab Self-Managed Integration guide](/enterprise/integrations/gitlab-self-managed) for full setup instructions.
## Setting up the Integration
**The setup is easy!** Here's how to get started:
1. Create a new GitLab account specifically for Devin (just like you'd create a personal account). You'll use this account, not your personal one, during the integration process.
2. In your Devin account, go to [Settings > **Connections** > **Gitlab**](https://app.devin.ai/settings/connections) and click "Connect".
3. You'll be redirected to GitLab where you should:
* Log in with the GitLab account you created for Devin (not your personal account)
* Grant the necessary permissions for Devin to work with your repositories
4. Once completed, you'll return to the Devin settings page where you can confirm the integration is active.
For GitLab on-premise (self-hosted) installations, the sync of MR status (open, merged, closed) to Devin sessions only happens once a day. This can lead to a temporarily misrepresented MR status in your session or session list until the next sync occurs.
***
## Webhook Configuration
Configuring a webhook allows Devin to automatically receive real-time notifications when specific events occur in GitLab (such as opening or updating merge requests and commenting on merge requests).
To configure the webhook:
1. In your Devin account, go to **Settings** > **Connections**
2. Locate the GitLab instance you want to configure
3. Click the **Manage** dropdown
4. Select **Configure Webhook**
5. Follow the provided commands to complete the setup
Once configured, Devin will be able to respond to GitLab events in real time rather than relying on periodic polling.
***
## Repository Permissions
### For Core and Teams users
Once the integration is configured, you can @mention repositories directly in your prompts within the Devin web application.
### For Enterprise users
Once the integration is configured, you can delegate repositories to specific organizations from **Enterprise Settings** > **Repository Permissions**.
1. Go to **Enterprise Repositories**
2. Select the correct organization
3. Open **Manage Permissions**
4. Add the relevant repositories with the appropriate **read/write** permissions
If repositories do not appear immediately after connecting, Devin refreshes the repository list periodically. You can manually refresh the repository list in Devin.
***
## User Linking
For Enterprise users with a self-hosted GitLab instance, individual users can link their personal GitLab accounts to Devin. This allows Devin to act on behalf of individual users for GitLab operations.
To link a personal GitLab account:
1. Ensure you are a member of a Devin organization with GitLab repository permissions
2. Go to **Personal Connections** in your Devin settings
3. Look for the GitLab integration
4. Select the GitLab connection and complete the linking flow
**Personal Connections only shows integrations for organizations the user belongs to.** If the GitLab integration does not appear, confirm that you are a member of a Devin organization with GitLab repository permissions.
***
## Using Devin with the GitLab Integration
After connecting GitLab, set up your repositories on [Devin's Machine](https://app.devin.ai/machine).
While Devin can see and address comments you leave on its merge and pull requests if you ask directly, Devin will not wake up automatically to respond to these comments.
## Best Practices
* Create a dedicated GitLab account for Devin
* Enable branch protections on main/master branches
* Configure the webhook for real-time event notifications
## Support
1. Create a Slack connect channel with our team at [app.devin.ai/settings/support](https://app.devin.ai/settings/support)
2. Share session links when reporting issues and provide screenshots
# Jira
Source: https://docs.devinenterprise.com/integrations/jira
Assign Jira tickets to Devin and turn them into PRs
## Setting up the integration
1. In your Devin account at app.devin.ai, go to [Settings > Connections > Jira](https://app.devin.ai/settings/connections/jira), and click "Connect".
2. You'll be redirected to Jira to review permissions and grant Devin access.
3. Once connected, configure your **playbook labels** and optionally set up **automation triggers** in the settings page.
After connecting, we recommend connecting a **service account** so Devin's comments appear as the bot, not as your personal account. See [Connecting a service account](#connecting-a-service-account) below.
## How to trigger Devin from Jira
There are four ways to start a Devin session from a Jira ticket:
### Assign the ticket to Devin
Assign the ticket to the Devin service account directly in Jira. Devin will use the **default playbook** configured in your [Jira integration settings](https://app.devin.ai/settings/connections/jira) to start working on the ticket.
### Add a playbook label
Add a playbook label (e.g. `!plan`, `!implement`, `!triage`) to the ticket. Devin will start a session using the specific playbook that matches the label. These labels correspond to the **playbook labels** configured in your integration settings. You need to create these labels manually in your Jira project — copy the label name from the integration settings.
### Add the "devin" label
Add the `devin` label to any Jira issue (you may need to create this label in your Jira project first). Devin will use the **default playbook** to start working on the ticket.
The integration uses word-boundary matching (case-insensitive), so any label containing **devin** as a standalone word will trigger it — for example, `devin`, `Devin`, `devin-workshop`, or `devin-task`. Labels where "devin" is part of a larger word, like `devinworkshop` or `devin_workshop`, will not trigger it.
### @mention Devin in a comment
Mention `@Devin` in a ticket comment with specific instructions. Devin will start a session and use your comment as the task instruction, without applying a playbook. If a session already exists for the ticket, your message will be forwarded to the existing session.
## Configuring the integration
### Session mode
The session mode toggle controls how Devin responds to Jira triggers:
* **Direct session creation** (enabled by default): Devin creates a full session and works on the issue, posting updates back to Jira.
* **Scoping only** (disabled): Devin only analyzes the ticket and posts a scoping comment with a summary, implementation plan, and confidence estimate. You can then click the provided link to start a session manually.
### Playbook labels
Playbook labels let you control which Devin [playbooks](/product-guides/using-playbooks) are available as Jira labels. When you add a playbook, its macro (e.g. `!plan`) becomes a label you can assign to Jira issues to trigger Devin with that playbook. Labels must be created manually in your Jira project — copy the label name from the integration settings.
* **Default playbook**: One playbook is marked as the default. When a ticket is triggered without a specific playbook label (e.g. with just the `devin` label or by assigning the ticket to Devin), Devin uses this default playbook.
* **Adding playbooks**: Click "Add playbook" to add additional playbooks. Only playbooks with a macro can be added.
* **Removing playbooks**: Remove a playbook to stop using its label as a trigger.
### Automation triggers
Automation triggers let Devin automatically start working on tickets when they match certain conditions, without manual assignment or labeling. You can configure triggers based on:
* **Projects**: Only trigger for tickets in specific Jira projects.
* **Labels**: Only trigger when a ticket has specific labels.
* **Statuses**: Only trigger when a ticket reaches a specific status (e.g. "To Do", "In Progress").
* **Playbook**: Optionally specify which playbook Devin should use for the triggered session.
Triggers use **edge detection**, meaning they only fire when a ticket transitions from not matching to matching the trigger conditions (e.g. when a label is added or a status changes), not for tickets that already match.
### Enterprise: Jira project mapping
For enterprise deployments with multiple Devin organizations, admins can map Jira projects to specific Devin organizations. This ensures tickets from each Jira project are routed to the correct Devin organization. A mapping is required for the Jira integration to work in enterprise setups.
## Interacting with Devin in Jira
Once Devin starts working on a ticket, it communicates back through Jira:
* **PR links**: When Devin creates a pull request, the PR URL is automatically added as a remote link on the Jira issue and posted as a comment.
* **Session link**: A direct link to the Devin session in the web app is provided so you can follow progress in real time.
* **Follow-up messages**: Mention `@Devin` in a comment to give Devin additional instructions or ask questions.
## Connecting a service account
After connecting Jira with your admin account, you can optionally connect a service account using OAuth 2.0 client credentials. This makes Devin's comments appear under a dedicated bot identity instead of your personal account.
1. In your Atlassian organization's admin settings, create an OAuth 2.0 service account with the following **Classic scopes**:
* `read:me`
* `read:jira-user`
* `read:jira-work`
* `write:jira-work`
2. Ensure the service account has the **User** application role for Jira. In [Atlassian Admin](https://admin.atlassian.com), go to **Directory > Service accounts**, select the service account, click **⋯ > Allow access**, and set the Jira role to **User**. You can also set this when first creating the service account. Without this role, the service account won't be able to access Jira resources.
3. In [Settings > Connections > Jira](https://app.devin.ai/settings/connections/jira), click **Connect service account** and enter the client ID and client secret.
# Linear
Source: https://docs.devinenterprise.com/integrations/linear
Assign Linear tickets to Devin and turn them into PRs
When you connect the Linear integration, Devin automatically has access to native Linear tools using your integration's authentication. You do not need to configure the Linear MCP separately from the [MCP Marketplace](/work-with-devin/mcp).
## Setting up the integration
1. In your Devin account at app.devin.ai, go to [Settings > Connections > Linear](https://app.devin.ai/settings/connections/linear), and click "Connect".
2. You'll be redirected to Linear to review permissions and grant Devin access. You can select which teams in Linear Devin will have access to. You can always change Devin's access directly in the Linear Apps settings later.
3. Once connected, configure your **synced playbook labels** and optionally set up **automation triggers** in the settings page.
## How to trigger Devin from Linear
There are three ways to start a Devin session from a Linear ticket:
### Assign Devin to a ticket
Assign the ticket to Devin directly in Linear. Devin will use the **default playbook** configured in your [Linear integration settings](https://app.devin.ai/settings/connections/linear) to start working on the ticket.
### Add a playbook label
Add a playbook label (e.g. `!plan`, `!implement`, `!triage`, `!review`) to the ticket. Devin will start a session using the specific playbook that matches the label. These labels are synced from your configured **synced playbook labels** in the integration settings.
### @mention Devin in a comment
Mention Devin in a ticket comment with specific instructions. Devin will start a session and use your comment as the task instruction, without applying a playbook.
## Configuring the integration
### Synced playbook labels
Playbook labels let you control which Devin [playbooks](/product-guides/using-playbooks) are available directly from Linear as labels. When you add a playbook to the synced list, its macro (e.g. `!plan`) becomes available as a Linear label in the "Devin Playbooks" label group.
* **Default playbook**: One playbook is marked as the default. When a ticket is assigned to Devin without a specific playbook label, Devin uses this default playbook. The `!plan` playbook is set as the default for new connections.
* **Adding playbooks**: Click "Add playbook" to sync additional playbooks. Only playbooks with a macro can be synced.
* **Removing playbooks**: Remove a playbook to stop syncing its label to Linear.
### Automation triggers
Automation triggers let Devin automatically start working on tickets when they match certain conditions, without manual assignment or labeling. You can configure triggers based on:
* **Teams**: Only trigger for tickets in specific Linear teams.
* **Labels**: Only trigger when a ticket has specific labels.
* **Statuses**: Only trigger when a ticket reaches a specific status (e.g. "Todo", "In Progress").
* **Playbook**: Optionally specify which playbook Devin should use for the triggered session.
Triggers use **edge detection**, meaning they only fire when a ticket transitions from not matching to matching the trigger conditions (e.g. when a label is added or a status changes), not for tickets that already match.
### Enterprise: Linear team mapping
For enterprise deployments with multiple Devin organizations, admins can map Linear teams to specific Devin organizations. This ensures tickets from each Linear team are routed to the correct Devin organization. A mapping is required for the Linear integration to work in enterprise setups.
## Interacting with Devin in Linear
Once Devin starts working on a ticket, it uses Linear's agent session interface to communicate:
* **Activity feed**: Devin posts real-time updates as it works, including commands run, files edited, and progress summaries.
* **Plan tracking**: Devin's todo list syncs to Linear's plan UI so you can see progress at a glance.
* **Follow-up messages**: Send messages in the agent session thread to give Devin additional instructions or ask questions.
* **Stop Devin**: Use the stop signal in Linear to put Devin to sleep on the current task.
* **PR links**: When Devin creates a pull request, the PR URL is automatically added to the agent session for easy access.
* **Session link**: A direct link to the Devin session in the web app is added to the agent session, along with a link to the playbook used (if applicable).
## Connecting your Linear user account
In addition to the organization-level integration, individual team members can link their Linear account to their Devin account. This allows Devin to recognize who triggered a ticket and attribute sessions to the correct user.
To connect your user account, go to [Settings > Connections > Linear](https://app.devin.ai/settings/connections/linear) and link your account in the user connection section.
# Microsoft Teams
Source: https://docs.devinenterprise.com/integrations/microsoft-teams
Chat and collaborate with Devin directly in Microsoft Teams
Tag **@Devin** in Microsoft Teams as soon as bugs, feature requests, and questions come in. Devin responds in-thread with updates and questions when it's tagged.
## Get started
### Installation
1. Go to [Settings > Connections](https://app.devin.ai/settings/connections) and select **Microsoft Teams**
2. Click "Connect"
3. You’ll be prompted to install the Devin app for Microsoft Teams in your tenant and/or target Team
4. Make sure to link your individual user. All users in your organization will need to complete this step to use Devin
5. Mention `@Devin` in a Team channel or chat to start a session
> Note: For Devin to work for each user, every individual must connect their own account in the Devin dashboard (Settings > Connections). This lets Devin associate their Microsoft Teams identity with their Devin user.
### How to use Devin from Microsoft Teams
Once you’ve installed the Microsoft Teams integration, simply trigger Devin with `@Devin` in any Team channel.
Devin will respond in-thread to your session. You can communicate back and forth just like in the regular Devin chat interface.
*Note that Devin may make mistakes. Please double-check responses.*
### Inline Teams Keywords & Functions
| Keyword | Function |
| ------------------- | -------------------------------------------------------------------------------------------- |
| `!ask` | Begin your message with !ask to get a quick codebase answer without starting a full agent |
| `!deep` | Get a deeper research answer using advanced search |
| `mute` | Prevents Devin from seeing further messages in the thread |
| `unmute` | Reverses the above |
| `(aside)`, `!aside` | Causes Devin to ignore the message (useful for commentary on Devin's run directly in-thread) |
| `sleep` | Puts Devin to sleep; to wake Devin up, send any message in the thread |
| `archive` | Puts Devin to sleep + archives the session |
| `EXIT` | Ends the session |
| `help` | Shows help message with available keywords and functions |
### Pricing
If you don't yet have a Devin account, you can learn more about pricing and plans [here](https://devin.ai/pricing).
### Privacy
Our privacy policy is available [here](https://cognition.com/privacy-policy).
### Authentication Flow
The diagram below illustrates the high-level authentication architecture for the Microsoft Teams integration, showing how authentication flows from Teams through various layers to create authenticated Devin sessions.
```mermaid theme={null}
graph TB
subgraph MSTeams ["Microsoft Teams"]
A[Teams User] --> B[Teams Channel]
B --> C[Teams Bot Framework]
C --> D[Microsoft Graph API]
end
subgraph AuthLayer ["Authentication Layer"]
E[Certificate-Based Auth] --> F[JWT Token Validation]
F --> G[Tenant ID Verification]
G --> H[User Identity Claims]
end
subgraph DevinPlat ["Devin Platform"]
I[Chat Manager] --> J[Identity Mapping Service]
J --> K[Organization Resolver]
K --> L[RBAC Authorization]
L --> M[Session Creation]
end
subgraph IdProviders ["Identity Providers"]
N[Microsoft Entra ID] --> O[SAML/SSO Provider]
O --> P[Devin Identity Store]
end
A --> E
D --> F
H --> J
N --> J
P --> L
M --> Q[Devin Session]
```
### Permissions Details
Below is a summary of the Microsoft Teams and Microsoft Graph permissions our integration requires—what each grants, why we need it, and where it's used.
> At a glance
>
> * Graph (Application, tenant-wide): discovery & installation orchestration.
> * Teams bot RSC (per Team/Chat): scoped access to messages/members/settings only where the bot is installed or present.
#### Tenant-wide Microsoft Graph (Application) Permissions
These require Admin Consent in Microsoft Entra ID. They are app-only (no user delegation).
| Permission | What it allows | Why we need it |
| --------------------------------------------------------- | -------------------------------------------- | ------------------------------------------------------------------ |
| `Organization.Read.All` | Read basic org profile | Validate the tenant where the app is being installed |
| `User.ReadBasic.All` | Read basic profiles for all users | Map member identities and resolve mentions in linked Teams |
| `AppCatalog.Read.All` | Read the Teams app catalog | Locate our app and fetch `teamsAppId` required for installation |
| `TeamsAppInstallation.ReadWriteAndConsentSelfForTeam.All` | Install/uninstall our own app; grant app RSC | Install/remove the bot in a selected Team from the Devin dashboard |
> Note: We do not use tenant-wide Graph to read message content. Message access is granted only via RSC and only where the bot is installed/present.
#### Teams Bot Resource-Specific Consent (RSC) Permissions
These are granted per Team/Chat at install time (do not apply tenant-wide).
| Permission | Scope | What it allows | Why we need it |
| --------------------------- | ------------ | --------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
| `ChannelMessage.Read.Group` | Team/Channel | Read channel messages where the app is installed | Process channel conversations (summaries, triggers, syncing) |
| `ChannelMessage.Send.Group` | Team/Channel | Send messages in channels (new posts and threaded replies) where the app is installed | Respond to messages in channel threads and proactively post updates to channels |
| `Member.Read.Group` | Team/Channel | Read team membership | Map identities, permission checks, mention routing |
| `TeamSettings.Read.Group` | Team/Channel | Read Team settings | Respect Team-level policies and tailor behavior |
| `ChatMember.Read.Chat` | Chat | Read chat participants | Address/respond correctly and support audit trails |
| `ChatMessage.Read.Chat` | Chat | Read messages in chats where the bot participates | Process prompts, context, and follow-ups |
| `ChatMessage.Send.Chat` | Chat | Send messages in 1:1 and group chats (DMs) where the bot participates; not for channels | Respond to users in DMs and group chats, post notifications, and interactive replies in chat threads |
| `ChatSettings.Read.Chat` | Chat | Read chat settings (e.g., moderation) | Align behavior with chat policies (rate limits, who can post, etc.) |
> RSC guardrails: Access is limited to the specific Team/Chat where the app is installed or participates. Removing the app from a Team/Chat revokes that access.
#### Example: Certificate-Based Authentication for Teams Discovery
The diagram below illustrates our app-only, certificate-based authentication with Microsoft Graph. Using an X.509 client certificate, the service acquires an access token and then calls Graph to list Teams (GET /v1.0/teams). This example demonstrates how Devin securely performs tenant discovery without user context.
```mermaid theme={null}
sequenceDiagram
participant S as Cognition
participant M as MSAL client
participant K as Certificate private key
participant A as Entra ID token endpoint
participant G as Microsoft Graph
S->>M: Acquire token for Graph (.default scope)
M->>M: Check token cache (tenant, scope, client)
M->>K: Build client_assertion JWT (sign with cert)
K-->M: client_assertion (signed JWT)
M->>A: POST /oauth2/v2.0/token
A-->A: Validate signature & cert thumbprint Verify app roles to Graph
A-->M: 200 access_token (aud=graph)
M-->S: Return access_token (store in cache)
S->>G: GET /v1.0/teams with Authorization: Bearer access_token
G-->S: 200 list of teams (paged via @odata.nextLink)
```
> Credential note: We use an X.509 certificate (client assertion) rather than a client secret for service-to-service authentication. This applies to Microsoft Graph calls, bot communications with the Bot Framework adapter, and any app-only API calls from the integration.
#### Complete Message Processing Flow (Teams → Cognition)
The diagram below shows the complete end-to-end flow when a user sends a message to Devin in Microsoft Teams, including token validation and bot processing.
```mermaid theme={null}
sequenceDiagram
participant U as Teams client
participant T as Teams service
participant W as Bot webhook adapter
participant J as Jwt validator
participant O as OpenID metadata & keys
participant C as Credential provider
participant B as Bot logic
U->>T: @Devin user message
T->>W: HTTP POST activity + Authorization Bearer token
note over W: Extract Authorization header and token
W->>J: Validate token
J->>O: Fetch OpenID config and signing keys
O-->J: Return JWKS keys
J->>J: Verify RS256 signature and parse claims
J-->W: Validated claims
W->>C: Check appId against credentials
C-->W: AppId recognized
W->>W: Add serviceUrl to trusted list
W->>B: Create TurnContext and call bot handler
B->>B: Execute business logic
B-->W: Outgoing activity
W->>T: Send reply via connector service
T->>U: Deliver message to user
```
> Credential note: We use an X.509 certificate (client assertion) rather than a client secret for service-to-service authentication. This applies to Microsoft Graph calls, bot communications with the Bot Framework adapter, and any app-only API calls from the integration.
#### Consent & Installation Flow
1. **Admin Consent (tenant-wide)**
* An Entra ID admin grants the Graph Application permissions listed above.
2. **App Discovery**
* The integration queries the Teams app catalog to locate our app and retrieve `teamsAppId`.
3. **Targeted Installation**
* From our dashboard, we install the bot into a specific Team.
* During installation, the RSC scopes are granted only to that Team (or to the specific Chat when invoked in a chat).
4. **Operation**
* Discovery (org/teams/channels/app catalog) uses Graph Application permissions.
* Reading/sending messages and reading members/settings rely on RSC within installed surfaces.
#### Least-Privilege Notes
* Basic readers only: `User.ReadBasic.All` (no tenant-wide message reading).
* Message content is accessed exclusively via RSC and only where the bot is installed/present.
* No mailbox, files, or calendar permissions are requested.
#### Revocation & Uninstallation
* Revoke Admin Consent: A tenant admin can remove the app’s enterprise app permissions in Entra ID.
* Uninstall from Teams: Remove the app from a Team/Chat to revoke RSC for that resource.
* Data Handling: On uninstall, our integration stops processing events for that Team/Chat and cleans up related subscriptions/links.
# Integrations Overview
Source: https://docs.devinenterprise.com/integrations/overview
Connect Devin to your existing tools and workflows
Devin integrates with the tools you already use, making it easy to incorporate AI-powered development into your existing workflows. From source control to project management to communication, Devin can work alongside your team in the platforms you rely on.
## How Integrations Work
You can connect Devin to your tools in several ways:
* **Native integrations** - Direct connections to platforms like GitHub, Slack, and Jira
* **Secrets Manager** - Store API keys and credentials securely for Devin to use
* **MCP (Model Context Protocol)** - Connect to hundreds of external tools and data sources
## Source Control
Connect Devin to your source control platform to enable repository access, pull request creation, and code contributions.
Connect your GitHub account to allow Devin to access, create pull requests and contribute to your existing repositories.
Connect GitLab to enable Devin to work with your GitLab repositories and merge requests.
Connect Bitbucket to allow Devin to access your Bitbucket repositories and create pull requests.
Connect Azure DevOps to enable Devin to work with your Azure repositories and pipelines.
## Communication
Connect Devin to your team communication platforms to start sessions and receive updates directly in your chat tools.
Connect Devin to your company Slack and kick off runs directly via Slack by tagging @Devin.
Connect Devin to Microsoft Teams and kick off runs directly via Teams by tagging @Devin.
## Project Management
Connect Devin to your project management tools to create sessions from tickets and track work automatically.
Connect Jira to allow Devin to create and update issues, track work, and integrate with your project management workflow.
Connect Linear to enable Devin to work with your Linear issues and projects.
## MCP Marketplace
The [Model Context Protocol (MCP)](/work-with-devin/mcp) allows you to connect Devin to hundreds of external tools and data sources. Browse the MCP Marketplace in Settings to enable integrations with:
* **Monitoring** - Sentry, Datadog, PagerDuty
* **Databases** - PostgreSQL, MySQL, MongoDB
* **Documentation** - Notion, Confluence
* **And many more**
Browse the MCP Marketplace to connect Devin to hundreds of external tools and data sources.
## Additional Configuration
Configure pull request templates for Devin's contributions.
Connect Devin to self-hosted source control and artifact repositories.
## API Integration
For automated workflows and programmatic access, you can use the Devin API to create sessions, retrieve results, and integrate Devin into your CI/CD pipelines.
Learn how to programmatically create sessions and retrieve structured results.
# GitHub Pull Request Templates
Source: https://docs.devinenterprise.com/integrations/pr-templates
How Devin discovers and uses GitHub-style pull request templates, including the custom Devin template filename.
# Pull Request Templates
Devin can use GitHub-style pull request templates. It looks in your repository for the first matching template file and uses it when generating or regenerating a PR description. In addition to the standard GitHub filenames, Devin also supports a Devin‑specific variant so you can give Devin a different template than your human authors use.
## 1. Discovery Order
First match wins (top to bottom):
```text theme={null}
PULL_REQUEST_TEMPLATE/DEVIN_PR_TEMPLATE.md
docs/PULL_REQUEST_TEMPLATE/DEVIN_PR_TEMPLATE.md
.github/PULL_REQUEST_TEMPLATE/DEVIN_PR_TEMPLATE.md
PULL_REQUEST_TEMPLATE/devin_pr_template.md
docs/PULL_REQUEST_TEMPLATE/devin_pr_template.md
.github/PULL_REQUEST_TEMPLATE/devin_pr_template.md
PULL_REQUEST_TEMPLATE.md
pull_request_template.md
docs/PULL_REQUEST_TEMPLATE.md
docs/pull_request_template.md
.github/PULL_REQUEST_TEMPLATE.md
.github/pull_request_template.md
```
The entries with `DEVIN_PR_TEMPLATE.md` and `devin_pr_template.md` are optional Devin‑specific overrides (both uppercase and lowercase variants are supported). If none exist, the standard `PULL_REQUEST_TEMPLATE.md` and `pull_request_template.md` locations are used. If nothing matches, Devin falls back to its built‑in default structure.
## 2. Custom Devin Template (optional)
Add a Devin‑only template by creating one of:
```text theme={null}
.github/PULL_REQUEST_TEMPLATE/DEVIN_PR_TEMPLATE.md
.github/PULL_REQUEST_TEMPLATE/devin_pr_template.md
docs/PULL_REQUEST_TEMPLATE/DEVIN_PR_TEMPLATE.md
docs/PULL_REQUEST_TEMPLATE/devin_pr_template.md
PULL_REQUEST_TEMPLATE/DEVIN_PR_TEMPLATE.md
PULL_REQUEST_TEMPLATE/devin_pr_template.md
```
Use this if you want Devin to include extra structure (e.g. risk checklist hints) without changing what humans see in their usual `PULL_REQUEST_TEMPLATE.md` or `pull_request_template.md`. Both uppercase and lowercase variants are supported.
If you prefer a single shared template, just keep (or add):
```text theme={null}
.github/pull_request_template.md
```
Placeholders and HTML comments will be cleaned up naturally.
## 3. Built‑in Default (if no file found)
If no template file exists, Devin uses an internal default with sections for:
* Summary
* Review & Testing Checklist
* (Optional) Mermaid diagram
* Notes
You do not need to copy this unless you want to customize it; supplying any of the supported files above completely replaces the default.
## 4. GitHub Reference
Devin follows GitHub’s single‑file template resolution rules. For more about GitHub PR templates (including multi‑template workflows), see [here](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-pull-request-templates).
***
Minimal setup to give Devin its own template:
```bash theme={null}
mkdir -p .github/PULL_REQUEST_TEMPLATE
echo "# [title]\n\n## Summary\n...\n" > .github/PULL_REQUEST_TEMPLATE/devin_pr_template.md
```
That’s it—open or regenerate a PR and Devin will use it.
# Self-Hosted SCM & Artifacts
Source: https://docs.devinenterprise.com/integrations/self-hosted-scm-artifacts
Connect Devin to your self-hosted source code management and artifact repositories
## Why connect Devin to self-hosted systems?
If your organization uses self-hosted source code management systems (like GitLab) or artifact repositories (like Artifactory), you can still take full advantage of Devin. By securely exposing these services to Devin's infrastructure, your team maintains control of your systems while enabling Devin to collaborate effectively with your development workflow.
## Overview
Your team can create a Network Load Balancer (NLB), allowlist Devin's static IPs, and publish a DNS record for it. This approach:
* **Limits access to a small, controlled surface area** - Only Devin's known IPs can connect
* **Takes less than a few hours** of engineering effort to set up
* **Maintains your existing infrastructure** - No need to migrate to cloud-hosted solutions
* **Provides centralized management** - Optional single load balancer for multiple services
## Prerequisites
Before setting up the integration, ensure you have:
* **Self-hosted GitLab** (or other SCM system) accessible within your network
* **Self-hosted artifact repository** (optional) such as Artifactory or Nexus
* **Network administration access** to configure firewalls, load balancers, and DNS
* **Devin's static IP addresses** - Found [here](/admin/common-issues#ip-allowlisting)
This integration is available for Enterprise plan customers. Contact [enterprise@cognition.ai](mailto:enterprise@cognition.ai) if you need assistance.
## Setup Options
You have two primary approaches for exposing your self-hosted services to Devin:
### Option 1: Direct IP Allowlisting (Recommended)
Maintain your existing self-hosted infrastructure and simply allowlist Devin's static IPs at the firewall level.
**For Source Code Management:**
1. Configure your firewall to allow inbound connections from Devin's IPs (listed [here](/admin/common-issues#ip-allowlisting))
2. Ensure your GitLab (or other SCM) instance is accessible via HTTPS
3. Provide the URL to Devin during integration setup
**For Artifact Repositories:**
1. Add Devin's IPs to your Artifactory/Nexus allowlist
2. Ensure the artifact repository is accessible via HTTPS
3. Configure appropriate credentials for Devin to access artifacts
If using a load balancer with your artifact repository, see the [Load Balancer Considerations](#load-balancer-considerations) section below for important details about IP allowlisting.
### Option 2: Centralized Load Balancer
Place multiple services behind a single Application Load Balancer (ALB) or Network Load Balancer (NLB) for centralized IP filtering.
**Benefits:**
* Single point of management for all network filtering
* Support multiple internal services with different domains
* Simplified security auditing and compliance
## Load Balancer Considerations
When choosing between Application Load Balancer (ALB) and Network Load Balancer (NLB), consider how each handles IP allowlisting:
**Application Load Balancer (ALB) - Recommended for most use cases:**
* ALB operates at Layer 7 (HTTP/HTTPS) and provides advanced routing capabilities
* Traffic goes through NAT, so your backend services see the ALB's internal IP addresses, not Devin's source IPs
* **For artifact repositories behind ALB:** You must configure IP allowlisting directly on Artifactory/Nexus since the load balancer's internal IP will be seen by the repository
* Use AWS WAF for IP filtering at the ALB level (see example below)
**Network Load Balancer (NLB) - Suitable for IP allowlisting scenarios:**
* NLB operates at Layer 4 (TCP) and preserves the original source IP addresses
* Your backend services see Devin's actual source IPs
* **For artifact repositories behind NLB:** IP allowlisting at the load balancer level is sufficient since source IPs are maintained
* Requires manual security group configuration for each IP address
While ALB is generally preferred for its flexibility and ease of management, NLB works well when you need IP allowlisting at the load balancer level without additional configuration on backend services.
## AWS Implementation Example
Here are example AWS configurations for both load balancer approaches:
### Application Load Balancer with WAF (Easier)
```bash theme={null}
# Create an IP set with Devin's static IPs
aws wafv2 create-ip-set \
--name devin-allowed-ips \
--scope REGIONAL \
--ip-address-version IPV4 \
--addresses 1.2.3.4/32 5.6.7.8/32 9.10.11.12/32 13.14.15.16/32
# Create a WAF web ACL
aws wafv2 create-web-acl \
--name devin-access-control \
--scope REGIONAL \
--default-action Block={} \
--rules file://waf-rules.json
# Associate the WAF with your ALB
aws wafv2 associate-web-acl \
--web-acl-arn arn:aws:wafv2:region:account:regional/webacl/... \
--resource-arn arn:aws:elasticloadbalancing:region:account:loadbalancer/app/...
```
Replace the IP addresses with the actual IPs from our [IP allowlisting documentation](/admin/common-issues#ip-allowlisting).
### Network Load Balancer (Manual Security Groups)
```bash theme={null}
# Add ingress rules for each Devin IP to your security group
aws ec2 authorize-security-group-ingress \
--group-id sg-xxxxxxxxx \
--protocol tcp \
--port 443 \
--cidr 1.2.3.4/32
# Repeat for each IP address
aws ec2 authorize-security-group-ingress \
--group-id sg-xxxxxxxxx \
--protocol tcp \
--port 443 \
--cidr 5.6.7.8/32
# Continue for all Devin IPs...
```
### DNS Configuration
After setting up your load balancer, create a DNS record that Devin can use:
```bash theme={null}
# Example: Point gitlab.yourcompany.com to your load balancer
# The domain will resolve to the load balancer IP, which filters traffic
# to only allow connections from Devin's allowlisted IPs
# Using AWS Route 53:
aws route53 change-resource-record-sets \
--hosted-zone-id Z1234567890ABC \
--change-batch file://dns-change.json
```
Example `dns-change.json`:
```json theme={null}
{
"Changes": [{
"Action": "CREATE",
"ResourceRecordSet": {
"Name": "gitlab.yourcompany.com",
"Type": "A",
"AliasTarget": {
"HostedZoneId": "Z215JYRZR1TBD5",
"DNSName": "your-alb-name-123456.us-west-2.elb.amazonaws.com",
"EvaluateTargetHealth": false
}
}
}]
}
```
## Integration Steps
Once your network infrastructure is configured:
1. **Test connectivity** - Verify that your services are accessible from outside your network using the configured domain
2. **Contact Devin support** - Reach out to Cognition with:
* Your self-hosted GitLab URL (e.g., `https://gitlab.yourcompany.com`)
* Your artifact repository URL (if applicable)
* Any specific authentication requirements
3. **Complete integration setup** - Work with the Devin team to finalize the connection
4. **Configure repositories** - Add your repositories to [Devin's Machine](https://app.devin.ai/machine)
Test your IP filtering configuration before providing access to Devin by attempting to connect from an IP address that's not on the allowlist. The connection should be blocked.
## Best Practices
* **Use HTTPS** - Always expose services over HTTPS with valid SSL certificates
* **Create a dedicated service account** - Set up a specific account for Devin in your GitLab/SCM system
* **Monitor access logs** - Regularly review connection logs from Devin's IPs
* **Document your setup** - Keep internal documentation of your load balancer and DNS configuration
* **Test failover** - Ensure your setup can handle load balancer or service failures gracefully
* **Regular security audits** - Periodically review which services are exposed and verify IP allowlists
## Troubleshooting
**Devin cannot connect to my self-hosted system:**
* Verify that all [Devin IP addresses](/admin/common-issues#ip-allowlisting) are allowlisted
* Check that your SSL certificate is valid and trusted
* Ensure DNS records are properly configured and propagated
* Verify your firewall rules allow HTTPS (port 443) traffic
**Authentication failures:**
* Confirm the service account credentials are correct
* Verify the service account has appropriate permissions in your SCM/artifact system
* Check for any IP-based authentication restrictions beyond the allowlist
**Performance issues:**
* Monitor your load balancer metrics for bottlenecks
* Ensure your self-hosted services have adequate resources
* Consider geographic proximity between your infrastructure and Devin's systems
## Support
For assistance with self-hosted integrations:
1. Create a Slack Connect channel with our team at [app.devin.ai/settings/support](https://app.devin.ai/settings/support)
2. Email [enterprise@cognition.ai](mailto:enterprise@cognition.ai) with your specific setup details
3. Share relevant configuration files (with sensitive data redacted) when reporting issues
# Slack
Source: https://docs.devinenterprise.com/integrations/slack
Chat and collaborate with Devin directly in your company Slack
Tag **@Devin** in Slack as soon as bugs, feature requests, and questions come in. Devin responds in-thread with updates and questions when it's tagged.
## Get started
### Installation
1. Go to [Settings > Connections > Slack](https://app.devin.ai/settings/connections/slack)
2. Click "Connect"
3. You’ll be prompted to install the Devin app for Slack in your workspace
4. Make sure to link your individual user. All users in your organization will need to complete this step to use Devin.
5. Tag @Devin in Slack to start a session
> Note: If your user account is not properly connecting, ensure that your Slack email is the same as your email in [https://app.devin.ai/settings](https://app.devin.ai/settings). If not, please authenticate the correct email on Slack.
### How to use Devin from Slack
Once you've installed the Devin integration for Slack, simply trigger Devin with @Devin in any channel. You may include attachments to your message.
Devin will respond in-thread to your session. Now, you can communicate back and forth as you would in the regular chat interface.
*Note that Devin may make mistakes. Please double-check responses.*
### Inline Slack Keywords & Functions
| Keyword | Function |
| --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `!ask` | begin your message with !ask to get a quick codebase answer without starting a full agent |
| `!deep` | get a deeper research answer using advanced search |
| `mute`, `@Devin mute` | prevents Devin from seeing further Slack messages in thread. Natural phrasings also work (e.g. "be quiet", "stop responding in this thread") |
| `unmute`, `@Devin unmute` | reverses the above (also "start responding again") |
| `(aside)`, `!aside` | causes Devin to ignore the message (useful for commenting on Devin's run directly in-thread) |
| `sleep` | puts Devin to sleep; to wake Devin up, send any message in the thread |
| `archive`, `@Devin archive` | puts Devin to sleep + archives the session |
| `EXIT` | ends the session |
| `!dana` | starts a [Data Analyst (Dana)](/work-with-devin/data-analyst) session for database queries, data analysis, and visualizations |
| `!fast` | begin your message with !fast to start the session in Fast Mode for quicker responses on simpler tasks |
| `!ultra` | begin your message with !ultra to start the session in Ultra Mode for the most complex tasks |
| `!lite` | begin your message with !lite to start the session in Lite Mode |
| `!fusion` | begin your message with !fusion to start the session in Fusion Mode |
| `!swe` | begin your message with !swe to start the session on SWE-1.7 |
| `!normal` | begin your message with !normal to switch an active session back to the default Devin mode |
| `!new` | force the session to start in a new thread instead of replying in the current one |
| `!channel #channel-name` | post the session's reply thread in a different channel (Devin must already be in it) |
| `!windows` | run the new session on a Windows VM (requires the Windows entitlement for your organization) |
| `!data` | alias for `!dana` |
| `!discovery` | only valid right after `!dana` / `!data` — catalogs the databases and schemas reachable through your connected MCP integrations |
| `unsync`, `!unsync` | stop syncing the session to the Slack thread (see [Sync sessions with Slack threads](#sync-sessions-with-slack-threads)) |
| `![macro_name]` | Attach a playbook to a Session by referencing its Macro name |
Bang commands (`!fast`, `!lite`, `!ultra`, `!fusion`, `!swe`, `!normal`, `!new`, `!channel`, `!windows`, `!dana`) are recognized anywhere in your message, not just at the beginning — `@Devin fix the bug !ultra !new` works the same as `@Devin !ultra !new fix the bug`. They can be stacked in any order, and the keywords themselves are stripped from the prompt Devin receives. A bang command inside an inline or fenced code span is treated as literal text. Sending a mode keyword in an active Devin thread switches that session's mode mid-session.
### Slash commands
| Command | What it does |
| ---------------------------- | -------------------------------------------------------------------------------------- |
| `/ask-devin [your question]` | Quick codebase answer, without starting a full session. Devin replies in a new thread. |
| `/dana [your data question]` | Starts a [Dana](/work-with-devin/data-analyst) data-analysis session. |
Run either command with no arguments (or with `help`) to get usage instructions back privately.
### Message shortcuts
Right-click (or use the ⋮ overflow menu on) any Slack message to act on it without retyping it:
* **Ask Devin about this** — uses the message as the question for a quick codebase answer, same as `/ask-devin`.
* **Create a new session** — opens a modal pre-filled with the message text, where you pick the channel to post the session in, optionally attach a [playbook](/product-guides/using-playbooks), and edit the prompt before submitting.
### Sync sessions with Slack threads
Sessions can sync bidirectionally with a Slack thread: messages you send in the webapp appear in the thread, and replies in the thread reach Devin. This means you can start a session anywhere and keep your team in the loop.
* Use the Slack toggle in the session composer to turn sync on or off for that session. The icon is colored when synced and greyed out when not.
* The first time you sync to a channel, Devin offers to make it your default so new sessions sync there automatically.
* Send `unsync` (or `!unsync`) in a synced thread to immediately stop syncing that session. Toggle sync back on in the webapp to resume.
A couple of related behaviors:
* Mentioning `@Devin` in the thread of an archived session unarchives it so you can continue the conversation.
* When Devin suggests an [environment configuration](/onboard-devin/environment/blueprint-reference) change, the Slack message includes the proposed diff and an **Apply** button so you can accept it without leaving Slack.
### Automations triggered from Slack
[Automations](/product-guides/automations) can be triggered by Slack activity — for example a reaction added to a message, or Devin monitoring a channel and jumping in when it can help — and can post run results back to a channel you designate. See the [Automations guide](/product-guides/automations) for setup.
### Turn on Slack Notifications
You can enable Slack notifications for specific runs and Devin will privately message you whenever there’s a status update. To do so, simply click "Enable Slack notifications" in the menu at the top of any run.
### Dedicated Devin channel
Set up a **#devin-runs** channel (or similar) to keep all Devin conversations in one place. This helps your team collaborate on Devin runs together and draw inspiration for different use cases from each other.
### How to Rename Devin
You may change Devin's name in your Slack workspace by going to your Slack Workspace Admin panel -> Configure apps -> Installed Apps -> Devin. Then click on App Details, and go to the Configuration tab of that page. If you scroll down you will find a section called 'Bot User' where you may change Devin's name.
### Pricing
If you don't yet have a Devin account, you can learn more about pricing and plans [here](https://devin.ai/pricing).
The AI assistant sidebar experience (app container) requires a paid Slack plan. All other Devin features — @mentions in channels and threads, `/ask-devin`, `/dana`, and message shortcuts — work on any Slack plan, including free workspaces.
### Privacy
Our privacy policy is available [here](https://cognition.com/privacy-policy).
### Permissions Details
| Permission | Description | Rationale |
| ---------------------------------------------------- | --------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `app_mentions:read` | View messages that directly mention @Devin | Devin is summoned by @mention, so it has to receive mention events |
| `assistant:write` | Act as an AI assistant in the Slack sidebar | Powers the AI assistant sidebar experience and its status updates |
| `chat:write, chat:write.customize` | Send messages as @Devin or using a customized username and avatar | Devin has to be able to respond to user requests |
| `commands` | Add shortcuts and/or slash commands that people can use | Powers `/ask-devin`, `/dana`, and the message shortcuts |
| `files:read, files:write` | Upload, edit, and delete files as Devin | Devin needs to manage files in order to send and receive attachments to/from the user |
| `channels:history, groups:history, im:history` | View messages and other content in channels, groups, and DMs that Devin is in | Devin has to access historical messages when it is launched inside of a message thread in order to retrieve the previous messages in the thread as context |
| `channels:read, groups:read, mpim:read, im:read` | View basic information about channels, private channels, group DMs, and DMs Devin has been added to | Devin needs to resolve and list the channels it can post in (for example the channel picker and `!channel`) |
| `channels:join` (optional) | Join public channels in a workspace | Lets Devin add itself to a channel an automation is configured to post in. Its absence only disables that auto-join |
| `im:write` | Start direct messages with people | Devin needs to be able to initiate DMs in order to send users notifications via Slack |
| `reactions:read, reactions:write` | View, add, and edit emoji reactions | Devin adds emojis to messages to mark runs as completed or failed, and reactions can trigger automations |
| `team:read` | View basic information about the workspace | Devin needs to map a Slack workspace to the right Devin organization |
| `users:read, users:read.email`, `users.profile:read` | View people in a workspace as well as their emails and profiles | Devin needs to be able to match Slack users with Devin users based on their email address |
We occasionally add scopes as Devin gains Slack capabilities. If your workspace's install is missing a required scope, Devin prompts an admin to reinstall the app from [Settings > Connections > Slack](https://app.devin.ai/settings/connections/slack).
# Tutorial Library
Source: https://docs.devinenterprise.com/learn-about-devin/workflows
Videos on how to use Devin by the team
Devin is the biggest single contributor to the Cognition repositories. Whether it's delegating frontend tasks, fixing bugs, or building internal tools, Devin works in all the tools where we collaborate with the rest of the team. Here are some examples of good ways to work with Devin:
* Tag Devin on a [Slack](/integrations/slack) or [Teams](/integrations/microsoft-teams) thread about a bug you're discussing with coworkers
* Delegate a task like a refactor in your IDE to save you from context switching (something you would have normally just added to your backlog)
* Kick off multiple sessions with the long tail of your todo list at the beginning of the day and return to draft PRs waiting for review around lunch
* Tag Devin on feature requests or issues raised by customers in your shared Slack or Teams channels
### Devin 2.0 IDE Walkthrough
### Interactive Planning with Devin
### DeepWiki
### Using Ask Devin for rapid codebase understanding
### Repo Setup
### Devin tackles a bug in Slack with Walden
### Silas delegates a refactor to Devin in the IDE
### Sara sends a task to Devin instead of adding to the growing Linear backlog
# AGENTS.md
Source: https://docs.devinenterprise.com/onboard-devin/agents-md
Add AGENTS.md files to provide context and instructions for Devin
Devin supports [AGENTS.md](https://agents.md/) - a simple, open standard for providing context and instructions to AI agents. Think of AGENTS.md as a README for agents.
## Creating an AGENTS.md File
Just put an `AGENTS.md` file in your project root (or anywhere else). Devin will look for the file before it starts coding.
Here's an example:
```markdown theme={null}
# AGENTS.md
## Setup Commands
- Install dependencies: `npm install`
- Start development server: `npm run dev`
- Run tests: `npm test`
- Build for production: `npm run build`
## Code Style
- Use TypeScript strict mode
- Prefer functional components in React
- Use ESLint and Prettier configurations
- Follow conventional commit format
## Testing Guidelines
- Write unit tests for all new functions
- Use Jest for testing framework
- Aim for >80% code coverage
- Run tests before committing
## Project Structure
- `/src` - Main application code
- `/tests` - Test files
- `/docs` - Documentation
- `/public` - Static assets
## Development Workflow
- Create feature branches from `main`
- Use pull requests for code review
- Squash commits before merging
- Update documentation for new features
```
We also highly recommend doing [repo setup](/onboard-devin/environment) to give Devin context on how to work with your repository.
# Devin environment setup
Source: https://docs.devinenterprise.com/onboard-devin/environment
Configure Devin's environment so sessions start with repos, tools, dependencies, environment variables, and secrets ready.
## What is Devin's environment?
Devin's environment is the workspace where Devin operates: a Linux-based virtual machine with your repositories cloned, tools installed, dependencies resolved, environment variables set, and configuration applied. It's the equivalent of a developer's laptop: the OS, the terminal, the installed toolchain, the cloned repos, and the credentials and settings those tools need.
Your environment configuration is saved as a **snapshot**: a frozen, bootable image that every session starts from. Configure it once, and every session boots into that known-good state.
## Why environment configuration matters
Devin works the same way any developer does: it clones repos, installs dependencies, runs lint, compiles code, and executes tests. To do any of that, it needs a working environment. Without one, Devin can't build your project, can't run your tests, and can't verify its own work. It would be like hiring a developer and not giving them a laptop.
Environment configuration gives Devin the tools, runtimes, credentials, environment variables, and project knowledge it needs to be productive from the first session. It also makes sessions faster: your snapshot already has repos cloned and dependencies installed, so Devin boots straight into productive work instead of setting up from scratch every time.
**This is the single highest-leverage thing you can do to improve Devin's effectiveness on your codebase.**
## How sessions work
Every session boots from a **snapshot**, a frozen, bootable image of the environment.
1. **Snapshot**: A pre-built image containing your repos, tools, and dependencies. Prepared in advance through configuration.
2. **Session**: Devin boots a fresh copy of the snapshot. Every session starts from the same clean state. Session changes don't persist back to the snapshot.
When your configuration changes, a new snapshot is built automatically. Each organization has exactly one active snapshot. Every session in that org boots from the same snapshot.
## Before you start
Before configuring Devin's environment, make sure Devin can access your repositories:
1. **Connect your SCM provider.** Go to **Settings > Connections** and connect GitHub, GitLab, Bitbucket, or Azure DevOps. Select which repositories Devin can access during setup. See the [integration guides](/integrations/overview) for detailed instructions.
That's it. Once connected, you can proceed to environment configuration.
1. **Connect your SCM provider (enterprise admin).** Go to **Enterprise Settings > Integrations** and connect your SCM provider. See [Git Integrations](/enterprise/integrations/git-integrations) for setup instructions.
2. **Grant each org access to its repos (enterprise admin).** Go to **Enterprise Settings > Repository Permissions** and assign repositories to each organization. Orgs cannot see or use repos until you explicitly grant access. See [Repository Permissions](/enterprise/integrations/git-integrations#repository-permissions).
3. **Configure the environment (org admin).** Once an org has repo access, proceed to environment configuration below.
If you skip these steps, repos won't appear when you try to add them to your environment. Devin needs repository access through your Git integration before it can clone and build.
## Set it up by asking Devin
This is the simplest way to configure Devin's environment and works for most repositories.
Start a Devin session and ask:
*"Set up your environment for this repo."*
Devin inspects your codebase and figures out which tools, runtimes, and dependencies it needs.
Devin proposes a blueprint as suggestion cards in the timeline. Review the proposed setup and approve the cards you want to use.
Devin runs a build from the approved blueprint and produces the snapshot that every session boots from.
For the full walkthrough, see [Let Devin do it](/onboard-devin/environment/blueprints#getting-started).
## Environment variables and secrets
Environment variables are part of your blueprint. Define non-sensitive values in a step's `env` field or write shared values to `$ENVRC`; see the [environment templates](/onboard-devin/environment/templates) for the `$ENVRC` and direnv patterns. Devin can infer tools and dependencies from your repository, but it cannot discover your credentials.
Store sensitive values as encrypted [Secrets](/product-guides/secrets) in the blueprint editor's **Secrets** tab, then reference them as `$VARIABLE_NAME`. Secrets are injected as environment variables during builds and sessions; see the [blueprint secrets guide](/onboard-devin/environment/blueprints#secrets) and [environment variables and secrets reference](/onboard-devin/environment/blueprint-reference#environment-variables-and-secrets).
## Choose your approach
Asking Devin is the default. If you want to author the configuration yourself, use [declarative configuration](/onboard-devin/environment/blueprints), the recommended manual path. Blueprints describe your environment, and builds automatically produce snapshots.
**Recommended manual path.** Review or edit the YAML Devin generates to control what gets installed, how dependencies are set up, and what Devin should know.
* Version controlled
* Auto-updating
* Composable across tiers
* Reproducible
## Related pages
Full field specification for blueprints: sections, GitHub Actions support, env vars, file attachments.
Copy-paste blueprints for Python, Node.js, Go, Java, Ruby, Rust, and advanced patterns.
Enterprise-wide environment management: 3-tier hierarchy, secrets, and cross-org configuration.
# Android emulator support
Source: https://docs.devinenterprise.com/onboard-devin/environment/android-emulation
Build and run Android applications on a full emulator running on Devin's own machine
Devin can build and run Android applications directly on its own machine — giving it the Android equivalent of [Computer Use](/work-with-devin/computer-use) and browser interaction. Devin can open the app, inspect behavior, reproduce issues, and verify changes in the environment where the application actually runs. Combined with [video recordings](/work-with-devin/testing-and-recordings), Devin can send you a recording as proof.
## What You Can Do
With Android emulator support enabled, Devin can handle the full mobile development loop:
Devin builds and runs your app on the emulator, then clicks through critical flows after each PR. You get a video recording that proves the feature works — watch it and merge.
Test complete user flows — login, navigation, form submission, checkout — on a real Android stack, not a mock. Devin follows the flow step-by-step and flags anything that breaks.
Verify layouts, themes, and responsiveness across screen sizes and API levels. Devin takes screenshots at key points and flags visual issues like overlapping elements or clipped text.
Reproduce issues on the emulator, capture `logcat` output, inspect behavior, trace the root cause, and push a fix — all in one session.
Building with React Native, Flutter, or Kotlin Multiplatform? Devin can test the Android side alongside your web or desktop builds in the same session.
Run Espresso or UI Automator test suites on the emulator and get results reported back, without needing a separate CI device farm or physical devices.
Verify your app across different API levels or device profiles by configuring multiple AVDs. Useful for catching compatibility issues before they reach users.
## How It Works
Android emulator support is built on the same [declarative configuration](/onboard-devin/environment/blueprints) system as the rest of Devin's environment. You add the Android SDK and emulator to your blueprint, and Devin's snapshot builds a VM with everything pre-installed. Every session boots from that snapshot with the emulator ready to go.
During a session, Devin interacts with the emulator in two ways:
| Method | What it does | When to use it |
| -------------------------- | ------------------------------------------------------------- | ------------------------------------------------------------ |
| **`adb`** (command line) | Install APKs, run tests, capture logs, take screenshots | Automated builds, instrumented tests, logcat debugging |
| **Computer Use** (desktop) | Tap, swipe, type, and navigate the emulator's screen visually | End-to-end UI testing, visual verification, video recordings |
The emulator window runs on Devin's desktop, so you can watch Devin interact with your app in real time via the **Desktop** tab in the webapp.
## Setting Up the Emulator
The easiest way to get started. Devin analyzes your Android project, installs the right SDK components, and configures the emulator for you.
Open a new session and ask Devin to set up Android emulation. For example: *"Set up an Android emulator for this repo."*
Devin proposes a blueprint with the Android SDK, build tools, and emulator configuration. Review the suggestion cards in your timeline and click **Approve**.
Once the build completes, start a new session. Ask Devin to build and run your app on the emulator to confirm everything works.
If you know exactly what SDK components and emulator configuration you need, you can write the blueprint yourself.
Go to **Settings > Environment > Blueprints** and select your Android repository.
Add the Android SDK, platform tools, emulator, and a system image to `initialize`. Add your dependency install to `maintenance`. See the [blueprint examples](#blueprint-examples) below for copy-paste templates.
Click **Save**. A build starts automatically (typically 5–15 minutes for Android due to SDK downloads). Monitor progress from **Settings > Environment > Snapshots**.
Once the build shows **Success**, start a new session. Ask Devin to launch the emulator and build your app to verify.
### What gets installed
A typical Android emulator support blueprint installs:
| Component | Purpose |
| ------------------------------- | ------------------------------------------- |
| Android SDK command-line tools | Core SDK management (`sdkmanager`) |
| Platform tools | `adb`, `fastboot` for device communication |
| Build tools | `aapt2`, `d8`, `zipalign` for building APKs |
| Android platform (e.g., API 34) | Target API level for your app |
| Emulator + system image | The virtual device itself |
Use an `x86_64` system image for best performance inside Devin's environment. ARM images work but are significantly slower under emulation.
## Using the Emulator
### On-demand testing
Ask Devin to build and run your app at any point during a session — no special syntax needed, just natural language:
* *"Build and run the app on the Android emulator"*
* *"Test the login flow on the emulator and send me a recording"*
* *"Open the settings screen on the emulator and verify the new toggle appears"*
* *"Run the Espresso tests on the emulator and show me the results"*
Devin will launch the emulator (if it isn't already running), build and run your app, and interact with it — using `adb` for programmatic actions and Computer Use for visual interactions.
### Integration with Testing & Recordings
Android emulator support plugs directly into Devin's [Testing & Recordings](/work-with-devin/testing-and-recordings) workflow. After creating a PR:
1. Devin offers to **Test the app** — click the button or ask directly
2. Devin builds and runs the app on the emulator and executes a focused test plan
3. The emulator screen is captured in a **video recording** with annotations
4. The recording is sent to you so you can watch the test and merge with confidence
This works the same way as web app testing — the only difference is that Devin interacts with the emulator window instead of Chrome.
Create a [Skill](/product-guides/skills) that tells Devin exactly how to build, launch, and test your Android app. This saves setup time on repeat sessions and ensures consistent testing. For example, include the Gradle build command, which activity to launch, and which flows to verify.
### Skill suggestions
After testing your Android app, Devin writes down what it learned — how to start the emulator, which Gradle tasks to run, how to navigate to the feature under test — and proposes creating or updating a [Skill](/product-guides/skills) via PR. You can merge the PR as-is or tweak it to refine the instructions.
Over time, this means Devin gets better at testing your Android project. Each session's learnings build on the last — so the second time Devin tests your app, it already knows how to build it, which activity to launch, and which flows matter most.
You can also prompt Devin to do this at any time (e.g., *"create a skill for how to build and test this Android app"*). See the [Skills guide](/product-guides/skills) for full details.
### Interacting via the desktop
The Android emulator runs as a window on Devin's Linux desktop. This means:
* **Devin can interact with it via Computer Use** — tapping buttons, swiping, typing text, navigating between screens
* **You can watch live** via the **Desktop** tab in the Devin webapp
* **Recordings capture the emulator screen** alongside anything else visible on Devin's desktop
For details on how desktop interaction works, see [Computer Use](/work-with-devin/computer-use).
### Using `adb`
Devin can also interact with the emulator programmatically via `adb`, which is useful for:
* **Installing APKs** — `adb install app-debug.apk`
* **Running instrumented tests** — `adb shell am instrument -w com.example.test/androidx.test.runner.AndroidJUnitRunner`
* **Capturing logs** — `adb logcat` to debug crashes or unexpected behavior
* **Taking screenshots** — `adb exec-out screencap -p > screenshot.png`
* **Simulating user input** — `adb shell input tap 500 800` for scripted interactions
Devin chooses between `adb` and Computer Use depending on the task — `adb` for speed and automation, Computer Use for visual verification and complex UI flows.
## Blueprint Examples
Copy-paste blueprints for common Android setups. Each template is self-contained — paste it into your blueprint editor and save.
```yaml theme={null}
initialize:
- name: "Install Android SDK"
run: |
export ANDROID_HOME="$HOME/android-sdk"
mkdir -p "$ANDROID_HOME/cmdline-tools"
cd "$ANDROID_HOME/cmdline-tools"
curl -fsSL https://dl.google.com/android/repository/commandlinetools-linux-11076708_latest.zip -o tools.zip
unzip -q tools.zip -d latest-tmp
mv latest-tmp/cmdline-tools "$ANDROID_HOME/cmdline-tools/latest"
rm -rf tools.zip latest-tmp
echo "export ANDROID_HOME=$ANDROID_HOME" >> ~/.bashrc
echo 'export PATH=$ANDROID_HOME/cmdline-tools/latest/bin:$ANDROID_HOME/platform-tools:$ANDROID_HOME/emulator:$PATH' >> ~/.bashrc
export PATH="$ANDROID_HOME/cmdline-tools/latest/bin:$ANDROID_HOME/platform-tools:$ANDROID_HOME/emulator:$PATH"
yes | sdkmanager --licenses > /dev/null 2>&1
sdkmanager "platform-tools" "build-tools;34.0.0" "platforms;android-34" "emulator" "system-images;android-34;google_apis;x86_64"
echo "no" | avdmanager create avd -n devin -k "system-images;android-34;google_apis;x86_64" --device "pixel_6"
maintenance: |
./gradlew assembleDebug
knowledge:
- name: build
contents: ./gradlew assembleDebug
- name: test
contents: ./gradlew test
- name: lint
contents: ./gradlew lint
- name: emulator
contents: |
Start the emulator: emulator -avd devin -no-window -no-audio -gpu swiftshader_indirect &
Wait for boot: adb wait-for-device && adb shell getprop sys.boot_completed
Install APK: adb install app/build/outputs/apk/debug/app-debug.apk
```
```yaml theme={null}
initialize:
- name: "Install Node.js"
run: |
nvm install 20
nvm use 20
- name: "Install Android SDK"
run: |
export ANDROID_HOME="$HOME/android-sdk"
mkdir -p "$ANDROID_HOME/cmdline-tools"
cd "$ANDROID_HOME/cmdline-tools"
curl -fsSL https://dl.google.com/android/repository/commandlinetools-linux-11076708_latest.zip -o tools.zip
unzip -q tools.zip -d latest-tmp
mv latest-tmp/cmdline-tools "$ANDROID_HOME/cmdline-tools/latest"
rm -rf tools.zip latest-tmp
echo "export ANDROID_HOME=$ANDROID_HOME" >> ~/.bashrc
echo 'export PATH=$ANDROID_HOME/cmdline-tools/latest/bin:$ANDROID_HOME/platform-tools:$ANDROID_HOME/emulator:$PATH' >> ~/.bashrc
export PATH="$ANDROID_HOME/cmdline-tools/latest/bin:$ANDROID_HOME/platform-tools:$ANDROID_HOME/emulator:$PATH"
yes | sdkmanager --licenses > /dev/null 2>&1
sdkmanager "platform-tools" "build-tools;34.0.0" "platforms;android-34" "emulator" "system-images;android-34;google_apis;x86_64"
echo "no" | avdmanager create avd -n devin -k "system-images;android-34;google_apis;x86_64" --device "pixel_6"
maintenance: |
npm install
cd android && ./gradlew assembleDebug
knowledge:
- name: build
contents: cd android && ./gradlew assembleDebug
- name: test
contents: npm test
- name: lint
contents: npm run lint
- name: emulator
contents: |
Start the emulator: emulator -avd devin -no-window -no-audio -gpu swiftshader_indirect &
Wait for boot: adb wait-for-device && adb shell getprop sys.boot_completed
Run on device: npx react-native run-android
```
```yaml theme={null}
initialize:
- name: "Install Flutter"
run: |
cd "$HOME"
git clone https://github.com/flutter/flutter.git -b stable --depth 1
echo 'export PATH=$HOME/flutter/bin:$PATH' >> ~/.bashrc
export PATH="$HOME/flutter/bin:$PATH"
flutter precache --android
yes | flutter doctor --android-licenses > /dev/null 2>&1
- name: "Install Android SDK"
run: |
export ANDROID_HOME="$HOME/android-sdk"
mkdir -p "$ANDROID_HOME/cmdline-tools"
cd "$ANDROID_HOME/cmdline-tools"
curl -fsSL https://dl.google.com/android/repository/commandlinetools-linux-11076708_latest.zip -o tools.zip
unzip -q tools.zip -d latest-tmp
mv latest-tmp/cmdline-tools "$ANDROID_HOME/cmdline-tools/latest"
rm -rf tools.zip latest-tmp
echo "export ANDROID_HOME=$ANDROID_HOME" >> ~/.bashrc
echo 'export PATH=$ANDROID_HOME/cmdline-tools/latest/bin:$ANDROID_HOME/platform-tools:$ANDROID_HOME/emulator:$PATH' >> ~/.bashrc
export PATH="$ANDROID_HOME/cmdline-tools/latest/bin:$ANDROID_HOME/platform-tools:$ANDROID_HOME/emulator:$PATH"
yes | sdkmanager --licenses > /dev/null 2>&1
sdkmanager "platform-tools" "build-tools;34.0.0" "platforms;android-34" "emulator" "system-images;android-34;google_apis;x86_64"
echo "no" | avdmanager create avd -n devin -k "system-images;android-34;google_apis;x86_64" --device "pixel_6"
maintenance: |
flutter pub get
knowledge:
- name: build
contents: flutter build apk --debug
- name: test
contents: flutter test
- name: lint
contents: flutter analyze
- name: emulator
contents: |
Start the emulator: emulator -avd devin -no-window -no-audio -gpu swiftshader_indirect &
Wait for boot: adb wait-for-device && adb shell getprop sys.boot_completed
Run on device: flutter run -d emulator-5554
```
```yaml theme={null}
initialize:
- name: "Install Android SDK"
run: |
export ANDROID_HOME="$HOME/android-sdk"
mkdir -p "$ANDROID_HOME/cmdline-tools"
cd "$ANDROID_HOME/cmdline-tools"
curl -fsSL https://dl.google.com/android/repository/commandlinetools-linux-11076708_latest.zip -o tools.zip
unzip -q tools.zip -d latest-tmp
mv latest-tmp/cmdline-tools "$ANDROID_HOME/cmdline-tools/latest"
rm -rf tools.zip latest-tmp
echo "export ANDROID_HOME=$ANDROID_HOME" >> ~/.bashrc
echo 'export PATH=$ANDROID_HOME/cmdline-tools/latest/bin:$ANDROID_HOME/platform-tools:$ANDROID_HOME/emulator:$PATH' >> ~/.bashrc
export PATH="$ANDROID_HOME/cmdline-tools/latest/bin:$ANDROID_HOME/platform-tools:$ANDROID_HOME/emulator:$PATH"
yes | sdkmanager --licenses > /dev/null 2>&1
sdkmanager "platform-tools" "build-tools;34.0.0" "platforms;android-34" "emulator" "system-images;android-34;google_apis;x86_64"
echo "no" | avdmanager create avd -n devin -k "system-images;android-34;google_apis;x86_64" --device "pixel_6"
maintenance: |
./gradlew :androidApp:assembleDebug
knowledge:
- name: build
contents: ./gradlew :androidApp:assembleDebug
- name: test
contents: ./gradlew allTests
- name: lint
contents: ./gradlew detekt
- name: emulator
contents: |
Start the emulator: emulator -avd devin -no-window -no-audio -gpu swiftshader_indirect &
Wait for boot: adb wait-for-device && adb shell getprop sys.boot_completed
Install APK: adb install androidApp/build/outputs/apk/debug/androidApp-debug.apk
```
## Troubleshooting
### Emulator won't start
**Common causes:** KVM not available in the VM, insufficient memory, or a missing system image.
**Fix:** Devin can attempt to configure KVM automatically when it detects the emulator needs hardware acceleration — in most cases, this resolves the issue without manual intervention. If KVM still isn't available after Devin's attempt, the emulator can fall back to software rendering mode — add `-no-accel` to the emulator launch command, though performance will be reduced. Also check that your blueprint installs the emulator and a compatible `x86_64` system image.
### Build fails with SDK errors
**Common causes:** Missing SDK components, incorrect `ANDROID_HOME` path, or Gradle can't find the right build tools version.
**Fix:** Verify that `ANDROID_HOME` is set correctly in your blueprint and that `sdkmanager` installs the platform version and build tools version your project requires. Check your project's `build.gradle` for `compileSdk`, `targetSdk`, and `buildToolsVersion` and match them in the blueprint.
### Emulator is slow
The Android emulator runs inside Devin's VM, so performance depends on the system image and rendering mode.
**Tips:**
* Use `x86_64` system images (not ARM) for hardware-accelerated emulation
* Use `-gpu swiftshader_indirect` for software rendering that doesn't require GPU passthrough
* Use `-no-window -no-audio` when Devin doesn't need the visual display (e.g., running instrumented tests via `adb`)
* Consider a lower-resolution device profile if visual fidelity isn't critical
### Devin can't interact with the emulator screen
**Common causes:** Desktop mode is not enabled, the emulator window is not visible, or the emulator is running in headless mode.
**Fix:** Ensure [Desktop mode](/work-with-devin/computer-use#how-to-enable-it) is enabled in your organization's settings. If you need Devin to visually interact with the emulator, launch it *without* the `-no-window` flag so the emulator GUI appears on Devin's desktop. Check that the emulator has fully booted (`adb shell getprop sys.boot_completed` should return `1`) before asking Devin to interact with it.
# Blueprint reference
Source: https://docs.devinenterprise.com/onboard-devin/environment/blueprint-reference
Complete field reference for blueprints: sections, step types, GitHub Actions, environment variables, secrets, and file attachments.
This is the full field reference for blueprints. For an introduction to blueprints and how they fit into Devin's environment, see [Declarative environment configuration](/onboard-devin/environment/blueprints).
A blueprint defines how Devin's environment is configured: what tools to install, how to keep dependencies up to date, and what commands Devin should know about.
## Overview
A blueprint has three core top-level sections, plus a `post-build` section for org- and enterprise-level blueprints and an optional `clone` section for repo-level blueprints:
```yaml theme={null}
initialize: ... # Install tools and runtimes
maintenance: ... # Install project dependencies
knowledge: ... # Reference info for Devin (never executed)
post-build: ... # (Org/enterprise only) Commands that run after all setup
clone: ... # (Repo-level only) Override git-clone defaults
```
| Section | Purpose | Executed? |
| ------------- | ----------------------------------------------------------------------------- | ------------------------------------------------------------------------------- |
| `initialize` | Install system tools, language runtimes, global CLIs | During full builds and for rebuilt workspaces |
| `maintenance` | Install and update project dependencies | Yes, during builds. Surfaced to the agent at session start (not auto-executed). |
| `knowledge` | Tell Devin how to lint, test, build, and other project-specific info | No, provided as reference |
| `post-build` | Commands that run after all repos are cloned and set up (org/enterprise only) | Yes, during builds — a non-zero exit code fails the build |
| `clone` | Override how the repository is cloned into the snapshot (repo-level only) | Applied during the build's clone step |
All sections are optional. You can include any combination.
`initialize` runs during full builds and for workspaces rebuilt from scratch. Results are saved in the snapshot. In a [differential build](/onboard-devin/environment/differential-builds), inherited workspaces skip `initialize`, pull the latest code, and run only `maintenance`. Write `maintenance` so it is self-contained and can run independently on top of the existing snapshot without requiring `initialize` to run immediately beforehand or relying on environment variables that `initialize` previously wrote to `$ENVRC`. At the start of every session, `maintenance` commands are **not auto-executed** — instead, they are surfaced to the agent as context so it knows which dependency commands to run if needed (e.g. after pulling latest code). Commands should still be fast and incremental. Builds run automatically when your blueprint changes and periodically (every \~24 hours).
## initialize
Use `initialize` for installing tools and runtimes that don't depend on the specific state of your code: language runtimes, system packages, global CLIs.
### Simple form
For straightforward shell commands, use a block scalar:
```yaml theme={null}
initialize: |
curl -LsSf https://astral.sh/uv/install.sh | sh
apt-get update && apt-get install -y build-essential
npm install -g pnpm
```
### Structured form
For named steps, environment variables, or GitHub Actions, use a list:
```yaml theme={null}
initialize:
- name: "Install Python 3.12"
uses: github.com/actions/setup-python@v5
with:
python-version: "3.12"
- name: "Install system packages"
run: |
apt-get update
apt-get install -y libpq-dev
- name: "Install global tools"
run: pip install uv
env:
PIP_BREAK_SYSTEM_PACKAGES: "1"
```
Both forms can be mixed. The simple form is equivalent to a single step with `run`.
### When to use initialize vs maintenance
| Put in `initialize` | Put in `maintenance` |
| ------------------------------------- | ----------------------------- |
| Language runtime installation | `npm install` / `pip install` |
| System packages (`apt-get`) | `bundle install` |
| Global CLI tools | `go mod download` |
| One-time configuration | Dependency cache updates |
| GitHub Actions (`setup-python`, etc.) | Repo-specific setup scripts |
Both sections run during full builds. In differential builds, inherited workspaces skip `initialize` and run only `maintenance` after pulling the latest code. Tools and runtimes go in `initialize`; dependency commands that track your code's lock files go in `maintenance`.
## maintenance
Use `maintenance` for dependency installation and other commands that should run after your code is cloned. These commands run during builds and are surfaced to the agent at session start so it can re-run them if dependencies have changed. This is where `npm install`, `pip install`, `uv sync`, and similar commands belong.
```yaml theme={null}
maintenance: |
npm install
pip install -r requirements.txt
```
Or in structured form:
```yaml theme={null}
maintenance:
- name: "Install npm dependencies"
run: npm install
- name: "Install Python dependencies"
run: uv sync
env:
UV_CACHE_DIR: /tmp/uv-cache
```
For repo-level blueprints, `maintenance` commands run from the repository root directory. For org-level blueprints, they run from the home directory (`~`).
## knowledge
The `knowledge` section is **not executed**. It provides reference information that Devin uses when working in your project. This is how you tell Devin the correct commands for linting, testing, building, and any other project-specific workflows.
```yaml theme={null}
knowledge:
- name: lint
contents: |
Run linting with:
npm run lint
For auto-fix:
npm run lint -- --fix
- name: test
contents: |
Run the full test suite:
npm test
Run a single test file:
npm test -- path/to/test.ts
- name: build
contents: |
npm run build
Build output goes to dist/
```
Each knowledge item has:
| Field | Type | Description |
| ---------- | ------ | ------------------------------------------------------------------ |
| `name` | string | Identifier for this knowledge item (e.g., `lint`, `test`, `build`) |
| `contents` | string | Free-form text with commands, instructions, or notes |
The `name` field is a label. By convention, `lint`, `test`, and `build` are the standard names. Devin references these when verifying its work. You can add any additional knowledge items with custom names:
```yaml theme={null}
knowledge:
- name: lint
contents: ...
- name: test
contents: ...
- name: build
contents: ...
- name: deploy
contents: |
Deploy to staging:
npm run deploy:staging
- name: database
contents: |
Run migrations:
npm run db:migrate
Seed test data:
npm run db:seed
```
## post-build
The `post-build` section is available on **organization-level and enterprise-level blueprints only** (it is not supported in repo-level blueprints). Its steps run during the build **after all repositories have been cloned and their `initialize` and `maintenance` steps have completed**, but before the health check and the snapshot image is created. This makes it the right place for cross-repo validation and health checks that need the fully assembled environment.
Because it runs late in the build with the whole environment in place, a `post-build` step can see every cloned repo and every tool installed by the enterprise, org, and repo blueprints.
```yaml theme={null}
post-build: |
# Verify the assembled environment is healthy
node --version
python --version
test -d ~/repos/my-service
```
Or in structured form:
```yaml theme={null}
post-build:
- name: "Verify toolchain"
run: |
node --version
uv --version
- name: "Smoke-test the workspace"
run: ~/repos/my-service/scripts/healthcheck.sh
```
`post-build` steps **fail the build on a non-zero exit code**. If a `post-build` step exits non-zero, the build is marked failed and no snapshot image is produced. Use this to gate snapshots on health checks — but make sure the commands are reliable so a flaky check doesn't block your builds.
`post-build` steps use the same [step types](#step-types) as `initialize` and `maintenance` (shell `run` commands and GitHub Actions `uses`), and run from the home directory (`~`).
## clone
For **repo-level blueprints**, the optional `clone` section overrides defaults used when Devin clones the repository into the snapshot. Every field is optional and falls back to a sensible default that preserves current behavior.
```yaml theme={null}
clone:
path: my-project # clone destination under ~/repos/ (default: repo short name)
ref: develop # branch or tag to check out (default: repo's default branch)
depth: 1 # 0 = full history, N = --depth N (default: 0)
tags: false # false passes --no-tags (default: true)
submodules: recursive # true / false / "recursive" (default: true)
lfs: false # false sets GIT_LFS_SKIP_SMUDGE=1 during clone (default: true)
```
| Field | Type | Default | Description |
| ------------ | --------------------- | --------------------- | ------------------------------------------------------------------------------------------------------------ |
| `path` | string | repo short name | Override the clone destination directory under `~/repos/`. Must be unique across repos in the same snapshot. |
| `ref` | string | repo's default branch | Branch or tag to check out after cloning. Commit SHAs are not supported here. |
| `depth` | int | `0` | Clone depth. `0` clones the full history; any positive value passes `--depth N` for a shallow clone. |
| `tags` | bool | `true` | When `false`, passes `--no-tags` to skip fetching git tags. |
| `submodules` | bool or `"recursive"` | `true` | `true` or `"recursive"` passes `--recurse-submodules`. `false` skips submodules entirely. |
| `lfs` | bool | `true` | When `false`, sets `GIT_LFS_SKIP_SMUDGE=1` to skip Git LFS object downloads during clone. |
`clone` only applies to **repo-level** blueprints — it controls how that specific repo is cloned into the snapshot. It has no effect in org-level or enterprise-level blueprints.
## Step types
Each step in `initialize`, `maintenance`, or `post-build` uses one of two types: shell commands (`run`) or GitHub Actions (`uses`).
### Shell commands (`run`)
Execute arbitrary shell commands in bash:
```yaml theme={null}
- name: "Install dependencies"
run: |
npm install
pip install -r requirements.txt
```
| Field | Type | Description |
| ------ | ----------------- | ----------------------------------------- |
| `name` | string (optional) | Human-readable label for the step |
| `run` | string | Shell command(s) to execute |
| `env` | map (optional) | Extra environment variables for this step |
**Execution details:**
* Commands run in bash. If any command in a multi-line script fails, the entire step stops immediately.
* Org-level blueprints execute in the home directory (`~`).
* Repo-level blueprints execute in the cloned repository root.
* Each step has a timeout of 1 hour.
* Secrets are automatically available as environment variables.
### GitHub Actions (`uses`)
Run Node.js-based GitHub Actions directly in your blueprint:
```yaml theme={null}
- name: "Install Python"
uses: github.com/actions/setup-python@v5
with:
python-version: "3.12"
```
| Field | Type | Description |
| ------ | ----------------- | ----------------------------------------- |
| `name` | string (optional) | Human-readable label for the step |
| `uses` | string | GitHub Action reference |
| `with` | map (optional) | Input parameters for the action |
| `env` | map (optional) | Extra environment variables for this step |
**Action reference format:**
```
github.com//@
github.com///@
```
The `github.com/` prefix and `@` suffix are both required. The ref is typically a version tag like `v5`.
**Commonly used actions:**
| Action | Purpose | Example `with` |
| ------------------------------------------- | ---------------- | ----------------------------------------------- |
| `github.com/actions/setup-python@v5` | Install Python | `python-version: "3.12"` |
| `github.com/actions/setup-node@v4` | Install Node.js | `node-version: "20"` |
| `github.com/actions/setup-go@v5` | Install Go | `go-version: "1.22"` |
| `github.com/actions/setup-java@v4` | Install Java/JDK | `java-version: "21"`, `distribution: "temurin"` |
| `github.com/gradle/actions/setup-gradle@v4` | Install Gradle | (none) |
| `github.com/ruby/setup-ruby@v1` | Install Ruby | `ruby-version: "3.3"` |
Only **Node.js-based** GitHub Actions are supported. Composite actions and Docker-based actions are not supported.
**How `with` values work:**
Values passed via `with` are provided to the action as inputs, following the same conventions as GitHub Actions workflows. All values are converted to strings.
```yaml theme={null}
with:
python-version: "3.12"
check-latest: true
cache: "pip"
```
**How actions propagate changes:**
Actions can modify the environment for subsequent steps. For example, `setup-python` adds the Python binary to `PATH`, which remains available for all later steps and in `maintenance`.
### run vs uses: which to use
| Use `run` when... | Use `uses` when... |
| ---------------------------------------- | ----------------------------------------------------------- |
| Installing system packages (`apt-get`) | Setting up language runtimes (Python, Node, Go, Java, Ruby) |
| Running project-specific scripts | An official GitHub Action exists for what you need |
| Configuring files or environment | You want automatic version management and caching |
| The command is simple and self-contained | You'd use the same Action in a GitHub Actions workflow |
In practice, most configurations use `uses` for language runtimes and `run` for everything else.
## Environment variables and secrets
### Step-level environment variables
Any step can define extra environment variables with the `env` field:
```yaml theme={null}
- run: pip install -r requirements.txt
env:
PIP_INDEX_URL: "https://pypi.example.com/simple/"
PIP_BREAK_SYSTEM_PACKAGES: "1"
```
These are scoped to the step and don't persist to subsequent steps.
### Cross-step environment variables (`$ENVRC`)
To propagate environment variables across steps, write them to the `$ENVRC` file:
```yaml theme={null}
- name: "Set shared variables"
run: |
echo "DATABASE_URL=postgresql://localhost:5432/myapp" >> $ENVRC
echo "APP_ENV=development" >> $ENVRC
```
Variables written to `$ENVRC` are automatically exported and available to all
subsequent steps and the Devin session produced by the current build. This works
similarly to `$GITHUB_ENV` in GitHub Actions.
This also applies to `PATH`. If you install a tool to a non-standard directory
(anything outside `/usr/bin` or `/usr/local/bin`), append it to `$ENVRC` so
subsequent steps and repo-level blueprints can find the binary:
```yaml theme={null}
- name: "Install latest direnv"
run: |
curl -sfL https://direnv.net/install.sh | bash
echo 'export PATH="$HOME/.local/bin:$PATH"' >> $ENVRC
```
A plain `export PATH=...` inside a `run:` block only affects that step's shell.
Each step starts a new shell process, so `PATH` changes that are not written to
`$ENVRC` are lost.
`uses:` actions (e.g. `actions/setup-node`) automatically propagate their `PATH`
additions to `$ENVRC` — you only need to do this manually for `run:` steps.
`$ENVRC` is reset at the start of every build, including differential builds.
Values written during one build are not available to the next build. In
particular, an inherited workspace runs only `maintenance`, so it cannot rely on
`PATH` or other variables that `initialize` wrote to `$ENVRC` in the parent
build. Configure any environment required by `maintenance` within
`maintenance` itself.
### Secrets
Secrets configured in the Devin UI (via the **Secrets** tab in each blueprint editor) are automatically injected as environment variables. You don't declare them in your blueprint. Just reference them by name (e.g., `$MY_SECRET`).
Secrets are injected before every step runs during builds **and** re-injected at the start of every session. They are scrubbed from the snapshot image itself, so credentials are never baked into saved machine images.
* **Organization secrets**: Available as environment variables in every step across all blueprints in the org. Set these in the **Secrets** tab of the org-wide blueprint editor.
* **Enterprise secrets**: Merged with org secrets (org secrets take precedence on name collisions). Available across all orgs in the enterprise.
* **Repository secrets**: Written to a per-repo file at `/run/repo_secrets/{owner/repo}/.env.secrets`. During builds, repo secrets are automatically sourced before that repo's blueprint steps run. At session time, Devin sources them when working in the repo. Configure these in the **Secrets** tab of the repository's blueprint editor.
**Build-only secrets**: Secrets marked as "build only" are available during snapshot builds but removed before the snapshot is saved. Use these for credentials needed only at build time (e.g., downloading private artifacts during `initialize`).
`maintenance` runs during builds. At session start, `maintenance` commands are surfaced to the agent (not auto-executed), so the agent may re-run them if needed. If a `maintenance` step writes secrets into config files (e.g., `~/.m2/settings.xml`, `~/.npmrc`), those files will be baked into the snapshot. Place credential-writing steps in `maintenance` (not `initialize`) so they are refreshed during periodic builds, but be aware the written files persist in the image. For maximum security, use environment variables or `$ENVRC` instead of writing credentials to disk.
### File attachments
You can upload files (like `.npmrc`, `settings.xml`, configuration files) through the blueprint editor. Uploaded files are written to `~/.files/` and an environment variable is set pointing to each file's path:
```
$FILE_SETTINGS_XML -> /home/ubuntu/.files/settings.xml
$FILE_NPMRC -> /home/ubuntu/.files/.npmrc
```
The variable name is derived from the file name: uppercase, with non-alphanumeric characters replaced by underscores, prefixed with `FILE_`.
Use file attachments in your blueprint steps:
```yaml theme={null}
maintenance:
- name: "Configure Maven"
run: |
mkdir -p ~/.m2
cp "$FILE_SETTINGS_XML" ~/.m2/settings.xml
```
## Git-backed blueprints
You can store blueprints as `.devin/blueprint.yaml` files directly in your repository, then sync them via the API or the UI. See [Git-backed blueprints](/onboard-devin/environment/git-backed-blueprints) for setup instructions and details.
## Complete example
For how blueprints compose across tiers (enterprise → org → repo), build statuses, repository states, and what triggers a rebuild, see [Builds and sessions](/onboard-devin/environment/blueprints#builds-and-sessions) on the Declarative configuration page.
### Org-wide blueprint
Shared tooling that every repo in the org needs. This runs first (after any enterprise blueprint), in the home directory.
```yaml theme={null}
initialize:
- name: "Install Node.js 20"
uses: github.com/actions/setup-node@v4
with:
node-version: "20"
- name: "Install Python 3.12 and uv"
run: |
curl -LsSf https://astral.sh/uv/install.sh | sh
- name: "Install shared tools"
run: |
npm install -g pnpm turbo
apt-get update && apt-get install -y jq ripgrep
- name: "Configure private registry"
run: |
echo "//npm.corp.example.com/:_authToken=$NPM_REGISTRY_TOKEN" >> ~/.npmrc
```
### Repo-level blueprint
Project-specific setup for a Node.js + Python monorepo. This runs after the org-wide blueprint, in the repository directory.
```yaml theme={null}
initialize:
- name: "Install Playwright browsers"
run: npx playwright install --with-deps chromium
- name: "Set up project environment variables"
run: |
echo "DATABASE_URL=postgresql://localhost:5432/myapp_dev" >> $ENVRC
echo "REDIS_URL=redis://localhost:6379" >> $ENVRC
echo "APP_ENV=development" >> $ENVRC
maintenance:
- name: "Install frontend dependencies"
run: |
cd frontend
pnpm install
- name: "Install backend dependencies"
run: |
cd backend
uv sync
- name: "Run database migrations"
run: |
cd backend
uv run alembic upgrade head
env:
DATABASE_URL: "postgresql://localhost:5432/myapp_dev"
knowledge:
- name: lint
contents: |
Frontend:
cd frontend && pnpm lint
Backend:
cd backend && uv run ruff check .
Auto-fix:
cd frontend && pnpm lint --fix
cd backend && uv run ruff check --fix .
- name: test
contents: |
Frontend unit tests:
cd frontend && pnpm test
Backend unit tests:
cd backend && uv run pytest
E2E tests (requires dev server running):
cd frontend && pnpm test:e2e
- name: build
contents: |
Frontend:
cd frontend && pnpm build
Backend:
cd backend && uv run python -m build
- name: dev-server
contents: |
Start the full development stack:
cd backend && uv run uvicorn main:app --reload &
cd frontend && pnpm dev
Frontend: http://localhost:3000
Backend API: http://localhost:8000
API docs: http://localhost:8000/docs
- name: database
contents: |
Run migrations:
cd backend && uv run alembic upgrade head
Create a new migration:
cd backend && uv run alembic revision --autogenerate -m "description"
Reset the database:
cd backend && uv run alembic downgrade base && uv run alembic upgrade head
```
# Devin environment blueprints
Source: https://docs.devinenterprise.com/onboard-devin/environment/blueprints
Blueprints describe Devin's environment; Devin can generate them from your repository, and you can review or edit them before builds create snapshots.
## Getting started
**Prerequisites**: Devin must have access to your repositories before you can configure its environment. If you haven't set up your Git integration yet, see [Before you start](/onboard-devin/environment#before-you-start) for setup steps. Enterprise users also need to grant each org access to its repos in **Enterprise Settings > Repository Permissions**.
A blueprint is the format Devin uses to describe an environment: the tools to install, dependencies to maintain, and commands it should know. Devin can generate a blueprint from your repository, and you can review or edit it whenever you want more control over the setup.
Best for most users. Devin inspects your repository, figures out which tools, runtimes, and dependencies are needed, and generates the blueprint for you. You review and approve the suggested setup before it builds.
Open a new session and ask Devin to configure the repository. For example: *"Set up your environment for this repo."*
Devin proposes a blueprint based on what it found. You'll see **suggestion cards** in your timeline. Review the proposed tools, dependencies, and commands, then click **Approve**.
Once you approve the suggestions, a build runs and produces a snapshot. Start a new session to boot from it, then ask Devin to run your lint or test commands to confirm everything works.
See the [one-prompt setup video and overview](/onboard-devin/environment#set-it-up-by-asking-devin) on the Environment hub.
Best when you know exactly what your environment needs, or want full control over every step. Faster if you already have your commands ready.
Go to **Settings > Environment > Blueprints** in your organization's sidebar.
If you don't see this option, contact your enterprise administrator to confirm that environment blueprints are enabled for your organization.
Click **Add** in the Repositories section. Select the repositories you want Devin to work with, then confirm.
Repositories added here are cloned into Devin's environment during each build. You can add more at any time.
Click on a repository to open its blueprint editor. Here's a simple example:
```yaml theme={null}
initialize: |
curl -LsSf https://astral.sh/uv/install.sh | sh
maintenance: |
uv sync
knowledge:
- name: lint
contents: uv run ruff check .
- name: test
contents: uv run pytest
```
For more languages and patterns, see the [Template library](/onboard-devin/environment/templates).
Click **Save**. A build starts automatically (typically 2–10 minutes). Monitor progress from **Settings > Environment > Snapshots** under **Current build**.
Once the build shows **Success**, start a new Devin session. Devin boots from the new snapshot with everything pre-configured. Try asking Devin to run your lint or test commands to verify the environment works.
The rest of this guide explains how the generated blueprint works and how to edit it when you want more control.
**Scenarios: growing with ACME Corp** — one repository, then multiple repositories with shared dependencies, then multiple organizations. Worked blueprints for each stage, and how to decide which tier something belongs in.
## How it works
Declarative configuration uses three concepts:
| Concept | What it is | Analogy |
| ------------- | ----------------------------------------------------------------------------------------- | -------------- |
| **Blueprint** | A YAML configuration that describes what to install and how to set up Devin's environment | Dockerfile |
| **Build** | The process that runs your blueprint, clones repos, and produces a snapshot | `docker build` |
| **Snapshot** | A frozen, bootable image of the environment that sessions start from | Docker image |
**Blueprints describe what you want.** You author them and edit them in the Settings UI.
**Builds run your blueprints to produce snapshots.** Builds run automatically when you save a blueprint and periodically (\~every 24 hours) to keep dependencies fresh.
**Snapshots are what sessions boot from.** Each organization has one active snapshot. Every session boots a fresh copy. Session changes don't persist back to the snapshot.
### Blueprint sections
A blueprint has three core sections, plus a `post-build` block for org/enterprise blueprints and an optional `clone` block for repo-level blueprints:
| Section | Purpose | When it runs |
| ------------- | ---------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
| `initialize` | Install tools, runtimes, system packages | During builds only. Results are saved in the snapshot. |
| `maintenance` | Install/update project dependencies, write credential configs | During builds. Surfaced to the agent at session start (not auto-executed). |
| `knowledge` | Reference info for Devin (lint, test, build commands) | Not executed. Loaded into Devin's context at session start. |
| `post-build` | Validate the fully assembled environment (org/enterprise only) | During builds, after all repos are cloned and set up. A non-zero exit fails the build. |
| `clone` | Override git-clone defaults for the repository (repo-level only) | Applied during the build's clone step. |
**`initialize`** is for things that only need to happen once: language runtimes, system packages, global CLI tools.
**`maintenance`** is for dependency installation that should stay current. It runs during builds and is surfaced to the agent at session start so it can re-run them if dependencies have changed (e.g. after pulling latest code). Commands are not auto-executed at session start, but should still be fast and incremental (use `npm install`, not `npm ci`).
**`knowledge`** is reference information, not executed. This is how you tell Devin the correct commands for linting, testing, and building. Keep entries lightweight and focused on executable commands.
**`post-build`** (org- and enterprise-level only) runs after every repo has been cloned and set up, right before the snapshot is saved. Use it to verify the assembled environment — e.g. check that required tools are installed or that a cross-repo smoke test passes. A non-zero exit code fails the build, so no snapshot ships without passing your checks. See [Blueprint reference → post-build](/onboard-devin/environment/blueprint-reference#post-build).
**`clone`** (repo-level only) overrides defaults Devin uses when cloning the repo into the snapshot — for example, checking out a non-default branch (`ref`), changing the clone destination (`path`), or skipping submodules or LFS objects. Every field is optional. See [Blueprint reference → clone](/onboard-devin/environment/blueprint-reference#clone) for the full field list.
**Knowledge here vs the Knowledge product feature:** The `knowledge` section in your blueprint is for short command references tied to the environment. For architecture docs, conventions, and team workflows, use the standalone [Knowledge](/product-guides/knowledge) feature instead.
**Multi-document YAML:** The blueprint editor supports multi-document YAML using the `---` separator. This lets you organize complex blueprints into logical sections within a single editor.
For the complete field specification (step types, environment variables, secrets, and file attachments), see the [Blueprint reference](/onboard-devin/environment/blueprint-reference).
### Blueprint scope
You can define blueprints at two levels:
| Level | Where to configure | What to put here |
| ---------------- | ---------------------------------------------------- | ------------------------------------------------------------------------------- |
| **Organization** | Settings > Environment > Blueprints > Org-wide setup | Tools shared across all repos: language runtimes, package managers, Docker auth |
| **Repository** | Settings > Environment > Blueprints > \[repo name] | Project-specific setup: `npm install`, lint/test/build commands |
Blueprints are **additive**: repo blueprints build on top of the org blueprint. A repo's `maintenance` can use tools installed by the org's `initialize`. If only one repo needs a tool, put it in that repo's blueprint. If every repo needs it, put it in the org blueprint.
For worked examples of choosing a tier as a codebase grows, see [Scenarios: growing with ACME Corp](/onboard-devin/environment/scenarios).
**Enterprise users:** There's a third tier, the enterprise blueprint, that applies across all organizations. See [Enterprise environment overview](/enterprise/environment-management/overview) for details.
## Builds and sessions
### The snapshot
Your organization has **one active snapshot**: a VM image with your tools, repos, and dependencies pre-installed. All configured repos are cloned and set up in that single image. Every session boots from a fresh copy.
### How builds work
A build creates a new snapshot by running your blueprints in sequence:
```
1. Enterprise blueprint, if configured (runs in ~):
a. initialize
b. maintenance
2. Org blueprint (runs in ~):
a. initialize
b. maintenance
3. Clone all repositories (up to 10 concurrent).
Each repo's blueprint may override clone defaults via the
`clone` block (branch/tag, depth, submodules, LFS, etc.).
4. For each configured repo, in the order shown in Settings
(runs in ~/repos/):
a. initialize
b. maintenance
5. post-build steps (org blueprint's first, then enterprise's; runs in ~)
6. Health check, then snapshot is saved
```
Layers are **additive**: repo-specific commands can use tools installed by the org or enterprise blueprint. Lower levels cannot override what a higher level set up. Builds typically take 5–15 minutes. Individual steps time out after 1 hour.
### How sessions work
Each session boots a **fresh copy** of the snapshot. When the session ends, all changes are discarded. At session start:
1. The latest code is pulled for the relevant repo(s).
2. `maintenance` commands (enterprise, org, and repo) are surfaced to the agent as context — **not auto-executed**. The agent may re-run them if it detects dependencies have changed since the last build.
3. That repo's `knowledge` entries are loaded into Devin's context.
**Knowledge is per-repo.** If you have 5 repos configured, Devin only sees the knowledge entries for the one it's working on.
### What triggers a build
| Trigger | Description |
| ------------------------------- | -------------------------------------------------- |
| Saving a blueprint | Creating, updating, or deleting a blueprint |
| Adding or removing a repository | Any change to the repository list |
| Adding a repository secret | New secrets require a rebuild to be available |
| Manual trigger | Clicking **Build snapshot** in the UI |
| Periodic refresh | Automatic, roughly every 24 hours |
| Devin suggestion | Devin proposes a blueprint change during a session |
Only one build runs at a time. New triggers cancel any queued build and start fresh.
### Build statuses
| Status | Meaning |
| ------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| **Success** | All steps completed. Snapshot is ready. |
| **Partial** | Some repo-level steps failed, but the snapshot is usable. Repos that succeeded work normally; repos that failed need their blueprints fixed. |
| **Failed** | Critical failure (org or enterprise setup failed). Snapshot is not usable. |
| **Cancelled** | Superseded by a newer build or manually cancelled. |
A **partial** build still produces a working snapshot. If one of five repos has a broken blueprint, the other four are fully functional.
**Build failing?** See [Troubleshooting builds](#troubleshooting-builds) for a step-by-step debugging guide.
## Managing your environment
### Repository states
Repositories appear in three states in the Environment settings:
| State | Meaning |
| -------------- | ------------------------------------------------------------------------------------ |
| **Configured** | Has a blueprint with initialize/maintenance/knowledge. Fully set up in the snapshot. |
| **Included** | Cloned into the snapshot but has no custom blueprint. Devin can access the code. |
| **Available** | Connected to the org but not added to the environment. Not cloned. |
**Included vs. configured:** An "included" repo is cloned so Devin can access the code, but has no custom setup commands. A "configured" repo has explicit initialize/maintenance/knowledge instructions.
### Secrets
Reference secrets with `$VARIABLE_NAME` syntax. Add them in the **Secrets** tab within the blueprint editor.
```yaml theme={null}
maintenance:
- name: Configure private registry
run: npm config set //registry.npmjs.org/:_authToken $NPM_TOKEN
```
Secrets are available as environment variables during builds and sessions. They are removed before the snapshot is saved, but if a command writes a secret value into a config file during `initialize`, that value persists in the snapshot. Place credential-writing steps in `maintenance` so they are refreshed during periodic builds.
For details on secret scopes and behavior, see the [Blueprint reference](/onboard-devin/environment/blueprint-reference#environment-variables-and-secrets).
### Multiple repositories
Each repo gets its own blueprint. During a build, all repos are set up in the same snapshot, cloned into separate directories with dependencies installed independently.
If two repos install different versions of a global tool or modify shared files (like `~/.bashrc`), the last one to run wins. Put shared tool installs in the org-wide blueprint to avoid conflicts.
### GitHub Actions
Instead of writing shell scripts to install tools and runtimes, you can reference GitHub Actions directly in your blueprint. Devin downloads and runs the action during the build, the same way GitHub's CI runners execute action steps.
```yaml theme={null}
initialize:
- name: Install Python 3.12
uses: github.com/actions/setup-python@v5
with:
python-version: "3.12"
```
This is especially useful for language setup actions like `setup-python`, `setup-node`, and `setup-go`, which handle version management and PATH configuration automatically.
For syntax details, examples, and limitations, see [GitHub Actions in blueprints](/onboard-devin/environment/github-actions).
### Monorepos
You can run commands in subdirectories using subshells, or create dedicated workspace-scoped blueprints for individual packages. Devin also supports per-package knowledge entries so each workspace gets its own lint, test, and build commands.
See [Workspaces and monorepos](/onboard-devin/environment/workspaces) for setup instructions and examples.
### Pinning and auto-updates
By default, Devin uses the latest successful build's snapshot. **Pinning** lets you lock to a specific build's snapshot. This is useful when a new build introduces a regression, or when you want to freeze the environment for a batch of sessions.
**To pin:** Go to **Settings > Environment > Snapshots**, find the build in history (must be `success` or `partial`, less than 7 days old), and click **Pin**. While pinned, periodic refreshes are skipped and the UI shows **Auto-updates paused**.
**To unpin:** Click **Resume auto-updates**. Devin switches to the latest successful build.
### Git-backed blueprints
You can store blueprints as `.devin/blueprint.yaml` files directly in your repository. After merging changes, call the sync API (or click Sync in the UI) to update the blueprint, then trigger a build. This gives you the same code-review workflow you use for application code, with sync automated via a CI step.
See [Git-backed blueprints](/onboard-devin/environment/git-backed-blueprints) for setup instructions and details.
## Troubleshooting builds
### Initialize step failed
**Common causes:** typo in a shell command, package not available, network timeout, incorrect GitHub Action reference.
**Fix:** Check build logs for the exact error. Update `initialize` in your blueprint and save. A new build triggers automatically.
### Repository clone failed
**Common causes:** Devin doesn't have access to the repo, repo was renamed/moved/deleted, transient network issue.
**Fix:** Verify repo access in your Git provider settings. Remove and re-add the repo if it was renamed.
### Maintenance step failed
**Common causes:** dependency conflict, missing system library, disk space exhaustion, lock file out of sync.
**Fix:** Check logs for the failing package/command. Update `maintenance` or `initialize` to install missing dependencies, or fix the lock file in your repository.
### Build timeout
Each step has a 1-hour timeout. Common causes: compiling large native dependencies from source (use pre-built binaries), downloading large artifacts, commands that hang waiting for input (all commands must be non-interactive).
### Iterating on fixes
1. Check build logs to identify the failure
2. Update the relevant blueprint
3. Save (a new build triggers automatically)
4. Monitor the new build's logs
5. Repeat until the build succeeds
You don't need to wait for a failed build to finish. Saving a new configuration cancels any queued build and starts fresh.
## Next steps
Worked examples: one repo, then multiple repos with shared dependencies, then multiple orgs.
Speed up builds by only rebuilding workspaces whose blueprints changed.
Use GitHub Actions to install languages, tools, and SDKs without writing shell scripts.
Subshells, workspace scopes, and knowledge entries for multi-package repositories.
Complete field reference: step types, environment variables, secrets, file attachments.
Copy-paste blueprints for Python, Node.js, Go, Java, Ruby, Rust, and advanced patterns.
Store blueprints in your repo as `.devin/blueprint.yaml` and sync via the API or UI.
Enterprise-wide environment management: 3-tier hierarchy, secrets, and cross-org configuration.
# Windows support
Source: https://docs.devinenterprise.com/onboard-devin/environment/windows-support
Run Devin on Windows with blueprints and sessions.
Devin supports Windows as a build and session platform. Windows environments use the same bash shell (Git Bash) as Linux, so most blueprint commands work across both platforms without modification.
Windows support is currently available on a limited basis. If you're interested in trying out Windows with Devin, please [contact us](https://cognition.com/contact) to learn more and get access.
## How it works
Windows support is built on the same [declarative configuration](/onboard-devin/environment/blueprints) system as Linux. The key difference is the `runs-on` field in your blueprint, which tells Devin which platform to build and run on.
Since both platforms use bash, you can write the same shell commands on Linux and Windows. The main differences are the file system layout and available package managers:
| Aspect | Linux (default) | Windows |
| --------------- | --------------------- | ------------------------------------------ |
| Home directory | `/home/ubuntu` | `/c/Users/Administrator` |
| Repo directory | `~/repos/` | `/c/Users/Administrator/repos/` |
| Package manager | `apt-get` | `choco` or direct installers |
## Writing Windows blueprints
### Single-platform blueprint
If your repository only targets Windows, use `runs-on: windows` at the top level:
```yaml theme={null}
runs-on: windows
initialize:
- name: "Install Node.js"
uses: github.com/actions/setup-node@v4
with:
node-version: "20"
- name: "Install build tools"
run: |
choco install visualstudio2022buildtools -y
choco install python --version=3.12 -y
maintenance: |
npm install
knowledge:
- name: lint
contents: npm run lint
- name: test
contents: npm test
- name: build
contents: npm run build
```
### Multi-platform blueprint
To build the same repository for both Linux and Windows, write each platform as a separate YAML document separated by `---`. Each document declares its own `runs-on` label. See the [Multi-document YAML](/onboard-devin/environment/blueprints#blueprint-sections) callout in the blueprint guide for background on this format.
```yaml theme={null}
runs-on: default
initialize: |
curl -LsSf https://astral.sh/uv/install.sh | sh
apt-get update && apt-get install -y build-essential
maintenance: |
uv sync
knowledge:
- name: test
contents: uv run pytest
---
runs-on: windows
initialize: |
choco install python --version=3.12 -y
maintenance: |
uv sync
knowledge:
- name: test
contents: uv run pytest
```
Each document produces a separate snapshot build for its platform. Sessions boot from the platform-specific snapshot.
The top-level YAML must be a mapping, not a sequence. Writing the example above as a single list (`- runs-on: default` / `- runs-on: windows`) is rejected by the backend with `Invalid YAML: each YAML document must be a mapping, not a sequence; use '---' to separate multiple blocks`. Use the `---` separator shown above.
## The `runs-on` field
The `runs-on` field maps to a registered machine config on your account:
| Value | Platform |
| -------------------- | ------------------------ |
| `default` or `linux` | Linux (default platform) |
| `windows` | Windows |
You can specify `runs-on` as a string or a list:
```yaml theme={null}
# Single platform
runs-on: windows
# Multiple platforms in one block (same commands run on each)
runs-on: [default, windows]
```
When a block lists multiple platforms, the build system creates one snapshot per platform using the same commands.
The list syntax runs identical commands on every platform in the list. Only use it when commands are truly cross-platform (e.g., `npm install`, `uv sync`). For platform-specific commands (like `apt-get` on Linux or `choco` on Windows), use the [multi-document format](#multi-platform-blueprint) instead — one document per platform, separated by `---`.
## Usage and cost
Windows sessions consume approximately **9% more** usage (ACUs or quota) compared to equivalent Linux sessions. For details on how usage is metered, see [Usage](/admin/billing/usage#windows-sessions).
## Windows session behavior
### Shell
Windows sessions use **Git Bash** as the default shell — the same bash shell used on Linux. Standard bash syntax works on both platforms:
```yaml theme={null}
- run: |
export MY_VAR="hello"
echo $MY_VAR
```
### Paths
Windows uses Git Bash path format (`/c/...` instead of `C:\...`):
```yaml theme={null}
# Linux paths
- run: cp config.json ~/.config/myapp/config.json
# Windows paths (Git Bash format)
- run: cp config.json /c/Users/Administrator/.config/myapp/config.json
```
### Secrets
Secrets are available as environment variables during sessions using standard bash syntax (`$SECRET_NAME`):
```yaml theme={null}
maintenance:
- name: "Configure registry"
run: |
npm config set //registry.npmjs.org/:_authToken $NPM_TOKEN
```
### File attachments
On Windows, uploaded files are written to `/c/Users/Administrator/.files/` instead of `/home/ubuntu/.files/`.
### Computer Use
[Computer Use](/work-with-devin/computer-use) is fully supported on Windows sessions. Devin gets a Windows desktop environment with Chrome, mouse, and keyboard access, so it can test web apps as well as Windows-native desktop applications (e.g. WPF and WinForms apps) and record its testing sessions.
## Blueprint tips for Windows
### Installing tools
Use `choco` (Chocolatey) or direct download scripts:
```yaml theme={null}
initialize:
- name: "Install Chocolatey packages"
run: |
choco install git -y
choco install nodejs-lts -y
choco install python --version=3.12 -y
choco install dotnet-sdk -y
```
### Common patterns
**.NET project:**
```yaml theme={null}
runs-on: windows
initialize:
- name: "Install .NET SDK"
run: |
choco install dotnet-sdk -y
maintenance: |
dotnet restore
knowledge:
- name: build
contents: dotnet build
- name: test
contents: dotnet test
- name: lint
contents: dotnet format --verify-no-changes
```
**Visual Studio / C++ project:**
```yaml theme={null}
runs-on: windows
initialize:
- name: "Install Visual Studio Build Tools"
run: |
choco install visualstudio2022buildtools -y
choco install visualstudio2022-workload-vctools -y
maintenance: |
msbuild /t:Restore MySolution.sln
knowledge:
- name: build
contents: msbuild MySolution.sln /p:Configuration=Release
- name: test
contents: vstest.console.exe bin/Release/Tests.dll
```
# Index a Repository
Source: https://docs.devinenterprise.com/onboard-devin/index-repo
Enable Ask Devin and DeepWiki by indexing your repositories
Indexing your repositories allows Devin to understand your codebase and enables powerful features like [Ask Devin](/work-with-devin/ask-devin) and [DeepWiki](/work-with-devin/deepwiki). This quick guide walks you through the indexing process.
Repository indexing is separate from [environment configuration](/onboard-devin/environment). Indexing enables code search and understanding features, while environment configuration sets up Devin's development environment.
## Index Your Repository
1. Go to [app.devin.ai](https://app.devin.ai) and ensure you're logged into your organization
2. Click on **Settings** in the sidebar to access your organization settings
3. Select the **Repositories** tab to view all connected repositories
4. Click **Index repo** on the repository you want to index
5. Select the branch(es) you want Devin to analyze
6. Wait for indexing to complete — this may take a few minutes depending on repository size
To index additional branches later, click **Manage** on any indexed repository, select a new branch, and click **Add branch**.
Once complete, you'll have access to:
* **[Ask Devin](/work-with-devin/ask-devin)** - Ask questions about your codebase and get detailed, accurate answers powered by advanced code search. You can also use Ask Devin to scope and plan tasks.
* **[DeepWiki](/work-with-devin/deepwiki)** - Explore auto-generated documentation for your repositories
For best results, index the branches your team actively develops on. This ensures Ask Devin and DeepWiki have the most up-to-date understanding of your code.
# Knowledge Onboarding
Source: https://docs.devinenterprise.com/onboard-devin/knowledge-onboarding
Knowledge is a collection of instructions and advice that Devin can reference in all sessions. Think of it as onboarding a new employee with the relevant organizational context.
## Knowledge 101
Knowledge is the best way to share codebase-level (vs. task-level) context that can help Devin when working in your codebase. A few examples of what information to put in Devin's Knowledge include code conformance practices, deployment workflows, PR naming conventions, testing workflows, how to interact with proprietary tools and more.
A few FYIs about Knowledge:
* Devin will automatically generate repo knowledge based on the existing READMEs, file structure and contents of the connected repositories. Note that if you don't give Devin access to the repo, it won't generate any associated Knowledge.
* Knowledge is retrieved based on the Trigger you set. The more specific the trigger (e.g. which file, repo or type of task the Knowledge applies to), the better the retrieval. You can find more details [here](/product-guides/knowledge#how-do-i-create-knowledge%3F).
* Devin will tell you in a session what Knowledge it used; you can see this under "Accessed Knowledge" in the session chat.
* Devin will automatically pull and update Knowledge based on specialized files in your codebase including `.rules`, `.mdc`, `.cursorrules`, `.windsurf`, `CLAUDE.md`, and `AGENTS.md`. Note that Devin won't automatically pull in more general file types like `.md`.
## Knowledge Onboarding Best Practices
It's helpful to spend a little time upfront investing in getting Devin up to speed. Much like a new hire, sharing relevant context on the codebase and workflows the engineering team follows will go a long way in making Devin more effective. Here are some recommended steps to take when you first set up Devin's Knowledge:
1. Review any auto-generated Knowledge and verify for (a) completeness and (b) accuracy.
2. If you want Devin to retrieve the Knowledge note anytime it's working on a session, make sure to pin it to all repositories. Otherwise, you can pin it to a specific repo if the information is only relevant in that context. If Knowledge isn't pinned, it will only be used when triggered so make sure your Trigger Description is clear.
3. If you don't have a centralized specialized documentation file in your codebase, we definitely recommend setting one up with a specialized file extension.
Visit the [Knowledge product guide](/product-guides/knowledge) for more details.
# Devin VPN configuration
Source: https://docs.devinenterprise.com/onboard-devin/vpn
Configure a non-MFA VPN for Devin workspaces with blueprints, file attachments, Secrets, and connection knowledge.
Devin can connect to a VPN from inside its workspace, so sessions can reach internal services such as package registries, databases, and internal Git hosts.
For enterprise systems on private networks, see the [deployment overview](/enterprise/deployment/overview) and [Dedicated SaaS private networking](/enterprise/deployment/dedicated_saas_private_networking).
## Configure a client VPN in a blueprint
For a non-MFA OpenVPN or WireGuard connection, configure the client in a blueprint:
1. Install the VPN client in `initialize`.
2. Upload the VPN profile as a blueprint [file attachment](/onboard-devin/environment/blueprint-reference#file-attachments). Devin writes attachments to `~/.files/` and exposes each path through a `$FILE_*` variable.
3. Store VPN credentials in [Secrets](/product-guides/secrets), preferably using a service account rather than a personal account.
4. Add a `knowledge` entry with the command Devin should use to connect or check the tunnel.
For complete OpenVPN and WireGuard blueprint examples, see the [VPN connection templates](/onboard-devin/environment/templates). For blueprint structure and build behavior, see [environment blueprints](/onboard-devin/environment/blueprints).
Client VPNs that require interactive MFA sign-in are not supported by this setup.
# Auto-triage
Source: https://docs.devinenterprise.com/product-guides/auto-triage
A persistent Devin that monitors your Slack channel and automatically triages incoming bugs
Auto-triage is a special type of [automation](/product-guides/automations) where a persistent Devin monitors a Slack channel and automatically investigates bugs, regressions, and incidents as they come in. Instead of manually assigning someone to look at every report, Devin watches the channel 24/7, decides what needs attention, and spawns focused sub-sessions to diagnose each issue.
Auto-triage has **long-term memory** — it accumulates context over time and learns from you via its [scratchpad](#the-scratchpad). It **intelligently deduplicates** repeated reports and **automatically routes** issues to the right code owner.
## How it works
A long-running parent Devin monitors your Slack channel and listens to every new message. It filters out noise, detects duplicates, and spawns focused child sub-devins to investigate actionable bugs. Each child reads the relevant code, traces the root cause, posts a diagnosis in the Slack thread, and tags the right code owner.
## Setting up auto-triage
1. Invite Devin to the Slack channel you want monitored (e.g. `#bugs`, `#incidents`)
2. Go to **Automations** and create a new automation using the **Triage bug reports on Slack** template
3. Select the channel and save
That's it — Devin will start watching the channel and triaging incoming messages.
Your personal Slack account must be connected in **Settings > Connections > Slack**.
## Customizing behavior
### Setup prompt
The setup prompt lets you customize how the triage Devin behaves. This is injected into the agent's instructions and influences how it handles incoming messages. Examples:
* "Focus on regressions in the payments service. For frontend bugs, tag the UI team."
* "Only investigate issues that include error logs or stack traces. Ask for more details if the report is vague."
* "When you find a root cause, always include a link to the relevant source file."
### MCP integrations
Connecting MCP integrations is highly recommended — they dramatically improve triage quality by giving Devin access to runtime data like logs, metrics, and error details.
Connect [MCP integrations](/work-with-devin/mcp) to give the triage Devin access to external tools. For example:
* **Datadog MCP** — Pull metrics, logs, and traces to correlate issues with runtime behavior
* **Sentry MCP** — Look up error details, stack traces, and affected users
* **Linear MCP** — Check for related tickets or create new ones
Enable MCP servers in **Settings > Connections > MCP servers** before setting up the automation.
## The scratchpad
The parent monitor and all child sub-devins share a persistent scratchpad. This is used to:
* Track recently triaged items (channel ID, message timestamp, reporter)
* Maintain a routing table mapping code areas to owners
* Record duplicate items so future reports can be linked to existing threads
* Store context that persists across session restarts
The scratchpad is the automation's long-term memory. The parent is primarily responsible for maintaining it, but children can read it for context and update it when they discover new information (e.g. someone says "that's not my area").
## Security
Since incoming Slack messages can contain untrusted user input (e.g. from support tickets), consider enabling a [network policy](/product-guides/automations#network-policy) to restrict outbound access for your auto-triage automation.
## Limits
Like all automations, auto-triage supports [ACU limits and invocation limits](/product-guides/automations#limits-and-safeguards) to control resource usage. Each child sub-devin spawned by the parent counts as a session against your ACU budget.
## Tips for effective auto-triage
* **Start with a focused channel.** Pick a channel dedicated to bug reports rather than a general engineering channel. Less noise means better signal.
* **Set clear expectations in the setup prompt.** Tell Devin what kinds of issues to prioritize and what to ignore.
* **Connect relevant MCP integrations.** Datadog, Sentry, and other observability tools dramatically improve triage quality by giving Devin access to runtime data.
* **Correct routing mistakes.** When Devin tags the wrong person, reply in the thread with a correction. The parent updates its routing table and gets it right next time.
# Automations
Source: https://docs.devinenterprise.com/product-guides/automations
Set up event-driven workflows that trigger Devin sessions automatically
Automations let you wire external events — Slack messages, GitHub webhooks, Linear ticket updates, schedules, and custom webhooks — to Devin sessions that start automatically. Instead of manually tagging Devin every time a bug is reported or a CI check fails, you define the trigger once and Devin handles each event as it arrives.
## Core concepts
An automation has three parts:
| Part | What it does |
| -------------- | --------------------------------------------------------------------------------------------------------------------- |
| **Trigger** | The event that fires the automation (e.g. a Slack message in `#bugs`, a GitHub CI failure, a Linear label change) |
| **Conditions** | Optional filters that narrow the trigger (e.g. only fire when the label is `bug`, only for a specific repo) |
| **Action** | What Devin does when the trigger fires — start a new session, message an existing session, or act as a triage monitor |
### Action types
| Action | Description |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Start session** | Creates a new Devin session with the prompt you define. The event payload is automatically included as context. |
| **Message session** | Sends a message to an existing, long-running Devin session — useful for feeding events into a session that maintains state. |
| **Triage Devin** | A persistent Devin that monitors a Slack channel. It watches every incoming message, decides what needs attention, and spawns child sub-devins for items that require investigation. See [Auto-triage](/product-guides/auto-triage) for details. |
| **Email notification** | Sends you an email when the automation runs — on every run, only on failures, or only on successes. |
### Trigger sources
| Source | Event types | Example use case |
| ------------ | ---------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| **Slack** | New message, reaction added | Triage bug reports in `#incidents`, react with 🚨 to start an investigation |
| **GitHub** | Issue comment, PR opened/updated, PR review, check run (CI), push | Auto-fix CI failures, respond to `/devin` comments on issues |
| **Linear** | Issue created, label added, status changed, priority changed, assigned | Triage bugs when labeled, implement tickets when assigned to Devin |
| **Schedule** | Recurring (cron-based) or one-time (run once) | Daily Sentry error sweeps, weekly dependency updates, nightly smoke tests, or a one-off task that runs at a specific future time |
| **Webhook** | Incoming HTTP request | Wire any external system (PagerDuty, Datadog, Sentry, custom tools) to Devin via a webhook URL |
A single automation can have **multiple triggers** — they act as an OR, so the automation fires when any of its triggers match. For example, you can have one automation that fires on both a GitHub CI failure and a Slack reaction.
## Creating an automation
### From the automations page
1. Navigate to **Automations** in the sidebar
2. Click **Create automation** (or use the chat input to describe what you want in natural language — Devin will generate the automation config for you)
3. Configure the trigger, conditions, and action
4. Click **Save**
### From a template
1. Navigate to **Automations** in the sidebar
2. Click **View all examples** in the top-right of the **Featured automations** box
3. Browse the template gallery — each template is a pre-configured automation for a common workflow
4. Click a template to pre-fill the editor with its trigger, action, and suggested limits
5. Customize the configuration (e.g. select your Slack channel or repo) and save
### Using natural language
On the automations page, you can describe what you want in the chat input at the bottom — for example, "When a CI check fails on my-org/my-repo, have Devin fix it and push to the same branch." Devin will generate the automation configuration for you, which you can review and save.
## Configuring triggers
### Slack triggers
Slack triggers fire when a message is posted or a reaction is added in a channel where Devin has been invited.
* **Slack message**: Fires on new messages in a specific channel. You must select the channel when configuring the trigger.
* **Slack reaction**: Fires when a specific emoji reaction is added to a message (e.g. 🚨 for incidents). You can filter by the reaction name and the channel.
Devin must be invited to the Slack channel for the trigger to work. You must also have your personal Slack account connected in **Settings > Connections > Slack**.
### GitHub triggers
GitHub triggers fire on repository events. You must select a specific repository for each trigger.
* **Issue comment**: Fires when a comment is posted on a GitHub issue. Commonly used with a `starts_with "/devin"` condition so users can type `/devin` on any issue to trigger Devin.
* **Pull request**: Fires on PR events (opened, synchronized, etc.).
* **Pull request review**: Fires when a review is submitted on a PR.
* **Pull request review comment**: Fires on individual review comments.
* **Check run (CI)**: Fires when a CI check completes. Filter by `conclusion = failure` to auto-fix broken builds.
* **Push**: Fires on pushes to a branch.
By default, GitHub automations only fire on private repositories. An admin can opt an individual GitHub connection into public repositories: in [Settings → Connections → GitHub](https://app.devin.ai/settings/connections/github), open the connection's menu and set **Automation scope** to **All installed repos**. Anyone on the internet can comment on or open a PR against a public repo, so public-repo triggers carry a higher prompt-injection risk — enable this deliberately and keep your trigger conditions narrow.
### Linear triggers
Linear triggers fire on issue events in your connected Linear workspace. You must select a team for each trigger.
* **Issue created**: Fires when a new issue is created in the selected team.
* **Label added**: Fires when a label is applied to an issue (e.g. `bug`, `devin`).
* **Status changed**: Fires when an issue's status changes (e.g. moved to "In Progress").
* **Priority changed**: Fires when an issue's priority changes.
* **Assigned**: Fires when an issue is assigned to someone.
### Schedule triggers
Schedule triggers fire on a time-based schedule — either recurring or as a single one-time run. In the trigger dropdown, expand **Schedule** and choose **Every hour**, **Every day**, **Every week**, **Run once**, or **Custom schedule**.
* **Recurring**: Set the frequency (hourly, daily, weekly) and time. Under the hood, schedules use the iCalendar RRULE format. Choose **Custom schedule** to build a custom recurrence (repeat every N minutes/hours/days/weeks/months) or enter a raw RRULE string directly (e.g. `FREQ=WEEKLY;BYDAY=MO;BYHOUR=9;BYMINUTE=0`) for more complex cadences.
* **Run once**: Fires a single time at a specific future date and time, then automatically disables itself. Useful for one-off delayed work — e.g. "wake Devin up in 12 hours to run a task." Pick the date and time (defaults to one hour from now); it must be in the future.
Times are displayed in your local timezone but stored as UTC internally.
### Webhook triggers
Webhook triggers let you connect any external system to Devin via a unique HTTPS endpoint.
1. Create an automation with a **Webhook** trigger
2. Copy the webhook URL and secret shown in the trigger configuration
3. Configure your external system (PagerDuty, Datadog, Sentry, or any custom tool) to send HTTP POST requests to this URL
4. Optionally add a **payload filter** — a regex pattern that the request body must match for the automation to fire
The webhook payload is included in the Devin session prompt as context. Payloads larger than 200 KB are automatically truncated.
#### Webhook secret
Every webhook trigger has a secret that authenticates incoming requests — calls without the correct secret are rejected. The secret is generated for you and shown when you add the webhook trigger in the automation editor.
Copy the secret when it's shown — it will not be shown again. A lost secret cannot be recovered; regenerate it instead.
Each request must include the secret in the `X-Webhook-Secret` HTTP header. For example, to test with curl:
```bash theme={null}
curl -X POST '' \
-H 'Content-Type: application/json' \
-H 'X-Webhook-Secret: ' \
-d '{"test": true}'
```
If you lose the secret or need to rotate it, open the webhook trigger in the automation editor and regenerate it. The old secret stops working immediately, so update your external system with the new value.
## Configuring actions
### Start session
The most common action. When the trigger fires, Devin starts a new session with your prompt. The event payload (e.g. the Slack message text, GitHub webhook body, or Linear ticket details) is automatically appended to the prompt so Devin has full context.
Options:
* **Prompt**: The instructions Devin follows. Write this like you would a normal Devin prompt.
* **Playbook** (optional): Use `@playbook-name` in your prompt to include a [playbook](/product-guides/using-playbooks) for additional instructions.
* **Tags** (optional): Add tags to sessions created by this automation for easy filtering.
### Message session
Sends a message to an existing, long-running Devin session. Useful when you want a single persistent session to process events over time instead of spawning a new session for each event.
You must select the target session when configuring this action.
### Triage Devin (monitor)
Creates a persistent Devin session that monitors a Slack channel. See the [Auto-triage guide](/product-guides/auto-triage) for full details on this action type.
### Email notification
Sends an email notification when the automation runs. Choose when to notify:
* **Always** — on every invocation
* **On failure** — only when the session fails or errors
* **On success** — only when the session completes successfully
## Limits and safeguards
Automations include built-in controls to prevent runaway usage:
### ACU limit
Set a maximum ACU (Agent Compute Unit) budget per session started by this automation. If Devin hits the limit, the session stops. This prevents any single invocation from consuming excessive resources.
### Invocation limit
Set a cap on how many times the automation can fire within a time window. For example, "at most 10 invocations per hour" prevents a noisy Slack channel or a flurry of CI failures from spawning dozens of sessions.
Both fields are optional — if unset, the automation runs without limits.
### Network policy
You can enable a network policy to restrict which external hosts the automation's sessions can access. This is especially important for automations that process untrusted user input (e.g. Slack messages, webhook payloads). You can add specific domains to the allowlist if Devin needs to reach external services.
## MCP integrations
Connecting MCP integrations is highly recommended — they dramatically improve automation quality by giving Devin access to runtime data like logs, metrics, and error details.
Automations work with [MCP integrations](/work-with-devin/mcp) to give Devin access to external tools. When creating an automation, the **Connections** section shows which MCP servers are recommended and their connection status.
For example, the "Daily Sentry Error Fixes" template recommends the Sentry MCP so Devin can query Sentry for unresolved errors. The "Datadog Alert Investigation" template recommends the Datadog MCP for pulling metrics and traces.
Enable MCP servers in **Settings > Connections > MCP servers** before creating automations that need them.
## Slack tool access
By default, automation sessions can read and write to the Slack channels involved in the trigger. You can grant access to additional Slack channels in the **Slack tools** section of the automation editor. This is useful when Devin needs to read from multiple channels beyond the one that triggered the automation.
## Activity and monitoring
Each automation tracks its invocation history. On the automation detail page, the **Activity** tab shows:
* Recent invocations with timestamps
* Whether each invocation succeeded or was skipped
* Links to the Devin sessions that were created
* Error messages for failed invocations
The automations list page shows a sparkline for each automation, giving you a visual overview of activity over the past 30 days.
## Enabling and disabling
Toggle an automation on or off at any time from the automations list or detail page. Disabled automations stop processing events but retain their configuration. Re-enabling an automation resumes event processing immediately.
## Templates
Devin includes a library of pre-built automation templates for common workflows:
| Template | Category | What it does |
| ----------------------------------- | ------------------ | ---------------------------------------------------------------------------------- |
| Triage Bug Reports on Slack | Monitoring | Monitors a Slack channel and auto-triages incoming bug reports |
| Daily Sentry Error Fixes | Monitoring | Pulls top unresolved Sentry errors daily and opens fix PRs |
| Datadog Alert Investigation | Monitoring | Investigates Datadog alerts posted to Slack and replies with a root-cause analysis |
| Daily Health Digest | Monitoring | Scans Datadog daily and posts a health summary to Slack |
| Stripe Failed Payment Investigation | Monitoring | Investigates failed payment alerts in Slack via the Stripe MCP |
| Weekly Analytics Health Check | Monitoring | Checks Metabase dashboards weekly for broken queries and anomalies |
| CI Failure Fixer | CI/CD | Auto-fixes failing CI checks on PRs |
| /devin Issue Fix | CI/CD | Responds to `/devin` comments on GitHub issues with a fix PR |
| CircleCI Failure Fix | CI/CD | Pulls CircleCI build logs on failure and pushes a fix |
| Customer Support Triage | Triage | Drafts responses to support messages in Slack |
| Jira Ticket to PR | Triage | Implements Jira tickets posted in Slack and opens a PR |
| Jam Bug Report Investigation | Triage | Investigates Jam recordings shared in Slack |
| Nightly QA & Smoke Tests | Maintenance | Runs E2E tests nightly and files tickets for regressions |
| Weekly Dependency Updates | Maintenance | Scans for outdated packages and opens update PRs |
| Weekly Changelog | Maintenance | Compiles merged PRs into a categorized changelog |
| Stale PR Cleanup | Maintenance | Flags PRs with no recent activity and checks for merge conflicts |
| Security Vulnerability Scan | Maintenance | Weekly CVE scan with fix PRs for critical vulnerabilities |
| Cloudflare Security Audit | Maintenance | Weekly review of Cloudflare audit logs for suspicious activity |
| Weekly Status Digest to Notion | Project Management | Compiles weekly progress into a Notion status update |
| Asana Sprint Progress Report | Project Management | Posts a daily standup summary from Asana to Slack |
| Figma Design Review on PR | Code Quality | Compares UI changes against Figma designs on PRs |
| SonarQube Quality Gate Fix | Code Quality | Fixes SonarQube quality gate violations on failing CI checks |
| Dependency Vulnerability Scanner | Security | Daily CVE scan with severity-prioritized fix PRs |
| Secret Scanner | Security | Daily scan for leaked credentials and hardcoded secrets, with fix PRs |
| Code Pattern Enforcer | Security | Compares your repo against a golden reference repo and opens alignment PRs |
| SRE Health Checker | Security | Weekly scan for deprecated APIs, missing error handling, and reliability gaps |
| OWASP Security Hardening | Security | Weekly scan for OWASP Top 10 vulnerabilities with fix PRs |
To browse all templates, open the **Automations** page in the Devin app and click **View all examples** next to "Featured automations" above the chat input (or go directly to `/automations/templates`).
# Autofix Settings - Bot Comments
Source: https://docs.devinenterprise.com/product-guides/bot-comment-settings
Control which bots Devin responds to on pull requests
## Overview
When Devin is tracking a pull request, it monitors incoming comments and responds to them automatically. By default, Devin ignores comments from bot users (such as `github-actions[bot]`, `dependabot[bot]`, or code review bots) to prevent infinite feedback loops. The **Autofix settings - bot comments** feature lets you control this behavior so Devin can automatically respond to comments from bots you trust.
This is an organization-level setting that applies to all Devin sessions within your org.
## Where to find it
Navigate to [**Settings** > **Customization**](https://app.devin.ai/customization) > **Pull request settings** > **Autofix settings - bot comments**.
Only organization admins can modify this setting.
## Available modes
### Don't respond to bot comments (default)
Devin ignores all comments from bot users on PRs. This is the safest option and prevents any risk of infinite loops between Devin and other automated tools.
### Respond to all bot comments
Devin treats bot comments exactly like human comments and processes all of them.
This mode may cause infinite loops with automated code review bots. For example, if a code review bot comments on Devin's PR, Devin responds with a code change, and the bot comments again, the cycle can repeat indefinitely. Use this mode only if you are confident your bots will not create feedback loops.
### Respond to specific bots only
You provide an allowlist of bot usernames that Devin should respond to. Devin processes comments from those bots and ignores all others. This is the recommended option for most teams because it gives you precise control.
To add a bot to the allowlist:
1. Select **Respond to specific bots only** from the dropdown.
2. Enter the bot's GitHub username in the input field (e.g., `github-actions[bot]`).
3. Click **Add**.
Bot usernames typically end in `[bot]`. You can find a bot's username by looking at who authored the comment on your pull request.
To remove a bot, click the **×** button next to its name in the allowlist.
Bot username matching is case-insensitive, so `GitHub-Actions[bot]` and `github-actions[bot]` are treated the same.
## How it works at runtime
When a bot leaves a comment on a PR that Devin is tracking, Devin checks your organization's bot comment settings:
1. **Mode is "none"** — the comment is ignored.
2. **Mode is "allowlist"** — the bot's username is checked against your allowlist. If it matches, Devin processes the comment. Otherwise, it is ignored.
3. **Mode is "all"** — the comment is processed.
If the comment passes the bot filter, it still goes through Devin's other comment processing checks (such as the comment monitoring checkbox on the PR). It is exempt from the [mention-only setting](#interaction-with-mention-only-mode).
Lint failure comments from bots (containing "lint check failed") are always processed regardless of this setting, so Devin can always respond to CI failures.
## Common use cases
* **CI bots**: Allow your CI bot so Devin can automatically fix lint errors, test failures, or build issues flagged by your pipeline.
* **Security scanners**: Allow your security scanning bot so Devin can address vulnerability reports directly.
* **Code quality tools**: Allow bots like SonarQube or Codacy so Devin can respond to code quality feedback.
## Interaction with Devin Review
[Devin Review](/work-with-devin/devin-review) posts comments on PRs as `devin-ai-integration[bot]`. Because this is a bot account, its comments are subject to your bot comment settings. Under the default mode ("Don't respond to bot comments"), Devin sessions will **not** automatically act on findings from Devin Review.
If you want Devin to automatically address issues flagged by Devin Review, either:
* Set the mode to **"Respond to specific bots only"** and add `devin-ai-integration[bot]` to the allowlist.
* Set the mode to **"Respond to all bot comments"**.
Devin Review's "No Issues Found" summary comments are always ignored regardless of this setting — only comments that report actual findings are affected.
## Interaction with mention-only mode
The bot comment filter runs first. If a bot comment passes it (mode "all", or mode "allowlist" with a matching username), the comment is processed even when the **"Only respond to PR comments that mention Devin"** setting is enabled — approved bots do not need to mention Devin.
Mention-only still applies to comments from human users, and to bot comments that the bot filter rejects.
## Tips
* Start with **"Respond to specific bots only"** and add bots one at a time. This lets you verify that each bot interacts well with Devin before adding more.
* If you notice unexpected loops, switch back to **"Don't respond to bot comments"** to stop them immediately.
* Bot users are identified by their GitHub user type (`Bot`), not by their username. Human users with `[bot]` in their name are not affected by this setting.
# Creating Playbooks
Source: https://docs.devinenterprise.com/product-guides/creating-playbooks
Build a library of reusable prompts for your organization
## What are Playbooks?
### Playbooks are easily shareable, reusable prompts for repeated tasks
A playbook is like a custom system prompt for a repeated task. For example, if you need to have many different Devin sessions that each integrate the same third-party library but in different parts of your application, you might want a Playbook.
Playbooks are also easily shareable and reusable, so once anyone succeeds with Devin, others can more easily replicate that success!
Most best practices, style guides, or other project-specific instructions should be shared with Devin by using [Knowledge](/product-guides/knowledge). We recommend reading the docs on Knowledge before creating Playbooks, to understand which method better fits your needs.
We recommend using Playbooks when:
* You or your teammates will reuse the prompt on multiple sessions.
* You find yourself repeating the same reminders to Devin
* The use case may be relevant to others — in your organization or within the Devin user community.
## Getting Started with Playbooks
Playbooks can immediately unlock Devin’s ability to contribute in a wide range of areas, but today require skill to write. Similar to prompt engineering, writing playbooks requires trial and error. The fruit of this labor, though, is a document which unlocks Devin’s ability to independently tackle complex work, from ingesting data into Redshift and performing database migrations to using diverse software and APIs: e.g. Together, Plaid, Stripe, Modal, Springboot, Odoo, and Storybook.
Consider writing your first playbook with a simple multi-step task you want Devin to tackle.
1. Create a document that outlines...
1. The outcome you want Devin to achieve
2. The steps required to get there
2. **Optional**: Add sections like **Procedure**, **Specifications**, **Advice**, **Forbidden Actions** or **Required from User**
1. **Procedure**: Outline the entire scope of the task. Include at least one step for setup, the actual task, and delivery.
2. **Specifications**: Describe postconditions - what should be true after Devin is done?
3. **Advice**: Include tips to correct Devin’s priors
4. **Forbidden Actions**: Include any action Devin should absolutely not take
5. **Required from User**: Describe any input or information required from the user
3. Create the playbook directly in the web app by clicking [Create a new Playbook](https://app.devin.ai/settings/playbooks/create). Alternatively, save a file with the file extension `.devin.md` and drag-and-drop it in the web app when starting a Devin session
You’ve successfully attached a playbook to a session if you see a blue pill appear, along with an inline component for editing the playbook before starting your session.
## Writing a Great Playbook
### Procedure
The Procedure section should...
* Have **one step per line**, each line written imperatively
* Cover the entire scope of the task
* Include at least one step for setup, the actual task, and delivery
* Aim to make the steps **Mutually Exclusive** and **Collectively Exhaustive**
* **Additional Tips**
* Procedures should help you define the order of Devin's action - like if/else/loops/goto in code
* Don’t make tasks too specific unless you really need to, this can reduce Devin’s ability to problem-solve
* Each procedure step should contain an action verb - e.g. Write, Navigate to, etc.
### Advice and Pointers
Share advice and pointers with Devin if...
* You have a preferred way of completing the tasks
* The advice applies to the entire task, or multiple steps. Advice specific to one step should be written next to that step (e.g. as a sub-bullet)
* You are correcting Devin’s priors. Advice can function like comments on pseudocode that influence its execution.
If the advice only applies to one Procedure step, write the advice under the procedure step using nested bullet points
### Specifications
The **Specifications** section can be helpful to describe the postconditions of the playbook — what should be true once Devin is done?
### What's Needed From User
Think through anything necessary but outside of Devin’s control. For example, if the user needs to provide a token or information that is not publicly available to Devin.
### Other Tips + Tactics
* Run 2+ Devins in parallel with the same playbook to quickly identify possible errors.
* If Devin needs help, chat with it to help it along. Then add to your playbook so Devin succeeds without intervention next time.
Be explicit about what the deliverable is & how Devin should communicate the fact that it’s done (e.g. what files to attach or links to share, if any)
Explore the different decisions Devin can make, and guide Devin down the most efficient path in the playbook.
* They can be the difference maker between a working playbook and a broken one.
* For example, the following can be a very good detail to include because alloy and tts-1 are probably not things Devin would've picked otherwise, and this guides Devin in a direction that is more likely to succeed!
```
3. Create request dict with model: "tts-1", voice: "alloy"
```
## Example Playbook
View example sessions using the playbook below [here](https://app.devin.ai/sessions/93f381206f44492e9fc8b236ee022877) and [here](https://app.devin.ai/sessions/eed1a18b9ce348f69e6bac84bb42d992).
## Macros
You can assign a **macro** to any playbook — a short identifier starting with `!` (e.g., `!data-tutorial`). Macros let you quickly attach a playbook to a session by typing its macro name in the prompt input. Macros can only contain letters, numbers, and hyphens, and must be unique within your organization.
## Version History
Playbooks maintain a **version history** so you can track changes over time. Each time you edit and save a playbook, a new version is created. You can view previous versions and revert to an earlier version if a recent change didn't work out as expected.
## Enterprise Playbooks
For enterprise customers, playbooks can be managed at the **enterprise level** in addition to the organization level. Enterprise playbooks are shared across all organizations in your enterprise, making it easy to standardize workflows across teams. Enterprise admins can create and manage enterprise-level playbooks from the enterprise settings.
```txt R Data Science Tutorial theme={null}
Playbook: R Data Science Tutorial
## Overview
Create a data science tutorial using an R markdown notebook.
## What’s Needed From User
- Link to a dataset (csv file attachment or kaggle link)
- Specific task to create a data science tutorial for
## Procedure
1. Download the dataset provided by the user.
- If needed, download the dataset using the Kaggle CLI - you don't need any credentials for this
2. Create an R markdown notebook titled `data_science_tutorial.Rmd`.
3. Create a `tmp.Rmd` file for writing and saving intermediate code.
4. Create 5 main sections inside the `data_science_tutorial.Rmd` file and add code from the `tmp.Rmd` file containing the following:
- Dataset Statistics. Generate a statistical summary of the dataset.
- EDA (Exploratory Data Analysis). Create a bar chart and a scatter plot for the provided data.
- Train-test split. Split the data in an 80:20 ratio. Save the training and testing data.
- Training the machine learning model. Save the model once trained.
- Inference with the saved model. Load the saved model and evaluate its performance on the test set using the metric specified by the user.
5. Once the code is written, add a short explanation for each section.
6. Convert the R markdown notebook to HTML format
7. Send the final R markdown notebook, HTML file, saved model and testing data to the user.
## Specifications
1. Send the R markdown notebook and HTML file to the user.
2. Send the saved model and testing data to the user.
## Advice and Pointers
1. Do not re-install packages if already installed.
2. Sign in to RStudio is not required to complete this task.
3. Run the entire notebook after you add code for each section.
## Forbidden Actions
1. Do not overwrite the `data_science_tutorial.Rmd` file.
```
# Devin app deployments
Source: https://docs.devinenterprise.com/product-guides/deployment-capabilities
Devin-hosted deployments for standalone apps Devin builds: static frontends on devinapps.com, FastAPI backends on Fly.io, plus approval and availability rules.
Most Devin work follows the normal software delivery path: Devin works in your repository, opens a pull request, and your team reviews, merges, and ships it through its existing pipeline. This page covers a narrower, optional path: asking Devin to build a small standalone app from scratch and host it for you, giving you a live URL for prototypes, demos, or throwaway internal tools.
If you're using Devin on an existing codebase, deployment happens through your own CI/CD pipeline, not through the hosted deployments described here. See [Existing applications](#existing-applications).
## What a deployment is
A deployment is Devin publishing an app it built to Cognition-hosted infrastructure, so the app stays reachable at a public URL after the session ends. Devin can deploy two things:
* **Static frontends**, served from `devinapps.com`.
* **FastAPI backends**, deployed to Fly.io.
Deploying is not how Devin ships code to *your* infrastructure. When Devin pushes to Vercel, AWS, Netlify, or your own CI/CD pipeline, it is running your tooling with credentials you provide — see [Existing applications](#existing-applications).
Deployments are intended for small apps Devin creates from scratch, such as prototypes, demos, and internal tools.
## Availability
Deployment is available to non-enterprise organizations with secure mode off:
* **Enterprise organizations**: deployment is disabled for all sessions. Deploy to your own infrastructure instead.
* **Secure mode**: when secure mode is enabled, Devin loses native internet deployment capabilities. The setting lives under Security settings on the Customization page.
Because a deployment makes content publicly reachable on the internet, every deploy requires your explicit approval. Devin shows an approve/deny prompt in the session, and the deploy runs only after you approve it.
## Frontend deployment
Devin uploads the contents of a build directory and serves them as a static site at a unique `https://.devinapps.com` subdomain. The only requirement is that the directory contains an `index.html` — so any framework that produces a static build works, including Vite, Next.js static exports, Astro, SvelteKit's static adapter, and plain HTML, CSS, and JavaScript.
When Devin creates a frontend from scratch and you haven't specified a stack, it scaffolds a Vite + TypeScript + Tailwind CSS + shadcn/ui app. That's a default for new projects, not a restriction on what can be deployed.
## Backend deployment
Devin deploys Python backends to Fly.io, generating the Dockerfile and `fly.toml` for you. The project must:
* have a `pyproject.toml` with a project name, and
* expose a FastAPI app named `app` in `app/main.py`.
Devin's FastAPI scaffold already satisfies both. For any other backend stack or language, choose your own deployment method and give Devin the credentials and instructions it needs via [Secrets](/product-guides/secrets) and [Knowledge](/product-guides/knowledge).
## Existing applications
| Component | Apps Devin creates | Existing applications |
| ------------ | ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| **Frontend** | Any static build, hosted on `devinapps.com` | Requires custom access and instructions via [Secrets](/product-guides/secrets) and [Knowledge](/product-guides/knowledge) |
| **Backend** | FastAPI projects, deployed to Fly.io | Requires custom access and instructions via [Secrets](/product-guides/secrets) and [Knowledge](/product-guides/knowledge) |
Devin is not equipped to deploy pre-existing applications to Cognition-hosted infrastructure. A static frontend may work if it builds to a directory with an `index.html`, but existing backends generally will not, because they rarely match the FastAPI layout the deployer expects.
For pre-existing applications, treat deployment like any other task you'd hand a new engineer: tell Devin which platform to use and store the credentials and commands in [Secrets](/product-guides/secrets) and [Knowledge](/product-guides/knowledge).
# Invite your Team
Source: https://docs.devinenterprise.com/product-guides/invite-team
Only available for Team and Enterprise plans
Add members to your Devin organization so you can collaborate with your team and create sessions within the same org.
## Roles
Your organization has three default roles:
* **Member** — Can start Devin sessions and view and contribute to most of your organization's resources, such as knowledge, playbooks, secrets, and environment snapshots.
* **Admin** — Has all member permissions, plus the ability to set up and manage billing, organization integrations, membership, and other organization-level settings.
* **DeepWiki Only** — Access limited to DeepWiki and Ask Devin.
Enterprise plans can also define [custom roles](/enterprise/security-access/custom-roles) with fine-grained permissions.
## Inviting members
To invite new members to your organization:
1. Navigate to **Settings > Members** in the sidebar, or go to [app.devin.ai/settings/members](https://app.devin.ai/settings/members).
2. Click **Invite members**.
3. Enter the email addresses of the people you want to invite.
4. Select a role for the invited users.
5. Click **Send invites**.
Invited users will receive an email with a link to join your organization. Once they accept the invitation, they will appear in the members list.
## Managing members
From the **Members** settings page, admins can:
* View all current members and their roles
* Change a member's role
* Remove members from the organization
Only admins can invite new members, change roles, or remove members from the organization.
# Knowledge
Source: https://docs.devinenterprise.com/product-guides/knowledge
Share important context and knowledge to help Devin get onboarded
## What is Knowledge?
Just like onboarding a new engineer, onboarding Devin requires an initial investment in **knowledge transfer**.
Knowledge is a collection of tips, advice, and instructions that Devin can reference in all sessions. You can continually add to Devin’s bank of Knowledge over time, and Devin will **automatically recall relevant Knowledge** as necessary.
Use the Knowledge feature to share documentation, tips, custom internal libraries, and other materials that Devin may need.
## How do I create Knowledge?
Navigate to [**Settings → Resources → Knowledge**](https://app.devin.ai/settings/knowledge), and click **Create knowledge** in the top right.
Your **Trigger Description** will help Devin recall relevant Knowledge at the right times. This can be a simple phrase or sentence. Devin will retrieve a Knowledge item when its current work is related to the specified triggers, and all Knowledge requires a trigger description.
**Content** should be a handful of sentences with relevant information.
### Macros
You can assign a **macro** to any knowledge item — a short identifier starting with `!` (e.g., `!deploy-checklist`). Macros let you quickly reference knowledge in your prompts by typing the macro name. Macros can only contain letters, numbers, and hyphens, and must be unique within your organization.
### Enabling and disabling Knowledge
Each knowledge item can be individually **enabled or disabled** per user. Disabling a knowledge item prevents Devin from retrieving it in your sessions, without deleting it from the organization. This is useful when a knowledge item is temporarily irrelevant to your work but may be useful to teammates or in the future.
## Knowledge Suggestions
Devin will automatically suggest Knowledge to remember based on your feedback in chat. Edit the suggested Knowledge before saving, or dismiss the Knowledge if it's not helpful.
You can also request Devin to regenerate a Knowledge Suggestion based on your feedback. This can make it easier to iterate on suggested knowledge rather than manually editing. Devin can also suggest updates to existing knowledge items in addition to suggesting new knowledge items.
## What belongs in Knowledge?
We recommend including the aspects of your prompts or playbooks you find yourself repeating regularly. Examples include common bugs and their associated solutions, code conformance practices, deployment workflows, testing workflows, how to interact with proprietary tools, etc.
## Organizing Knowledge with Folders
You can organize knowledge items into **folders** for easier management. Folders support:
* **Nested hierarchy** — Create sub-folders to build a structured knowledge tree.
* **Bulk enable/disable** — Toggle an entire folder on or off. When a folder is disabled, all knowledge items inside it are disabled for your sessions.
* **Move items** — Drag knowledge items between folders, or use the move action to reorganize.
* **Auto-organize** — Select multiple knowledge items and let Devin automatically sort them into logical folders.
Folders are particularly helpful when your organization has a large number of knowledge items spanning different teams, projects, or workflows.
## Tips and tricks
1. Create specific Knowledge that is targeted at one workflow or action. Devin will read the entire Knowledge contents, so keep it all relevant and up-to-date!
* Split up your Knowledge into smaller ones where possible. Devin is capable of accessing multiple Knowledge “items” at once.
2. Make a habit of adding and updating Knowledge. These are shared across your organization, and will continually improve Devin for your team over time.
3. Devin retrieves Knowledge when relevant, not all at once or all at the beginning. Be sure to make your retrieval trigger highly relevant to the contents.
4. Use folders to group related knowledge (e.g., by project, team, or workflow) so you can quickly enable or disable sets of knowledge as your focus changes.
## Organization and Enterprise Knowledge
For enterprise customers, the Knowledge page is split into separate tabs to help you manage knowledge at different scopes:
* **Organization Knowledge** — Knowledge items scoped to your current organization. These are visible to all members of the organization and are the default scope for new knowledge items.
* **Suggestions** — AI-generated knowledge suggestions based on your session interactions (shown for non-primary organizations).
* **Enterprise Knowledge** — Knowledge items that apply across all organizations in your enterprise. Only visible when you belong to an enterprise account. Enterprise admins can create and manage enterprise-level knowledge from this tab.
Primary organization users see a single **Enterprise Knowledge** tab. Non-primary organization users with an enterprise account see all three tabs, with Organization Knowledge as the default. Non-primary organization users without an enterprise account see only Organization Knowledge and Suggestions.
Enterprise knowledge items are particularly useful for sharing company-wide coding standards, architectural guidelines, deployment procedures, and other context that should apply uniformly across all teams and organizations.
### Promoting Organization Knowledge to Enterprise
If an organization-level knowledge item proves useful enough to share across your entire enterprise, you can promote it directly from the knowledge editor. Open the item, then click **Promote to Enterprise** in the Details tab. The item is moved from organization scope to enterprise scope and becomes available to all organizations in your enterprise.
Promotion requires enterprise knowledge management permissions, and is only available for user-created knowledge items in organizations that belong to an enterprise.
## Pinning Knowledge to Repos
You can choose whether Knowledge applies to no repo, a specific repo, or all repos:
* Pinning to **no repo**: The Knowledge is only retrieved when Devin decides it's relevant to your current context.
* Pinning to **a specific repo**: The Knowledge is always used whenever Devin is working in that specific repo.
* Pinning to **all repos**: The Knowledge automatically applies to every repo that Devin is working on in any session.
# Cloud Authentication with OIDC
Source: https://docs.devinenterprise.com/product-guides/oidc
Give Devin short-lived, keyless access to your cloud services via OpenID Connect
Devin can authenticate to cloud services using OpenID Connect (OIDC) workload identity federation instead of long-lived credentials. Each Devin session receives a short-lived identity token issued by Devin, which your cloud provider verifies and exchanges for temporary credentials. No static API keys or secrets need to be stored in Devin.
## How it works
1. Every Devin session automatically receives a short-lived **identity token**, signed by Devin and refreshed for the lifetime of the session.
2. Your cloud provider verifies the token against Devin's public OIDC issuer and grants temporary, scoped access.
Tokens identify the session through claims such as `org_id`, `devin_id`, and `requesting_user_email`, so you can write trust policies that grant access to your organization, or to specific sessions or users. Tokens expire automatically — there is nothing to rotate or revoke.
## Setup actions
Add the relevant action to the `initialize` section of your [environment blueprint](/onboard-devin/environment/blueprints):
| Action | Purpose |
| --------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
| [`setup-aws-oidc`](https://github.com/CognitionAI/actions/tree/main/setup-aws-oidc) | AWS CLI and SDK auth via IAM `AssumeRoleWithWebIdentity` |
| [`setup-gcp-oidc`](https://github.com/CognitionAI/actions/tree/main/setup-gcp-oidc) | gcloud and Google Cloud SDK auth via Workload Identity Federation |
| [`setup-vault-oidc`](https://github.com/CognitionAI/actions/tree/main/setup-vault-oidc) | HashiCorp Vault CLI auth via the JWT/OIDC auth method |
| [`setup-jfrog-oidc`](https://github.com/CognitionAI/actions/tree/main/setup-jfrog-oidc) | JFrog CLI auth via JFrog's OIDC token exchange |
| [`setup-devin-oidc`](https://github.com/CognitionAI/actions/tree/main/setup-devin-oidc) | Base `devin-oidc` CLI, for services that trust Devin as an identity provider |
### Example: AWS
```yaml theme={null}
initialize:
- uses: github.com/CognitionAI/actions/setup-aws-oidc@main
with:
role-arn: "arn:aws:iam::123456789012:role/devin-sessions"
region: "us-east-1"
```
Devin can then run AWS commands without any stored credentials:
```bash theme={null}
aws sts get-caller-identity
```
See the [`setup-aws-oidc` documentation](https://github.com/CognitionAI/actions/tree/main/setup-aws-oidc) for the full AWS-side prerequisites and configuration options.
### Example: GCP
```yaml theme={null}
initialize:
- uses: github.com/CognitionAI/actions/setup-gcp-oidc@main
with:
workload-identity-provider: "projects/123456789/locations/global/workloadIdentityPools/devin/providers/devin-oidc"
service-account: "devin@my-project.iam.gserviceaccount.com"
project: "my-project"
```
gcloud and the Google Cloud client libraries then authenticate automatically through Workload Identity Federation:
```bash theme={null}
gcloud storage ls
gcloud auth print-access-token
```
See the [`setup-gcp-oidc` documentation](https://github.com/CognitionAI/actions/tree/main/setup-gcp-oidc) for the full GCP-side prerequisites (workload identity pool and provider setup) and configuration options.
### Example: custom services
For your own APIs and internal services, use the base CLI to request a token for any audience your service accepts:
```bash theme={null}
devin-oidc token --audience my-api --subject-keys "org_id"
```
Configure your service to trust Devin's OIDC issuer and verify tokens against its published JWKS at `/.well-known/jwks.json`. The issuer is your Devin webapp origin — `https://app.devin.ai`, or your own domain for enterprise deployments (e.g. `https://yourdomain.devinenterprise.com`).
## Token claims
Tokens carry the following identity claims, which you can reference in trust policies and use to compose the token subject via `subject-keys`. The subject is built from `key:value` pairs of the selected claims — for example, `--subject-keys "org_id"` (the default) produces a subject like `org_id:a67b8de8-9483-4a9c-9662-51c3d2a45e88`.
| Claim | Description |
| ---------------------------------------------- | ----------------------------------------------------------- |
| `org_id` | Organization the session was launched in |
| `account_id` | Account (enterprise or single-org customer) identifier |
| `devin_id` | The Devin session ID |
| `devin_trigger` | How the session was started (e.g. `webapp`, `slack`, `api`) |
| `requesting_user_id` / `requesting_user_email` | The user who started the session |
| `service_user_id` | Service user, for API-initiated sessions |
## Security properties
* **No long-lived credentials**: tokens are short-lived and refreshed automatically; nothing needs to be rotated or revoked when a session ends.
* **Scoped access**: audience-scoped tokens are only valid for the specific service they were requested for, and your trust policies control exactly which identities can be granted access.
* **Auditable identity**: tokens carry the session, organization, and requesting user, so cloud-side audit logs attribute every action to a specific Devin session.
Enterprise deployments with custom domains have a dedicated per-account signing key, and the token issuer is your custom Devin URL. Contact your Devin administrator or Cognition support for your issuer URL and organization ID.
# Set up your plugin ecosystem
Source: https://docs.devinenterprise.com/product-guides/plugin-ecosystem
Build, host, and govern a shared set of Devin plugins for your organization or enterprise, with managed distribution and policy controls.
Plugins are in **closed beta**. To request access, contact [support@cognition.ai](mailto:support@cognition.ai). Behavior and configuration may change in future releases.
This guide walks through standing up your own **plugin ecosystem**: a repo of plugins your organization owns, distributed to every Devin session and CLI user through a managed manifest, with required, optional, and forbidden plugins as the governance controls.
Two template repos accompany this guide:
* [**plugin-template**](https://github.com/CognitionAI/plugin-template) — a starter for authoring a single plugin (or a couple of them).
* [**team-marketplace-template**](https://github.com/CognitionAI/team-marketplace-template) — the full ecosystem pattern: a monorepo of plugins plus a **meta-plugin** whose manifest defines your baseline and policy.
## 1. Author your plugins
A plugin is a directory with a `.devin-plugin/plugin.json` manifest; everything else is optional:
```
my-plugin/
├── .devin-plugin/
│ └── plugin.json # name, version, dependency + policy lists
├── AGENTS.md # always-on rule
├── rules/ # triggered rules
├── agents/.md # custom subagents (CLI/Desktop-only today); agents//AGENT.md also works
├── hooks.json # lifecycle hooks
├── .mcp.json # MCP servers
└── skills//SKILL.md # skills, exposed as /:
```
Fork [plugin-template](https://github.com/CognitionAI/plugin-template) to start, and see the [CLI plugins reference](/cli/extensibility/plugins/overview) for the full format. Keep `AGENTS.md` short — it costs context in every session for everyone who has the plugin.
## 2. Validate and test locally
Both templates ship a validator (`node scripts/validate-template.mjs`) and a CI workflow that runs it on every PR. For a live test, install from a local folder with the [Devin CLI](/cli/index):
```bash theme={null}
devin plugins install ./plugins/my-plugin # linked: edits apply on the next session
devin plugins list
```
## 3. Host them in one repo
Put all of your org's plugins in a single repo as subfolders (`plugins//`), each referenced with its own `git-subdir` source. The repo can stay private: cloud sessions fetch it through your Git integration, and CLI users fetch with their own git credentials (so they need repo access too).
Fork [team-marketplace-template](https://github.com/CognitionAI/team-marketplace-template) for this layout — and update its meta-plugin's `git-subdir` URLs to point at your fork. In the template the meta-plugin lives at the **repo root**, so the repo itself is the installable unit: requiring `your-org/your-marketplace` installs the whole baseline.
## 4. Define your baseline with a meta-plugin
The **meta-plugin** pattern turns your whole ecosystem into one installable unit. It's a plugin with little or no content of its own — its manifest does the work. Put it at the repo root so the repo itself is the meta-plugin:
```jsonc theme={null}
// .devin-plugin/plugin.json (repo root)
{
"name": "team-starter-pack",
"requiredPlugins": [
// auto-installed for everyone, recursively
{ "source": "git-subdir", "url": "https://github.com/acme/plugins.git", "path": "plugins/engineering-baseline" },
{ "source": "git-subdir", "url": "https://github.com/acme/plugins.git", "path": "plugins/security-guardrails" }
],
"optionalPlugins": [
// endorsed, not auto-installed; also a carve-out from this manifest's forbids
{ "source": "git-subdir", "url": "https://github.com/acme/plugins.git", "path": "plugins/frontend-standards" }
],
"forbiddenPlugins": [
"untrusted-vendor/*"
]
}
```
## 5. Distribute from Settings → Resources → Plugins
An admin adds one entry to the managed manifest on the [Plugins settings page](https://app.devin.ai/settings/marketplace) — see the [Plugin marketplace guide](/product-guides/plugins):
```json theme={null}
{
"requiredPlugins": ["acme/plugins"]
}
```
Requiring the marketplace repo installs its root meta-plugin, which pulls in the whole baseline recursively.
Everyone in scope now gets the baseline automatically. Pick the scope deliberately:
* The **enterprise/account** manifest reaches cloud sessions **and** CLI users logged into the account.
* The **org** manifest reaches **cloud sessions only** — the CLI has no org context.
## 6. Govern
The three lists are the policy language, at every level (managed manifests, repo config, plugin manifests). Higher authority wins — enterprise/account over org over repo over user — and a lower level can never re-permit what a higher level forbids, nor forbid what it requires.
To lock an account down to an approved set only:
```json theme={null}
{
"forbiddenPlugins": ["*"],
"requiredPlugins": [
"acme/plugins",
{ "source": "git-subdir", "url": "https://github.com/acme/plugins.git", "path": "plugins/engineering-baseline" },
{ "source": "git-subdir", "url": "https://github.com/acme/plugins.git", "path": "plugins/security-guardrails" }
],
"optionalPlugins": [
{ "source": "git-subdir", "url": "https://github.com/acme/plugins.git", "path": "plugins/frontend-standards" }
]
}
```
The manifest's own required/optional entries are exempt from its own `"*"` forbid; nothing else is, and no lower level can widen the carve-out. The exemption covers only *directly listed* entries — a required plugin's transitive dependencies aren't exempt — so under a lockdown, list everything the meta-plugin pulls in (here `engineering-baseline` and `security-guardrails`) explicitly. See [dependencies and governance](/cli/extensibility/plugins/overview#dependencies) for the full semantics.
## 7. Evolve
* Merging to your plugin repo's default branch **is** the release: new sessions pick it up automatically — see [how updates roll out](/product-guides/plugins#how-updates-roll-out).
* Teams add plugins by PR to the marketplace repo; the template's CI validates the layout on every PR.
* Existing Claude plugins install as-is (Devin falls back to `.claude-plugin/plugin.json`), so you can endorse community plugins in `optionalPlugins` without vendoring them.
## Current limitations
* Plugins load in cloud sessions, the [Devin CLI](/cli/index), and Devin Desktop (when using Devin Local); they do not apply to the classic Cascade agent.
* **Subagents** (`agents/.md` or `agents//AGENT.md`) load in local Devin agents only (CLI and Devin Desktop), not in cloud sessions.
* **Hooks**: cloud sessions run `command` hooks for every [event](/cli/extensibility/hooks/lifecycle-hooks) except `SessionStart` and `SessionEnd`; `prompt`-type hooks are CLI/local-only.
* **Plugin-served MCP** loads in-session but doesn't yet appear in the MCP settings UI.
* **Org-level** manifests don't reach CLI users; use the enterprise/account manifest for CLI enforcement.
## Learn more
* [Plugin marketplace](/product-guides/plugins) — the web app side: manifests, scopes, uploads
* [CLI plugins reference](/cli/extensibility/plugins/overview) — file format, authoring, per-user installs
* [Skills](/product-guides/skills) — the `SKILL.md` procedures plugins bundle
# Plugin marketplace
Source: https://docs.devinenterprise.com/product-guides/plugins
Install and require bundles of skills for everyone in your org or enterprise from the Devin web app
Plugins are in **closed beta**. To request access, contact [support@cognition.ai](mailto:support@cognition.ai). Behavior and configuration may change in future releases.
## What are plugins?
A **plugin** bundles skills — and optionally rules, hooks, MCP servers, and subagents — so it can be installed and reused as a unit. See the [plugins reference](/cli/extensibility/plugins/overview) for the file format and what a plugin can ship.
**Managed plugins** let an admin install plugins centrally, from the Devin web app, so they apply to **everyone in the org or enterprise** — no per-user setup. This covers cloud Devin sessions **and** [Devin CLI](/cli/index) users logged into the account (enterprise/account-level config reaches the CLI too — see [cloud sessions vs. the CLI](#cloud-sessions-vs-the-cli)). When a plugin is installed, its skills become available to Devin automatically as `/:` commands.
This page covers the web app side of plugins: managed manifests, scopes, and uploads.
## Where to configure them
Go to [**Settings → Resources → Plugins**](https://app.devin.ai/settings/marketplace). The page has two tabs:
* **Marketplace** — browse plugins (the Devin official catalog plus any your org or enterprise has added) and install them. Installing a plugin **adds it to the manifest of the chosen scope as a required plugin**, so it's installed for everyone in that scope.
* [**Configuration**](https://app.devin.ai/settings/marketplace?tab=configuration) — edit the raw plugin **manifest** as JSON, and upload your own plugin as a folder or `.zip` (or build one in the editor).
Access is permission-gated:
* **Org admins** (organization settings access) manage the **org** manifest.
* **Enterprise admins** (enterprise settings access) additionally manage the shared **enterprise** manifest.
## The manifest
The manifest is a single JSON document with three lists:
```jsonc theme={null}
{
"requiredPlugins": ["acme/review-tools"],
"optionalPlugins": [],
"forbiddenPlugins": ["sketchy-org/bad-plugin", "acme/*"]
}
```
* **`requiredPlugins`** — installed for everyone in scope (recursively, including any plugins they depend on).
* **`optionalPlugins`** — an allow-list that endorses plugins without auto-installing them; used to carve out exceptions to a forbidden entry.
* **`forbiddenPlugins`** — a deny-list of plugin identities or glob patterns.
The manifest is stored verbatim; the agent validates the full source at install time. See the plugins reference for the [source forms](/cli/extensibility/plugins/overview#manifest) each entry can take and the full [dependency and governance semantics](/cli/extensibility/plugins/overview#dependencies).
## Adding your own plugins
Depending on where the plugin lives, add it in one of these ways:
| Where it lives | How to add it |
| ---------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
| **Public git repo** | Add `"owner/repo"` (or the git URL) to the manifest, or install from the Marketplace tab if it's in the catalog |
| **Private git repo** | Same manifest entry — see [using a private skills repo](#using-a-private-skills-repo) for how auth works |
| **Subfolder of a repo** (e.g. a monorepo of plugins) | Add a `git-subdir` source — see the [plugins reference](/cli/extensibility/plugins/overview#manifest) |
| **Not in a repo at all** | Upload it as a bundle (below) |
### Uploading a plugin bundle
On the [**Configuration**](https://app.devin.ai/settings/marketplace?tab=configuration) tab, the **Uploaded plugin** section lets you upload a plugin as a folder or `.zip`, or build one directly in the editor. Saving it adds it to the manifest as a required plugin (installing it for everyone in scope); deleting it removes the reference. This is a good option for a plugin you don't want to (or can't) host in a git repo.
### Using a private skills repo
Point the manifest straight at the private repo — you generally don't need to bake it into your [environment snapshot](/onboard-devin/environment/blueprints). Any private repo Devin can already reach through your Git integration installs automatically. Use the git URL form, or `git-subdir` to install a plugin from a subfolder of a shared repo. (CLI users covered by the same manifest fetch with their own local git credentials, so they'll need access to the repo too.)
If the repo isn't reachable through your Git integration, either **upload it as a bundle** (above) or clone it during environment setup and reference it with a local path.
## How updates roll out
* **Manifest changes** (Settings → Resources → Plugins) apply to the **next session**.
* **Plugin changes** — merging to the branch a plugin tracks reaches new sessions automatically, within a few hours. Pin the plugin to a commit SHA to control updates yourself; on the CLI, `devin plugins update` refreshes immediately.
* Running sessions keep what they loaded at start — updates never change a session mid-flight.
## Scope and inheritance
Managed manifests exist at up to two levels:
* **Standalone accounts** have a single **account** manifest that applies to everyone.
* **Enterprises** have a shared **enterprise** manifest that is **inherited by every child org**, plus a per-**org** manifest layered below it. The Marketplace view shows both, and enterprise admins can choose to install a plugin at the enterprise scope (applies everywhere) or an org admin can install it at just their org.
These sit at the top of the overall plugin hierarchy, above repo- and user-level plugin config. See [inheritance and levels](/cli/extensibility/plugins/overview#inheritance-and-levels) for the other levels and the authority rules.
### Cloud sessions vs. the CLI
Both cloud Devin sessions and the [Devin CLI](/cli/index) enforce the **enterprise/account** manifest — required plugins are installed and forbids are enforced for CLI users logged into the account too.
The **org** manifest applies only to **cloud sessions**. The CLI authenticates at the account level and has no org context, so org-level requires and forbids don't reach CLI users. Put anything you need enforced in the CLI (or account-wide) in the enterprise/account manifest, and use the org manifest for org-specific additions to cloud sessions.
## Learn more
* [Skills](/product-guides/skills) — the `SKILL.md` procedures that plugins bundle
* [CLI plugins reference](/cli/extensibility/plugins/overview) — plugin file format, authoring, and per-user install
* [Playbooks](/product-guides/creating-playbooks) — reusable prompt templates attached to sessions
# Scheduled Sessions
Source: https://docs.devinenterprise.com/product-guides/scheduled-sessions
Automate recurring or one-time Devin sessions that run on a schedule
**Automations are now the recommended way to run Devin on a schedule.** [Automations](/product-guides/automations) support schedule triggers along with event-driven triggers (Slack, GitHub, Linear, webhooks), conditions, invocation limits, and more. If you're setting up a new scheduled workflow, use an automation with a **Schedule trigger** instead. Existing scheduled sessions will continue to work.
Scheduled Sessions let you create Devin sessions that run automatically — either on a recurring schedule or as a one-time run at a specific date and time. Use them to automate repetitive tasks like daily reports, periodic code maintenance, routine data analysis, and more.
## Creating a Scheduled Session
There are two ways to create a scheduled session:
### From the input box
1. Type your prompt in the Devin input box
2. Click the **three-dot menu** (⋯) on the right side of the input box
3. Select **Schedule Devin**
4. You'll be taken to the schedule creation page with your prompt pre-filled
### From the Schedules settings page
1. Navigate to **Settings > Schedules** in the sidebar
2. Click **Create schedule**
3. Fill in the schedule details
## Configuring a Schedule
When creating or editing a schedule, you can configure the following options:
### Name
Give your schedule a descriptive name so you can easily identify it in the list (e.g., "Daily CI Report" or "Weekly Dependency Updates").
### Schedule type
Choose between two schedule types:
* **Recurring** — Runs repeatedly on a cron-based frequency (default)
* **One-time** — Runs once at a specific date and time, then automatically disables itself
### Agent
Choose which agent type should run the scheduled session:
* **Devin** — Standard AI software engineer (default)
* **Data Analyst** — Optimized for data analysis and queries
* **Advanced** — For playbooks and session analysis
### Playbook (optional)
Attach a [playbook](/product-guides/using-playbooks) to the scheduled session. The playbook will be applied every time the schedule runs, ensuring consistent behavior across executions.
### Repositories (optional)
Select one or more repositories for the scheduled session to work in. When repositories are selected, they are included as a hint in the session prompt so Devin knows which repos to focus on. Leave empty to let Devin determine the relevant repositories from the prompt.
### Frequency (recurring schedules)
For recurring schedules, set how often the schedule should run. The frequency editor supports two modes:
**Visual mode** provides preset options:
* **Hourly** — Run every N hours
* **Daily** — Run at a specific time every day
* **Weekly** — Run at a specific time on selected days of the week
Times are displayed in your local timezone but stored as UTC internally. The editor handles the conversion automatically.
**Custom mode** lets you enter a standard cron expression directly (e.g., `0 9 * * 1-5` for weekdays at 9 AM UTC). This gives you full flexibility for complex schedules.
### Run at (one-time schedules)
For one-time schedules, pick the date and time when the session should run. The time is entered in your local timezone and converted to UTC automatically. One-time schedules must be set to a time in the future.
After a one-time schedule executes, it is automatically disabled. The schedule and its past sessions are preserved for audit purposes.
### Email notifications
Control when you receive email notifications about scheduled session runs:
* **Always** — Get notified after every run
* **On failure only** — Only get notified when a scheduled session fails (default)
* **Never** — No notifications
### Slack notifications
You can optionally send notifications about scheduled session runs to a **Slack channel**. When configured, Devin posts updates to the selected channel when the schedule runs. This requires a connected Slack integration in your organization settings.
### Run as
By default, sessions created by a schedule are attributed to the user who originally created the schedule. When editing a schedule, you can update this so that future runs are attributed to you instead. This is useful when schedule ownership changes hands — the new owner receives notifications and the sessions appear under their account.
### Prompt
Write the instructions that Devin will follow each time the schedule runs. This is the same as the prompt you would type when starting a regular Devin session.
## Managing Schedules
Navigate to **Settings > Schedules** to see all your scheduled sessions. The list shows each schedule's name, frequency, last run time, and status.
### Status
Each schedule has one of three statuses:
* **Active** — The schedule is enabled and will run at its next scheduled time
* **Paused** — The schedule is disabled and will not run until re-enabled. One-time schedules are automatically paused after execution.
* **Error** — The schedule encountered consecutive failures
### Editing a schedule
Click on any schedule in the list to view its details. Click **Edit** to modify its configuration, including the name, prompt, agent, playbook, repositories, frequency, notification settings, run-as user, and whether it is enabled or paused.
### Pausing and resuming
You can pause a schedule by editing it and toggling the **Status** switch to **Paused**. Paused schedules will not create new sessions until re-enabled. Toggle it back to **Active** to resume.
### Deleting a schedule
Click the **three-dot menu** on a schedule's detail page and select **Delete**. This permanently removes the schedule. Past sessions created by the schedule are not affected.
## Viewing Past Sessions
Each schedule detail page has a **Past Sessions** tab that lists all Devin sessions created by that schedule. Click on any session to navigate to its full session view. This is useful for reviewing outcomes, debugging failures, or auditing what the schedule has been doing over time.
## Use Cases
Here are some common ways to use Scheduled Sessions:
* **Daily standup reports** — Summarize recent PRs, issues, or commits every morning
* **Periodic dependency updates** — Check for and apply dependency updates on a weekly basis
* **Recurring data analysis** — Generate reports or dashboards from your data at regular intervals
* **Routine code maintenance** — Run lint fixes, dead code removal, or test coverage checks on a schedule
* **Monitoring and alerting** — Periodically check system health or review logs for anomalies
# Secrets & Site Cookies
Source: https://docs.devinenterprise.com/product-guides/secrets
Securely share credentials with Devin so it can access any tool
## Giving Devin Credentials
Devin can use its own login credentials to access platforms that require authentication, either in its Browser or via the command line. We recommend setting up a dedicated account for Devin to use (e.g. [devin@company.com](mailto:devin@company.com)) on each service that it needs access to. You may then save Devin's username and password as Secrets on your account, so that it can log in as part of your future sessions.
Adding secrets is primarily done via the [Secrets page](http://app.devin.ai/secrets). This page is particularly relevant for Organization-level secrets. For repo-specific or session-specific secrets, see the below sections.
When adding a secret, you may add a Note that explains additional context or instructions for using the secret. Use this field to convey useful information to both Devin and your fellow organization members. Example notes could include:
* This API key should only be used in our production env but never in staging or dev.
* Used for our AWS RDS Database in us-west-2
* These credentials are scheduled to be deprecated after Q3 2025
* Auto-expires every 30 days - ping the SecOps team for rotation if this starts failing
* This API key is attached to the [devin@company.com](mailto:devin@company.com) user account
## Persisted Global Secrets
Secrets added in [Settings → Resources → Secrets](https://app.devin.ai/settings/secrets) are **persisted** to future sessions and apply to the entire organization. Note that any secrets you share here will be usable by Devin in all future Devin sessions within your organization. All secrets are encrypted at rest. **New secrets are only available to Devin in sessions created *after* you added the secret.**
Please note that all members of your organization will be able to use Global Secrets, but only admins will be able to view or edit existing secrets. Take care to only add secrets that are specifically scoped to your organization and usable by all its members.
### Personal Secrets
In addition to organization-wide secrets, you can create **personal secrets** that are scoped to your own sessions only. Personal secrets are not shared with other members of your organization. This is useful for credentials tied to your personal accounts or for testing secrets that should not be exposed to the broader team.
To create a personal secret, select the **Personal** scope when adding a new secret on the [Secrets page](https://app.devin.ai/secrets). Personal secrets are only accessible in sessions you create and are not visible to other organization members or admins.
There are a few types of secrets available:
This is most suitable for most generic secrets with a single value. Each Secret Name (also known as a Secret Key) is associated with a single Secret Value. Examples of secrets stored here could be:
* API Keys
* SSH Keys
* Usernames or Passwords
* Tokens
If a single secret requires multiple values, please make a distinct secret for each value. For example, you could store GITHUB\_USERNAME and GITHUB\_PASSWORD as two Raw Secrets.
**Cookies “hold” your authenticated state**; if you are logged into some site, then giving Devin your cookies for that site will make it so that Devin is automatically logged in for the same site.
Please note that sometimes cookies can be insufficient by themselves and may require additional Username or Password secrets. For example, on Amazon, Devin may be logged into the site while shopping or adding to cart, but Amazon might require an additional layer of password confirmation when it comes time to check out.
Cookies are stored as a base64 encoded string of `;` delimited JSON array in the standard chromium cookie format. This is important to know if you need to manually encode cookies rather than exporting them directly from Chrome. For details of how to add a Cookie secret, please see [Adding a New Site Cookie](/product-guides/secrets#adding-a-new-site-cookie)
Time-based one-time passwords are used for two-factor authentication (2FA). Devin can store TOTP secrets that act similarly to those in Google Authenticator or Authy. For details of how to add a TOTP secret, please see [Adding a New TOTP](/product-guides/secrets#adding-a-new-totp)
Devin used to support creating Key-Value secrets that would handle multiple keys per secret. However, this feature is no longer available.
Instead of making key-value secrets, we recommend simply creating multiple raw secrets for each distinct field. For example, instead of creating a key-value secret for JIRA\_LOGIN, you could create two raw secrets: JIRA\_USERNAME and JIRA\_PASSWORD.
## Repo-Specific Secrets
To scope secrets to a specific repository, you can add them as environment variables (or in a .env file) during [environment configuration](/onboard-devin/environment).
Sessions using the same Snapshot in the future will be able to access those environment variables, but other unrelated sessions will not.
## Session-Specific Secrets
While Devin is working, it may ask you to provide credentials (API keys, logins, etc.) within the current conversation, like so:
When Devin asks for secrets in this fashion, these secrets are scoped purely to the current session and are not saved for any future sessions.
Alternatively, you can set session-specific secrets yourself:
## Working With Secrets
Once a secret has been configured in Devin, your application may access it like a normal ENV variable (as long as the session was started after your secret was configured). This applies to global organization-wide secrets, repo-specific secrets, and session-specific secrets.
Devin performs some text conversion to ensure that your Secrets are valid ENV variables:
* It removes invalid characters by replacing anything other than a letter, digit, or underscore with another underscore. For example, the secret named Abc%123 would become the ENV variable Abc\_123
* If your secret name does not begin with a letter, Devin adds an underscore to the beginning of the name. For example, the secret 123MYVAR would become the ENV variable \_123MYVAR
* If you have two secrets with the same name, Devin will add a counter to the end. For example, if you have two secrets named MY\_SECRET you would end up with two ENV variables named MY\_SECRET and MY\_SECRET\_2 and so on.
You may then access your secrets using your application's preferred method of reading ENV variables. For example, you may prepend a dollar sign to refer to a secret like \$API\_KEY.
## Adding a New Site Cookie
To add a Site Cookie, please follow the steps below:
1. Log in as you normally would to the account you'd like to share with Devin. This will generate cookie(s).
2. In order to get the cookie(s) from the browser store, download the browser extension [Share your cookies](https://chromewebstore.google.com/detail/share-your-cookies/poijkganimmndbhghgkmnfgpiejmlpke) and follow the steps on that Extension to extract your cookies. You may want to test that importing the cookie in another Chrome Profile successfully authenticates you to the site.
3. Add the exported cookie to Devin via the [Secrets page.](https://app.devin.ai/secrets)
4. When using the cookie for a site, Devin should find that it’s already logged in when it navigates to that site. Tell Devin to give it a try!
If you're not using Chrome or need to manually encode cookies, note that Devin expects cookies in a base64 encoded string of `;` delimited JSON objects in the standard chromium cookie format.
## One-Time Password
Devin can now handle two-factor authentication (2FA) using a time-based one-time password (TOTP). To do this, you’ll need to give Devin the information provided at the time 2FA is set up on Devin's account for the specific application:
1. Access Devin's account for the service that requires 2FA.
2. Go to the account security settings and look for an option to regenerate or view the QR code. This may be called Set up or Replace Authenticator.
3. If the application allows, select the option to view the QR code.
4. Once the QR code is displayed on your screen, take a screenshot.
5. Go to [Devin's Secrets](https://app.devin.ai/secrets), click on the "Add Secret" button, and change the Secret type to "One-time Password". Put a descriptive name. Click the small QR code icon in the top right of the Value input box and upload your QR code screenshot.
Only provide 2FA codes associated with accounts that were specifically set up for Devin's use only. We do not recommend giving Devin any 2FA codes to your personal accounts.
### Tips for TOTPs
* Some applications may not allow you to view the existing QR code once 2FA is enabled. In such cases, regenerating the QR code is the only option.
* Always save any new backup codes provided during the process in a secure location.
# Session Insights
Source: https://docs.devinenterprise.com/product-guides/session-insights
Analyze your Devin sessions and get actionable feedback to improve future interactions
## What is Session Insights?
Session Insights is an analysis feature that helps you understand what happened in your Devin sessions and provides actionable recommendations for improvement. When you trigger an analysis, Session Insights examines the session to identify patterns, issues, and opportunities for better collaboration.
Session Insights is available for all completed Devin sessions at no additional cost. When a session ends, Devin automatically generates a lightweight classification (category, languages, and tools). For large sessions (L or XL), a full analysis is also generated automatically at teardown. For smaller sessions, you can trigger a full analysis manually through the UI or via the [API](/api-reference/v3/sessions/post-organizations-session-insights-generate).
## How to Access Session Insights
### Step 1: Complete a Session
Run a Devin session and let it complete. Session Insights works best with sessions that have clear outcomes, whether successful or not. Sessions that are too short (fewer than one Devin message) will not generate insights.
### Step 2: Open the Insights Modal
After your session completes, look for the **Session Insights** button in the top bar of your session.
### Step 3: Generate or View Analysis
Click the button to open the Session Insights modal. If an analysis has not yet been generated, click **Generate Analysis** to start one. Generation typically takes about a minute. If an analysis already exists, you can click **Regenerate** to create a fresh analysis.
## Session Overview Metrics
At the top of the Session Insights modal, four key metrics give you a quick snapshot of the session:
### ACU Usage
ACU (Agent Compute Unit) usage reflects how much compute Devin consumed during the session. Lower ACU usage for a given task generally indicates a more efficient session. Use this metric to compare similar tasks and identify sessions where Devin may have spent excessive compute on retries or dead ends.
### User Messages
The total number of messages you sent during the session. A high message count can indicate that Devin needed frequent course corrections, suggesting that the initial prompt could be more detailed. Ideally, provide all important context upfront to minimize back-and-forth.
### Session Size
Session size is a composite classification (XS, S, M, L, XL) based on both ACU usage and user message count. Either higher ACU usage or a higher number of user messages can increase the session size.
The thresholds for each size category are:
| Size | ACU threshold | User message threshold |
| ------ | ------------- | ---------------------- |
| **XS** | ≤ 2 ACUs | ≤ 2 messages |
| **S** | ≤ 5 ACUs | ≤ 5 messages |
| **M** | ≤ 10 ACUs | ≤ 10 messages |
| **L** | ≤ 20 ACUs | ≤ 20 messages |
| **XL** | > 20 ACUs | > 20 messages |
For enterprise customers, ACU thresholds are scaled by a factor of 10 (e.g., XS ≤ 20 ACUs, S ≤ 50, M ≤ 100, L ≤ 200, XL > 200). User message thresholds remain the same.
The overall session size is the **larger** of the ACU-based size and the message-based size. Sessions classified as **L** or **XL** are flagged as unhealthy, meaning Devin likely encountered significant issues or the task scope was too broad for a single session. Consider breaking large tasks into smaller, focused sessions.
To keep sessions small and efficient, provide all important information upfront in the initial prompt.
### Category
Devin automatically classifies sessions into task categories based on the work performed. Classification also includes metadata such as the **tools and frameworks** used and the **programming languages** involved.
The available task categories are:
* **Feature Development** — building new features, components, services, or implementing new functionality
* **Bug Fixing** — investigating and resolving bugs, errors, or unexpected behavior
* **Code Review** — reviewing, explaining, or analyzing existing code and architecture
* **Refactoring & Optimization** — improving code structure, performance, or readability without changing behavior
* **Test Generation** — writing, fixing, or improving tests (unit, integration, e2e, QA) and test infrastructure
* **Migrations & Upgrades** — upgrading dependencies, migrating between frameworks or versions
* **CI/CD & DevOps** — CI/CD pipeline work, deployment, monitoring, alerting, and infrastructure tasks
* **Security** — fixing security vulnerabilities, addressing CVEs, and improving security posture
* **Data & Automation** — data analysis, pipelines, scripting, dashboards, and automation tasks
* **Documentation & Content** — writing or updating documentation, READMEs, changelogs, API docs, and translations
* **Research & Exploration** — exploring feasibility, researching solutions, designing architecture, writing RFCs, and prototyping
This classification helps you understand how Devin interpreted your task and can reveal misalignment between what you intended and what Devin worked on.
## Analysis Tabs
The Session Insights modal contains three tabs, each focused on a different aspect of the analysis.
### Issue Timeline
The Issue Timeline tab contains two sections:
**Issues Detected** lists problems Devin encountered during the session. Each issue includes:
* A **label** describing the issue category
* An **impact** rating (high, medium, or low)
* A **description** explaining what went wrong
Issues are grouped by label and impact level, making it easy to see patterns. Common issue types include build failures, environment configuration problems, incorrect assumptions about the codebase, and scope ambiguity.
**Timeline** provides a chronological, color-coded view of key events during the session:
| Color | Meaning |
| ---------- | ------------------- |
| Red | High impact issue |
| Yellow | Medium impact issue |
| White/Gray | Significant event |
| Green | Value provided |
Each timeline event has a title and description. Events linked to specific issues appear in bold. Use the timeline to understand the flow of the session — where Devin made progress, where it hit obstacles, and how it recovered.
### Actionable Feedback
The Actionable Feedback tab helps you improve future sessions in two ways:
**Improved Prompt** shows a rewritten version of your original prompt with specific improvements. The suggested prompt is displayed with interactive highlighting — hover over an underlined section to see what changed and why. A numbered list of **Changes Made** below the prompt explains each modification:
* Added context or constraints that were missing from the original
* Clarified ambiguous instructions
* Included success criteria or specific requirements
* Frontloaded important information that Devin needed earlier
Click **Start new session** to launch a new Devin session pre-filled with the improved prompt.
**Action Items** lists recommended configuration changes to improve future sessions. These are concrete steps you can take in your [environment configuration](/onboard-devin/environment) or [Knowledge](/product-guides/knowledge) setup:
* **Machine setup** — environment or tooling changes (e.g., installing missing dependencies, configuring access)
* **Repo config** — repository-level changes (e.g., adding build scripts, updating configuration files)
Click **Go to machine** to navigate directly to your machine configuration and apply the suggested changes.
### Knowledge Usage
The Knowledge Usage tab shows how your [Knowledge](/product-guides/knowledge) items were used during the session:
**Useful Knowledge** lists knowledge items that helped Devin complete the task successfully, with an explanation of how each piece of knowledge was applied.
**Misleading Knowledge** lists knowledge items that led Devin astray or contained outdated or incorrect information. Each entry explains why the knowledge was harmful, helping you identify items that need updating or removal.
Click on any knowledge item to navigate directly to it and make edits. Regularly reviewing this tab helps you maintain a high-quality knowledge base.
## Interpreting Common Insight Patterns
### High ACU Usage with Few User Messages
This typically means Devin worked autonomously but struggled with the task. Check the Issue Timeline for recurring errors or retries. Common causes:
* Missing environment setup (dependencies, API keys, access credentials)
* Ambiguous requirements that led to trial-and-error approaches
* Complex tasks that would benefit from being broken into subtasks
**What to do:** Review the Improved Prompt for suggestions on adding context. Check Action Items for machine or repo configuration changes.
### Many User Messages with Low ACU Usage
This suggests frequent interruptions or course corrections. Devin spent little compute but needed constant guidance. Common causes:
* Underspecified initial prompt
* Devin misunderstood the task scope or requirements
* The task required domain-specific knowledge not available to Devin
**What to do:** Use the Improved Prompt as a template for future similar tasks. Add relevant details to your [Knowledge](/product-guides/knowledge) so Devin can access them automatically.
### Misleading Knowledge Flagged
When the Knowledge Usage tab shows misleading knowledge items, those items may contain outdated instructions or overly broad advice that conflicts with your current codebase. Common causes:
* Knowledge was written for a previous version of your codebase
* Knowledge is too general and gets retrieved in irrelevant contexts
* Knowledge conflicts with other knowledge items
**What to do:** Update or delete the flagged knowledge items. Make knowledge trigger descriptions more specific to avoid irrelevant retrieval.
### Session Classified as Wrong Category
If the category shown in the overview does not match what you intended, it likely means Devin interpreted your request differently. Common causes:
* The prompt was ambiguous about the goal
* The task description focused on one aspect but the intent was different (e.g., describing a bug when you wanted a feature)
**What to do:** Compare the category with your intent. Use the Improved Prompt to see how the analysis recommends clarifying the task objective.
### Timeline Shows Repeated Issues
When the same issue type appears multiple times in the timeline, Devin likely got stuck in a retry loop. Common causes:
* A persistent build or test failure that Devin could not resolve
* An environment issue (missing tool, wrong version, permission error)
* A fundamental misunderstanding of the approach needed
**What to do:** Check Action Items for environment fixes. Consider adding a [Knowledge](/product-guides/knowledge) item that explains the correct approach for this type of task.
## Best Practices
### Review Insights After Complex Sessions
Make it a habit to check Session Insights after important or complex sessions. The patterns you identify will help you become more effective over time.
### Apply Prompt Improvements Iteratively
Use the suggested improved prompts as starting points for similar future tasks. Over time, you will develop a library of effective prompt patterns. Save your best prompts as [Playbooks](/product-guides/creating-playbooks) for repeatable workflows.
### Maintain Your Knowledge Base
Regularly review the Knowledge Usage tab to keep your knowledge items accurate and relevant. Remove or update misleading knowledge promptly — a single outdated knowledge item can degrade session quality across your entire team.
### Address Recurring Issues via Machine Setup
If Action Items consistently recommend the same environment or configuration changes, address them proactively. Setting up your [environment configuration](/onboard-devin/environment) correctly prevents repeated issues across all future sessions.
### Share Insights with Your Team
Session Insights can reveal patterns that benefit your entire organization. Add key learnings as [Knowledge](/product-guides/knowledge) so your teammates can benefit from them.
### Keep Sessions Focused
If your sessions consistently classify as L or XL, break large tasks into smaller, more focused sessions. Smaller sessions tend to produce better results and are easier to analyze and iterate on.
## Troubleshooting
### No Insights Available
If Session Insights is not available for a session, it may be because:
* Analysis has not been triggered yet — click **Generate Analysis** in the Session Insights modal or use the [generate API endpoint](/api-reference/v3/sessions/post-organizations-session-insights-generate)
* The session is still in progress
* The session was too short to generate meaningful analysis (fewer than one Devin message)
* There was an error during the analysis process — try clicking **Regenerate**
### Analysis Takes Too Long
Analysis generation typically completes within a minute. If it has been generating for more than five minutes, the process may have timed out. Close and reopen the Session Insights modal, then click **Regenerate**.
### Investigate with Devin
The **Investigate with Devin** button in the Session Insights modal opens a new Devin session pre-configured to analyze the original session in depth. Use this for sessions where the automated analysis alone does not fully explain what happened.
# Skills
Source: https://docs.devinenterprise.com/product-guides/skills
Teach Devin reusable procedures by committing SKILL.md files to your repos
## What are Skills?
Skills are `SKILL.md` files you commit to your repositories that teach Devin **reusable procedures** — any repeatable workflow you want Devin to follow consistently. Testing your app before opening a PR, deploying to an environment, investigating a codebase, scaffolding a new service — if you can write it as step-by-step instructions, you can turn it into a skill.
They follow the open [Agent Skills standard](https://agentskills.io/specification), so the same skill files work across multiple AI coding tools.
Place skill files at `.agents/skills//SKILL.md` in your repository. Devin automatically discovers them across all your connected repositories. See the [Agent Skills specification](https://agentskills.io/specification) for the full file format reference.
## Why Skills Matter
Without skills, Devin has to figure out workflows from scratch every session. With skills, you define a procedure once and Devin follows it reliably every time. Skills are useful whenever you have a workflow that:
* **Should be done the same way every time** — testing checklists, deployment steps, review procedures
* **Requires repo-specific knowledge** — which services to start, what ports to use, which commands to run
* **Benefits from dynamic context** — pulling in git diffs, branch names, or environment info at invocation time
## Devin Suggests Skills Automatically
Devin can automatically suggest skills for you. After Devin tests your application or learns something new about your setup during a session, it will suggest creating or updating a skill to capture that knowledge. You'll see a suggestion in your session timeline with:
* A summary of what was learned (e.g. "how to start the backend with Docker")
* The proposed `SKILL.md` file contents
* A **"Create PR"** button to commit the skill to your repo
Over time, Devin builds up a library of skills in your repo about how to run, test, and deploy your application.
## Examples
### Testing before opening a PR
A skill that tells Devin how to verify a Next.js app before creating a pull request:
```markdown theme={null}
---
name: test-before-pr
description: Run the local dev server and verify pages before opening any PR that touches frontend code.
---
## Setup
1. Install dependencies: `npm install`
2. Start the database: `docker-compose up -d postgres`
3. Run migrations: `npx prisma migrate dev`
4. Start the dev server: `npm run dev`
5. Wait for "Ready on http://localhost:3000"
## Verify
1. Read the git diff to identify which pages changed
2. Open each affected page in the browser
3. Check for: console errors, layout issues, broken links
4. Screenshot each page at desktop (1280px) and mobile (375px) widths
## Before Opening the PR
1. Run `npm run lint` and fix any issues
2. Run `npm test` and confirm all tests pass
3. Include screenshots in the PR description
```
### Deploying to an environment
A skill that deploys the app using arguments for the target environment, with dynamic content injection:
```markdown theme={null}
---
name: deploy
description: Deploy the app to a target environment and run smoke tests.
argument-hint:
triggers: ["user"]
---
## Deploy
1. Make sure you are on the correct branch for this deploy
2. Run `./scripts/deploy.sh $1`
3. Wait for the deploy script to complete successfully
## Verify
1. Curl `https://$1.example.com/health` and confirm a 200 response
2. Run the smoke test suite: `npm run test:smoke -- --env=$1`
3. Report the deployment URL and test results
## Current context
- Branch: !`git branch --show-current`
- Last commit: !`git log --oneline -1`
```
Invoking with `@skills:deploy staging` substitutes `staging` for `$ARGUMENTS` and `$1`, and the `` !`command` `` blocks inject live git info. The `triggers: ["user"]` field ensures Devin only runs this skill when you explicitly ask for it — it won't auto-activate.
### Investigating a part of the codebase
A skill for guided code exploration that restricts Devin to read-only tools:
```markdown theme={null}
---
name: investigate
description: Research a part of the codebase and produce a written summary with file references.
allowed-tools: Read, Grep, ListDir
argument-hint:
---
## Research
1. Search the codebase for files related to: $ARGUMENTS
2. Read the most relevant files thoroughly
3. Trace the call chain and data flow
## Summarize
1. Write a summary of how $ARGUMENTS works
2. Include specific file paths and line numbers for every claim
3. Note any concerns, edge cases, or areas that need attention
```
The `allowed-tools` field restricts Devin to read-only operations — no editing, no shell commands. This is useful for exploration tasks where you want analysis without side effects.
## Skill Discovery
Devin discovers skills from **two sources**, merged together at the start of every session:
1. **Indexed repos** — Devin's backend indexes `SKILL.md` files across all repositories connected to your organization. These are available immediately when a session starts, before any repos are cloned.
2. **Cloned repos** — As repositories are cloned onto the session's machine, Devin scans them for `SKILL.md` files on disk. Disk-scanned skills update or override any matching indexed skill from the same repo, ensuring Devin always uses the latest version on the branch being worked on.
When a repo clone completes mid-session, Devin automatically re-scans that repo so newly added or modified skills are picked up without restarting.
### Supported Skill File Locations
Devin searches for `SKILL.md` files in all of the following directories:
* `.agents/skills//SKILL.md` **(recommended)**
* `.devin/skills//SKILL.md`
* `.github/skills//SKILL.md`
* `.claude/skills//SKILL.md`
* `.cursor/skills//SKILL.md`
* `.codex/skills//SKILL.md`
* `.cognition/skills//SKILL.md`
* `.windsurf/skills//SKILL.md`
* `.codeium/skills//SKILL.md`
All nine paths are scanned in every repo.
### What Devin Loads from a Skill File
When a skill is discovered, Devin parses the YAML **frontmatter** (the `---` block at the top) and extracts:
| Field | Purpose |
| --------------- | ---------------------------------------------------------------------------------- |
| `name` | Identifies the skill. Falls back to the parent directory name if omitted. |
| `description` | Short summary shown in the skill list so Devin (and you) know what the skill does. |
| `allowed-tools` | Restricts which tools Devin can use while the skill is active. |
Devin also supports these additional frontmatter fields beyond the standard spec:
| Field | Purpose |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| `argument-hint` | Hint text shown alongside the skill name describing expected arguments. |
| `triggers` | Controls who can invoke the skill — `["user", "model"]` by default. Set to `["user"]` to prevent Devin from auto-activating it. |
Everything **after** the frontmatter is the skill body — the step-by-step instructions Devin is prompted to follow when the skill is invoked.
See the [Agent Skills specification](https://agentskills.io/specification) for the full file format reference.
## How Devin Uses Skills
At the start of every session, Devin sees a list of all available skills (name + description). When a skill is **invoked**, Devin reads the full `SKILL.md` file and injects its body into its current context as a system-level instruction. This means Devin actively follows the skill's steps for the remainder of the task — it's not just a reference, it directly guides Devin's behavior.
Devin can use skills in several ways:
### Automatic invocation
When Devin determines a skill is relevant to the current task, it invokes it automatically. For example, if you ask Devin to fix a bug in frontend code and there's a `test-before-pr` skill, Devin will activate it before opening the PR. Set `triggers: ["user"]` in the frontmatter to prevent auto-invocation for skills you only want triggered explicitly.
### Mention a skill in your prompt
You can tell Devin to use a specific skill by including `@skills:skill-name` in your message:
```
Fix the login bug on the /auth page @skills:test-before-pr
```
You can also pass arguments:
```
@skills:deploy staging
```
The arguments are substituted into the skill body wherever placeholders appear: `$ARGUMENTS` is replaced with the full argument string, and `$1` through `$9` with the individual whitespace-separated arguments (missing ones become empty). If the skill body contains no placeholders, the arguments are appended to the end of the skill content instead. `$0`, `$10` and beyond, and other dollar expressions like `$HOME` are left as-is.
### One active skill at a time
Devin can only have one skill active at a time. Invoking a new skill replaces the previous one. When active, Devin is prompted to follow the skill's steps in order and complete each one before moving on.
### Searching and listing
Devin can search for skills by keyword or directory if it needs to find the right one mid-session. You can also ask Devin to list available skills or reload them after you've pushed changes to a skill file.
## Limitations
* **Global / org-level skills** — Today, skills live inside repositories. For org-wide skills, you can create a dedicated "skills" repo as a workaround. We're exploring first-class support for org-level skills that apply across all repos.
* **Composing multiple skills** — Currently only one skill can be active at a time. We're working on support for chaining and composing workflows.
## Skills vs. Playbooks
Both skills and [playbooks](/product-guides/creating-playbooks) give Devin reusable instructions, but they work differently:
| | Skills | Playbooks |
| ------------------------- | ------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- |
| **Where they live** | In your repo as `SKILL.md` files — version-controlled alongside your code | In the Devin web app — managed through the UI |
| **How they're triggered** | Devin discovers and invokes them automatically, or you reference them with `@skills:name` in any prompt | Manually attached to a session when you start it |
| **Scope** | Scoped to a repo — Devin picks up the right skills based on which repos are relevant to the task | Org-wide — any team member can attach any playbook to any session |
| **Auto-suggestion** | Devin suggests new skills after testing your app or learning something new | Created manually by team members |
| **Best for** | Testing procedures, local dev setup, deployment checklists, repo-specific workflows | Reusable prompt templates, cross-repo task patterns, onboarding guides |
**Which should I use?** If your instructions are tied to a specific repo — how to run it, test it, or deploy it — use a skill. If your instructions are general-purpose prompts that apply across repos or teams, use a playbook.
## Learn More
* [Agent Skills specification](https://agentskills.io/specification) — the open standard for `SKILL.md` file format, frontmatter fields, and directory structure
* [Knowledge](/product-guides/knowledge) — for contextual tips and facts (not step-by-step procedures)
* [Playbooks](/product-guides/creating-playbooks) — for reusable prompt templates attached to sessions
# Using Playbooks
Source: https://docs.devinenterprise.com/product-guides/using-playbooks
## How to use Playbooks
To use playbooks simply select one from your Team or the Community library. You've successfully attached a playbook if you see a blue pill appear, along with an inline component for editing the playbook before starting your session.
Alternatively, you can attach a `.devin.md` file when you start your Devin session.
### Using macros
If a playbook has a **macro** assigned (e.g., `!data-tutorial`), you can quickly attach it by typing the macro name in the prompt input box. This is a convenient shortcut when you know the macro identifier for the playbook you want to use.
Once you start the session, you should see your playbook show up with a grey background in the chat with Devin!
## Refining Playbooks
As you run a new playbook with Devin, you'll identify opportunities to improve the instructions so that Devin can complete the task more reliably. Here are some helpful features for **iterating on playbooks live**:
## Example Gallery
Check out the Community Gallery at [https://app.devin.ai/settings/playbooks](https://app.devin.ai/settings/playbooks):
# 2024
Source: https://docs.devinenterprise.com/release-notes/2024
**Devin is now generally available!**:
Check out our [announcement on X](https://x.com/cognition_labs/status/1866535303911182771). All engineering teams can now tag Devin to fix frontend bugs, create first-draft PRs for backlog tasks, make refactors, and more. Subscriptions start at \$500/month and include:
* Unlimited seats - Devin is built for engineering teams
* Access to Devin's API, integration for Slack, and IDE extension
* Onboarding session & direct support from the Cognition engineering team
**Devin is now faster and more cost-efficient**:
Over the last 2 weeks, we've made Devin \~10% faster and \~10% more cost-efficient, especially for tasks that require Devin to make many code edits. This means the same task will require fewer Agent Compute Units (ACUs).
**Fixes for crashing, stuck, and hanging Devins**:
If you've noticed Devin stuck on the same action or unable to sleep/wake up, please let us know via Slack Connect or [support@cognition.ai](mailto:support@cognition.ai). These issues should not happen again, and we're happy to refund your ACUs if they do!
**More options to customize Devin**:
By default, sessions in your sidebar are filtered to non-archived sessions that you started. Change your default filters by clicking on the filter icon next to "Search sessions" > "Save as Default" at the bottom of your filters list.
By default, Devin automatically responds to PR comments and CI failures. Change this using the "Control Options" section in Devin's PR comment.
Always receive Slack notifications from Devin, even when you start sessions from the web app. Turn on Slack notifications in Settings > Profile.
Customize whether Devin sessions start in existing or new Slack threads, whether Devin waits for you to approve its plan, and more in Settings > Customization.
Devin can send Slack updates on its GitHub activity. Configure the channel these updates are sent to in Settings > Integrations.
Share Devin sessions you start in the web app to Slack. You can now change the default channel.
**Configure + monitor Devin's machine**:
If you need to increase Devin's machine size (disk space, RAM, CPU), we've added additional options in Settings > Devin's Workspace > Danger Zone.
You can always monitor Devin's machine utilization during a session, in the top right corner of the session page.
**Pinned and auto-updated Knowledge**:
Knowledge Devin should always remember when working in a repository can now be pinned.
Devin also auto-generates and auto-updates its own Knowledge on repo structure and components. Find auto-generated notes under Knowledge > Repo Knowledge.
**Bring Devin into conversations just as you would with human teammates**:
Tag @Devin on bug reports and feature requests directly on Slack:
* Devin pulls in context automatically
* Message Devin from your phone
* All Slack sessions also link to a webapp session
Recent improvements to our integration for Slack:
* Say "sleep" to put Devin to sleep. Devin only wakes up again when you tag @Devin in thread
* Say "archive" to put Devin to sleep + archive the session
* Turn on Slack notifications in sessions started from the webapp, you're now able to (1) interact with Devin in Slack (2) receive updates in the Threads section of Slack
**Devin responds to PR comments and lint errors automatically**:
Ask Devin to create a PR! Recent improvements to our PR workflow:
* When the PR receives comments or fails lint, Devin will automatically wake up to address it if it's sleeping
* Click "PR Preview" under the session title to see the changes Devin has made before a PR has been created. If Devin makes edits, you'll see a "Jump to Latest" button appear in the top right
**Use Devin as your todo list**:
Try sending tasks to Devin as they come up, instead of adding them to your todo list. Hide completed sessions with the new archive button next to the session title.
Archived sessions show up under Folder > Archived in the left sidebar.
**Configure Devin's Behaviors**:
[Configure Behavior in Settings](https://app.devin.ai/customization) to customize Devin's behavior to your needs. These settings are user-specific and will not affect other users in your organization.
The first behavior you can now configure is Agency.
When Devin detects a task that requires codebase information, it will begin by investigating the repo and creating a plan. When Agency is turned on, Devin will proceed with its plan without waiting for your approval. Devin will always ask you whether you want to override this per-session.
**Configure Devin's Workspace**:
Devin's Workspace resets to a saved machine state at the start of every session. By default this machine state includes all the repositories you've added and set up at app.devin.ai/workspace.
> Tip: Setting up Devin's Workspace significantly improves Devin's performance on your codebase. Imagine if every time you started a task, your laptop and part of your memory were wiped - that's what happens to Devin without setup!
Behind the scenes, all repositories you set up co-exist on the same (default) machine state at the start of every session.
**Bulk import secrets**:
If your repo requires many secrets, share them with Devin in bulk [in the Secrets section of settings](https://app.devin.ai/secrets) -- coming soon to the repo onboarding workflow.
**Faster navigation with cmd-k**:
Use cmd-k to quickly start a new session and navigate the web applications
**Talk to Devin from your IDE (Beta Access)**:
Handoff async work to Devin while you focus on your primary task. Review when convenient.
* Works in conjunction with Copilot and Cursor
* Devin's just a shortcut away (Cmd+G)
* Keep track of your active Devins
* Review and accept code directly in your local IDE
[Install the Devin Extension](https://marketplace.visualstudio.com/items?itemName=cognition.devin) to get started.
**Use macros to easily attach [Playbooks](/product-guides/creating-playbooks) (from Slack, Devin IDE, or webapp)**:
A macro is a shortcut (e.g. !macro) that can be used to quickly attach a Playbook to your initial prompt to Devin. [Navigate to your Playbook in your Library](https://app.devin.ai/playbooks) and click "Edit" to set the macro for each Playbook.
**Planning mode**:
For certain tasks, much of the work needed is figuring out what should be done and aligning on the approach. Devin will now automatically detect more complex tasks and spend time proposing a plan before beginning execution.
You can always auto-approve the plan if you don't want Devin to wait for your approval.
**Programmatically create Devin sessions and retrieve results (including structured output) using our new REST API**:
Our new RESTful API allows you to integrate Devin into your own applications, write scripts to kick off multiple sessions in parallel, and build powerful automation workflows on top of Devin.
You'll be able to specify a structured output format in your prompt, for example:
```txt theme={null}
Devin, we're using auth0 instead of clerk - can you remove clerk support from the provided file? Output format: {lines_edited: int, success: bool}
```
View structured output in the web app on any session page with CMD+i, or click "Show structured IO" in the dropdown menu in the top right corner of your chat.
You can obtain an API key from your [settings page](https://app.devin.ai/settings/api-keys).
Read our [API documentation](/api-reference/overview) to learn more and view an example of how to use the API.
**It's now easier to understand what Devin's been up to with the "Follow Devin" tab**:
The "Follow Devin" tab is designed to make it faster to understand what Devin's been up to - it highlights Devin's actions (file edits, shell commands, etc) as Devin works. Click on the magnifying glass icon to jump to the associated tool (editor, shell, browser, planner) for more information.
**To be successful with Devin, upfront investment is usually required - our new Onboarding Flow walks you through the required steps**:
Onboarding steps include:
* Connecting your GitHub organization - this enables Devin to **scan your codebase** and generate [Repo Knowledge](/product-guides/knowledge). GitHub also enables Devin create PRs and **respond to your PR comments automatically**!
* Connecting your Slack organization allows you to kick off sessions and respond to Devin in the same place where you interact with your human teammates! Next time someone reports a frontend bug, try tagging @Devin in the channel to address it!
* Manually [setting up Devin's machine](/onboard-devin/environment). If your repository requires developers to have environment variables or dependencies installed, it's important to set up Devin's machine. Otherwise, Devin will spend its limited resources figuring out setup before it's able to tackle the task you give it.
**You'll receive warnings if Devin is about to sleep**:
Previously, users on our Personal and Team plans might've noticed that Devin may sleep unexpectedly.
This is now fixed, and if Devin is about to sleep because it's low on ACUs or close to per-session ACU limits (which reset with each new instruction and can be configured in [Settings > Usage](https://app.devin.ai/settings/usage)), you'll receive a toast notification in the web app!
**Repo knowledge**:
Devin will now automatically **scan your repositories** and generate [Repo Knowledge](/product-guides/knowledge). This allows Devin to more quickly and successfully do real work for you in your repo. You can always add and edit your own Knowledge manually in [Settings > Knowledge](https://app.devin.ai/knowledge)
**Increased options for Enterprise users**:
Enterprise users now have more options to configure Devin to meet your organization's needs, including:
* **Single sign-on with Okta**
* **Auto-Join for Company Domains:** Allow any user with a company email to join Devin without individual invites
* **Customized Onboarding:** Tailor example sessions and suggested prompts to guide your organization's users to Devin's most valuable use cases
* **Usage Insights:** Automated email alerts to track your usage over time
**A new home page, designed for longer prompts and smaller screens**:
Devin often works best when you share detailed context and requirements upfront. With our redesigned home page, the input box expands as you type and feels more like a file editor:
* press Enter for new lines
* use Cmd + Enter (or Ctrl + Enter) to send your message
* paste example code snippets or lists of requirements to try our rich text features
**\[Beta] Devin API**:
The Devin API allows you to spin up Devin sessions programmatically. Use cases range from automatic PR reviews and lint error resolution to providing internal services for migrations. Currently available for our Enterprise users - contact us at [support@cognition.ai](mailto:support@cognition.ai) to learn more!
**Faster session and workspace navigation**:
It's now much faster to scrub Devin's workspace, switch sessions, and start new sessions in the Devin web app.
**We've migrated our authentication system to Auth0**:
You'll notice a new design on our login page, but you'll be able to log in as normal using your email, Google, or GitHub credentials.
**Introducing Devin for Teams**:
With our Team plan, your entire team can create, share and collaborate together in Devin sessions. The Team plan includes everything in the Personal plan, plus:
* Unlimited seats
* Access to our integration for Slack
* A larger ACU (Agent Compute Unit) capacity included with your monthly subscription
* A dedicated workspace for your team to create, share, and collaborate in Devin sessions together
Contact us at [support@cognition.ai](mailto:support@cognition.ai) to learn more!
**Devin responds to comments on PRs**:
Try reviewing Devin's code via GitHub or GitHub Mobile - Devin will automatically respond as long as the session hasn't ended and Devin isn't sleeping.
**Devin suggests Knowledge**:
Try giving Devin feedback in chat! Devin will automatically suggest new additions to Knowledge if something seems useful for future sessions.
Knowledge is a collection of tips, documentation, and instructions that Devin "knows" across all future sessions. Devin will automatically recall relevant Knowledge as necessary, and you can always manually add or review Knowledge in **Settings & Library** > **Knowledge.**
**Let Devin create Devins with MultiDevin**:
Tackle large backlogs of tasks by delegating to a team of Devins that work in parallel. MultiDevin consists of 1 "manager" Devin and up to 10 "worker" Devins.
The manager Devin distributes a task to each worker Devin, then merges the changes from all *successful* worker Devins into one branch or pull request. MultiDevin is great for repeated, isolated tasks like lint errors, code clean-ups, migrations, refactors, and more!
**Enterprise VPC Deployment**:
Devin offers an enterprise deployment option tailored for organizations with stringent security and compliance requirements. Our cloud-agnostic solution allows Devin to deploy DevBoxes within your own Virtual Private Cloud (VPC) and to store data within your cloud, ensuring your data remains exclusively within your controlled environment.
**"Wake up" old Devin sessions**:
Previously, Devin sessions ended after long periods of inactivity. Now, most sessions will "sleep" instead, meaning that you can wake Devin up and resume the session at any point.
You can still end sessions manually with the "stop" button at the top right corner of the chat.
**Send Devin code reviews in product**:
Ask Devin questions or ask for edits to specific lines of code. The code you comment on will be sent to Devin in one chat message.
Simply highlight any text in Devin's editor and click "Add to chat" or "Add a comment".
**Universal Planner**:
With Universal Planner, Devin can now more reliably perform long, multi-step tasks that require **looping** - in other words, tasks that require performing the same action multiple times - without needing to use Playbooks.
Playbooks are still recommended for tasks and prompts that will be run multiple times or prompts that are helpful to share with your team.
**Devin got smarter!**:
Many of our improvements this week have been behind the scenes **improvements to Devin's instruction following, editing, planning, and speed:**
📚 Playbooks **no longer expect or require a rigid structure** (e.g. ## Procedure section is no longer needed)
💬 Devin is a better **communicator!** When Devin makes notable deviations from the initial plan, it will inform you more reliably.
🔢 Devin is less reliant on playbooks and can follow ad-hoc plans more effectively
**Add secrets to library mid-session**:
Convenience improvement for secrets management:
**General UI Improvements**:
We've done some cleanup to our **mobile UI, settings page, and session controls.**
**Devin is now faster!**:
You'll notice that Devin has a faster time to the first message, and is quicker at completing some actions. Expect more improvements in the coming days!
**Devin's Work Log**:
Devin now maintains a work log in its planner. More quickly grok what Devin's accomplished with the work log!
Open the accordions to read Devin's retro of its work at each step. 🟢/ 🟠 / 🔴 correspond to A/B/C grades. You'll also find timestamps and how long Devin spent at each step.
**Devin Mobile Improvements**:
Try Devin while on the go - Devin mobile is now more usable, although we have a couple other improvements in the works!
**Integration for Slack 2.0**:
**Create sessions directly from Slack, attach Playbooks and Snapshots using Slack's convenient modal interface!**:
Look for the **"Create a new session"** option in the message menu (you may need to click **"More message shortcuts"** the first time you try this)
Also try the **/devin shortcut** or open Slack's shortcut launcher
**Use "send to channel" to mirror sessions started via the web app on Slack**:
This enables anyone in the channel (with Devin access) to quickly follow along and collaborate with Devin!
**Seamless communication across Slack channels and web app**:
Messages sent via the web app are now mirrored in Slack threads and vice versa
**Turn on Slack notifications mid-session**:
Slack notifications are now more informative, containing message contents and session title.
**Use Devin's Editor and Shell**:
It can sometimes be more convenient to directly take actions for Devin, rather than providing instructions for Devin to follow.
We're excited to share that you can now directly use Devin's machine. The new "Use Devin's Machine" button in the web interface opens VSCode in a new tab. Using VSCode, you can directly read and edit Devin's files, as well as open up a terminal in Devin's machine.
**Playbook Editing**:
Quick edit a playbook before sending it to Devin. Selected playbooks show up inside of the input box and the input box can be expanded, enabling fast and convenient edits to a Playbook before sending it to Devin.
Inline and in-session playbook edits won't be reflected in the Playbook Library unless you click the **"Update Playbook in library"** button. Alternatively, save your edits as new Playbook with the **"Create new Playbook in library"** button.
**Forbidden Actions Reliability**:
Devin now abides by forbidden actions more reliably when it's told what not to do via user messages or Playbooks.
```jsx theme={null}
## Forbidden Actions
- Do NOT touch any Kotlin code
- Do NOT push directly to the main branch.
- Do NOT work on the main branch
- Do NOT commit changes to the yarn.lock or package-lock.json files unless asked to explicitly.
```
**Playbooks Library & Past Runs**:
Explore how your teammates are using Playbooks in the new "Past runs" tab, and directly select Playbooks from library
**Ask Devin about Devin**:
Devin is now aware of its own product features and improvements! Try asking Devin what it knows about the Devin web app, and it'll explain its features and where to find them.
**Start Duplicate Sessions**:
Quickly kick off 2+ similar sessions with the new **"Start duplicate session"** button in the sidebar. You'll be redirected to the Devin home page with your initial message pre-populated along with any attachments, playbooks, and snapshots.
We recommend kicking off 2+ Devin sessions for some tasks, to give Devin more chances to succeed!
**Home Screen Upgrades & Shortcuts**:
The new Devin home screen makes it faster to explore and select Playbooks and Snapshots. We also introduced **Shortcuts.** Select a snapshot and/or playbook and save them as a shortcut so that they're quick to reuse!
**PR Metrics Dashboard**:
The PR metrics view aggregates all PRs made by Devin. The PR metrics view is available at [https://app.devin.ai/metrics](https://app.devin.ai/metrics)!
**Session Filtering**:
Quickly filter all of your sessions by creator, status, playbook, date, etc.
**Playbooks Library**:
You can now easily create, view and use playbooks by going to the **Devin app > Library > Playbooks.** You'll be able to create playbooks for your personal use cases, and explore playbooks from the community. Any playbooks you create will be shared with your team.
You can click in any of your Team or Community Playbooks to see example runs as inspiration for how to use a given playbook.
**Playbook Compiler**:
With the playbook compiler, you can now quickly iterate on your playbook to make sure the format, structure and content are optimized for the best playbook session results.
Tip:
* Write your playbook in the **Content** on the left hand side
* Click compile and review the newly formatted Playbook
* You can always edit and update the compiled Playbook. When it's ready, click create!
**Interactive Browser**:
Interactive Browser allows users to directly use Devin's browser. This feature is especially helpful for browser tasks where Devin may require assistance, such as completing CAPTCHAs, multifactor authentication steps and more.
**Knowledge**:
Knowledge is a collection of tips, instructions, and organizational context for Devin. You can continually add to Devin's bank of knowledge over time, and Devin will automatically recall relevant knowledge as necessary.
You can easily add knowledge to Devin's "knowledge bank", or disable it if needed.
View when and how Devin is using Knowledge in any run's progress updates.
**View Code Updates**:
During a session, you can now click into Devin's progress updates to view specific code edits Devin made while working through the sub-tasks. You can also view these directly from the Editor.
Progress Updates View
Editor Updates View
Code updates will open a modal where you can track new code written by Devin up to that specific point in time in the session.
**View Shell Updates**:
During a session, you can now click into Devin's progress updates to view specific shell commands Devin used while working through the sub-tasks. You can also view the Command History from the Shell.
Progress View Shell Updates
**Shell Command History**:
Shell updates will show you the full Command History and related outputs. You can easily copy a command and output by clicking on the three-dots icon.
Any commands that are italicized are commands run at a future point in time in the session, you can jump to different points in time in the session by clicking on different commands in the Command History section.
**Machine Snapshot Startup Commands**:
For a given machine snapshot, you can now **set a list of startup commands that will be run at the beginning of every run**. Some details:
* The commands are run from `~`
* The commands run in sequence (so having `cd dir` and then `ls` will do `ls` from `dir`)
* Each command is given a 2 minute timeout (so you can't run long-running servers with these commands)
**Command History**:
With command history, you can easily see a list of all the commands that Devin ran, along with a preview of their outputs.
Tip:
* Click on a command to jump to the timestamp where Devin used the command.
* Click the menu icon (appears when you hover over a command) to copy the full output.
**Keep Alive**:
> Deprecation Warning: This is no longer a supported feature. Devin can be woken up again any time after going to sleep now. It is recommended that hosted services be deployed elsewhere with Devin's help.
Keep Alive will keep a session alive indefinitely, and will count against Technical Preview users' daily quota. Manually terminating a session will override Keep Alive.
Note that Keep Alive is useful for keeping any hosted services (devinapps.com links) alive, but is **not necessary** if Devin helps you deploy apps using third party services like Netlify, Firebase, Vercel, etc.
**Browser Notifications**:
Get notified when Devin sends you a message. You can find this under Settings > Profile.
**Pause Devin**:
The new pause button is a shortcut and alternative to telling Devin to pause.
**Open VS Code: Access Devin's machine**:
Open VS Code lets you read and edit files on Devin's machine just like if you were working with Devin in VSCode. You can also open up a terminal in Devin's machine, which means you have **full access** to Devin's machine.
💡 Tip:
Use VSCode with [environment configuration](/onboard-devin/environment) to set up everything Devin needs to be productive moving forward:
* Tell Devin **"Run `pwd` and then pause. Do not do anything else."**
* **Open VSCode and open up a terminal** once Devin is paused
* **Do any machine setup yourself** (install packages, configure repos, etc.)
* **Create a snapshot.** Moving forward start sessions with this snapshot - all your future Devins will benefit from the setup you prepared!
**Cookies + Persisted Secrets**:
With Persisted Secrets, any secrets that you add in the Settings page will be usable by Devin in all future Devin sessions.
Additionally, with site cookies, Devin will find that it's already logged in to sites you provide valid cookies for (no login required by Devin!).
* Note that **this is a beta feature** and may not work for some sites, but we've found that it works for Amazon and Resy, and are excited to explore together what else this enables!
* Additionally, Devin may still ask for credentials. You'll need to remind Devin to first check using its browser whether it's already logged in!
Learn more here: [Persisted Secrets + Site Cookies](/product-guides/secrets)
**\[Organizations] Unlist Sessions**:
> This feature is only available to Organizations, not Technical Preview or Personal accounts
My default, all new sessions are visible to your Team (aka Organization). To make a session private to you, click the menu icon (which appears on hover) next to your session name in the sidebar to find the Unlist session option.
**\[Organizations] Integration for Slack**:
> This feature is only available to Organizations, not Technical Preview or Personal accounts
Once you've connected Slack to your organization, you'll be able to initialize Devin directly just by tagging @Devin in Slack. Devin responds in-thread with updates and questions, just as in the regular chat interface.
You can also enable Slack notifications for specific runs and Devin will privately message you whenever there's a status update. To do so, simply click the Slack icon at the top of any run you'd like to be notified for.
💡 Tip: Use these inline Slack commands to manage your Devin session:
* "mute" → prevents Devin from sending further Slack messages.
* "unmute" → reverses the above.
* "(aside)" or "!aside" → causes Devin to ignore the message (useful for commenting on Devin's run in-thread).
* "EXIT" → ends the session.
* snapshot:\[snapshot-name] → Use a particular snapshot with your run
* playbook:\[playbook-name] → Use a particular playbook with your run
Learn more here: [Integration for Slack Guide](/integrations/slack)
# 2025
Source: https://docs.devinenterprise.com/release-notes/2025
**New Agent Upgrade**
All enterprise customers have now been upgraded to the newest version of Devin, powered by the latest architectural and model improvements. The legacy "Agent (old)" option has been removed from the Agent dropdown menu in the input box, ensuring all users benefit from the most advanced capabilities.
**Enterprise API v3 Metrics Endpoints**
New API v3 endpoints for tracking usage metrics and active users across your enterprise. Includes endpoints for sessions, searches, PRs, and daily/weekly/monthly active user metrics with time-series data. See [API Release Notes](/api-reference/release-notes) for details.
**Jira Project Mapping Search**
Added a search filter to the Jira project mapping modal.
**Child Session Indentation**
Batch sessions now appear visually indented under their parent session in the sidebar, making it easier to understand session hierarchies and navigate complex multi-session workflows at a glance.
**Repository Connection Warnings**
The repository side panel now displays a warning banner when a repository has a connection issue.
**Consumption Analytics Improvements**
Enhanced analytics dashboard with extended historical data:
* Historical cycles chart now displays 12 months of data (up from 5 months)
* New export functionality for previous billing cycles, enabling better cost analysis and reporting
**Computer Use Setting Update**
Removed the "Only available on the new agent" disclaimer from the computer use setting; this feature is now available across all agent versions.
**Copy PR Context Button**
New convenience feature allowing users to quickly copy PR context summaries to clipboard with a single click, streamlining code review workflows and external communication.
**Minor bug fixes and improvements**
Various bug fixes and performance improvements across the platform.
**Custom Slash Commands**
Organizations can now create and manage custom slash commands that expand into predefined text prompts when used in chat. Features include:
* Support for modifying default commands like /plan and /review
* Ability to create entirely new custom commands tailored to your team's workflows
* Command management interface for enterprise administrators
**Microsoft Teams Integration**
Users can now interact with Devin directly in Microsoft Teams channels by mentioning @Devin. The integration provides:
* In-thread responses with updates and questions to help with software engineering tasks
* Support for mapping Teams channels to specific Devin organizations
**Enterprise API v3 Enhancements**
New v3 API endpoints for advanced sessions, organization searches, and improved audit logs. See [API Release Notes](/api-reference/release-notes) for details.
**Service Users Created Date**
The service users page now displays the creation date for each service user.
**Minor bug fixes and improvements**
* The "Connected accounts" section in organization settings has been renamed to "Integrations".
**Data Analyst Devin (Dana)**
Dana, which is a version of Devin optimized for data analysis tasks, is now available for all users. To use Dana, simply connect a data source via MCP then start asking questions.
**Enterprise API v3 Updates**
New v3 beta endpoints and improvements for service users. See [API Release Notes](/api-reference/release-notes) for details.
**Service Users Page Improvements**
Unified role filter combining enterprise and organization roles into a single grouped dropdown for easier filtering on the service users page.
**Consumption Analytics**
New backend support for detailed consumption analytics and reporting, providing better visibility into resource usage across organizations.
**Enterprise Hypervisors Capacity Utilization**
The hypervisor monitoring page now shows usage as a percentage instead of max slots and available slots.
**Azure DevOps Webhook Support**
Automated PR comments and status updates for Azure DevOps repositories.
**Minor bug fixes and improvements**
Various bug fixes and performance improvements across the webapp UI, Slack integration, and DeepWiki.
**Enterprise API v3 Git Permissions Bulk Create Improvements**
The Enterprise API v3 Git Permissions bulk create endpoint now accepts up to 200 permissions per request, increased from the previous limit of 100. Additionally, the endpoint now validates requests to prevent common configuration errors:
* **Duplicate detection**: Requests containing identical permissions (same connection, repository path, and group prefix) are now rejected with a clear error message listing the duplicates.
* **Overlap detection**: Requests containing a repository-specific permission that conflicts with a group prefix permission are now rejected. For example, adding both `group_prefix: "myorg"` and `repo_path: "myorg/repo1"` for the same connection will fail, since the group prefix already covers that repository.
These validations help maintain a clean and unambiguous permission model, preventing confusion about which permissions are active and avoiding unexpected behavior when managing permissions.
**Enterprise API v2 Pagination Limit Update:**
* The maximum pagination limit for Enterprise API v2 query parameters has been reduced from 1000 to 200 for improved performance and reliability.
* This change affects all v2 Enterprise API endpoints with pagination, including sessions, members, organizations, groups, and user usage endpoints.
* The default limit remains 100, with a minimum of 1 and a new maximum of 200.
* Note: This change does NOT affect the v1 External API.
**Advanced Mode**
Released Advanced Mode under the "Advanced Features" section, which allows for advanced usage of Devin. Includes features like session analysis, playbook creation and optimization, and bulk knowledge management. The Advanced Mode features respect RBAC; playbook and knowledge modifying features are only available to users with the appropriate permissions.
**Multi-branch Repository Indexing**
You can now index and manage multiple branches per repository, not just the default branch. A new "Manage branches" side panel in the repositories page lets you add or remove branches for indexing, making it easier to keep documentation up-to-date across different development branches.
**Wiki Branch Selection**
Repository wikis now support viewing documentation for different branches. When multiple branches are indexed, a branch selector dropdown appears in the wiki interface, allowing you to switch between branches to view the appropriate documentation for your work.
**Hebrew Language Support for DeepWiki**
DeepWiki now supports generating documentation in Hebrew, expanding multi-language documentation capabilities for international teams.
**Interactive Mermaid Diagrams**
Mermaid diagrams in wikis now support pan and zoom functionality, making it easier to explore complex diagrams. The zoom is limited to prevent over-zooming, and clicking to drag no longer accidentally opens the diagram modal.
**Steerable Wiki Now Default**
The steerable wiki feature is now enabled by default for all users. You can customize repository documentation by uploading configuration files to adjust content detail, fix inaccuracies, and match team standards.
**MCP Usage Tracking for Enterprises**
MCP (Model Context Protocol) usage tracking is now available for all enterprise organizations, providing better visibility into how teams are using MCP integrations across the enterprise.
**Session Insights Improvements**
Added an "Investigate with Devin" button in the session insights modal, making it easier to dive deeper into session analysis and create follow-up tasks based on insights.
**Prefix-based Git Permissions**
Enterprise administrators can now create git permissions using prefix matching, allowing access to all repositories that start with a specific prefix (e.g., "myorg/frontend-" matches all frontend repositories).
**Mobile Wiki Improvements**
Improved mobile layout for wiki search bars and other wiki components.
**Minor Bug Fixes & Quality of Life Improvements**
Various bug fixes and performance improvements across the platform.
**Breadcrumb Navigation Redesign**
Redesigned breadcrumb navigation system with improved organization selector, enterprise organization management with favorites, and enhanced mobile responsiveness.
**New Devin Agent**
Added New Devin agent mode for Enterprise customers, which is a faster, more intelligent version of Devin. See [Devin Sonnet 4.5: Lessons and Challenges](https://cognition.com/blog/devin-sonnet-4-5-lessons-and-challenges) for more details.
**Document Titles**
Added descriptive document titles to all webapp pages for easier browser tab identification, including dynamic titles that show search queries.
**Repository Setup Steering Knowledge**
Added the ability to provide enterprise-wide knowledge for the synchronous repository setup agent at [https://app.devin.ai/settings/snapshots](https://app.devin.ai/settings/snapshots).
**Agentic Knowledge Management**
Improved agentic knowledge management, allowing Devin to contribute knowledge base entries within the folder hierarchy during sessions.
**Snapshots Organization**
Reorganized snapshots pages under /settings and improved snapshot management with bulk editing capabilities for better organization.
**Ada Renamed to Ask Devin**
Renamed Ada assistant to Ask Devin for clearer branding throughout the interface.
**Playbook Usage Visibility**
Added analytics for when playbooks are retrieved during sessions.
**Git Commit Authoring**
Added new git commit authoring option in customization settings to control commit attribution.
**Redshift MCP Production Ready**
Removed beta tag from AWS Redshift MCP integration.
**Slack Notification Safety**
Sanitized @everyone, @channel, and @here mentions in Slack notifications to prevent accidental mass mentions.
**Direct Attachment Download**
Improved attachment download functionality with direct download support for better performance.
**Wiki Edit Button Improvements**
Improved wiki edit button to work consistently across all git providers including GitHub, GitLab, Bitbucket, and Azure DevOps.
**Minor Bug Fixes & Quality of Life Improvements**
Various bug fixes and performance improvements across the platform.
**Unified Agent Selection Experience**
Consolidated agent selection into a streamlined experience with an improved agent switcher on the home page, making it easier to choose the right agent for your task.
**Clone Repository via API**
New V2 Enterprise Organizations API endpoint for enterprise admins to programmatically clone repositories and create snapshots with custom setup steps and startup commands.
**Enterprise Knowledge Folder Management**
Updated enterprise knowledge folder management with improved UI and restrictions on folder movement.
**Minor Bug Fixes & Quality of Life Improvements**
Various bug fixes and performance improvements across the platform.
**DeepWiki Codemaps**
Interactive code visualization is now available in DeepWiki, allowing you to explore codebases visually with an intuitive mode switcher that helps you navigate between different views of your repository documentation.
**Multi-language Wiki Support**
DeepWiki now supports generating documentation in multiple languages.
**Slash Command Improvements**
Enhanced slash command interface with visual badges and keyboard shortcut hints, making it easier to discover and use quick-start commands.
**GitLab PR Comments**
Devin can now read and respond to comments on GitLab pull requests.
**Searchable Channel Dropdown**
Channel selection dropdowns are now searchable for Slack and Teams integrations.
**Pre-selected User Roles**
When inviting new users to your organization, the most appropriate role is now pre-selected based on context.
**Minor Bug Fixes & Quality of Life Improvements**
Various bug fixes and improvements including better computer use event display, knowledge page filtering, and repository setup banner persistence.
**Steerable Wiki for GitHub and Gitlab**
Users now have the ability to upload .json files to adjust the contents of a DeepWiki to add more detail, edit any inaccuracies, and customize documentation to match team standards.
**Enterprise Playbooks API v2**
Updated Enterprise Playbooks API with improved functionality for programmatic playbook management.
**Slack Enterprise Grid Support**
Full support for Slack Enterprise Grid deployments, enabling larger enterprises to use Devin with their Slack infrastructure.
**GitLab CI/CD Integration**
Enhanced GitLab integration with support for viewing CI job logs and pipeline metrics directly within Devin, providing better visibility into build and deployment processes.
**Session Analytics Enhancements**
Added external link icons to the session analytics table, making it easier to open sessions directly from the analytics view.
**Minor Bug Fixes & Quality of Life Improvements**
* Product polish and design system migration for playbooks and settings pages
* Repository page improvements with better filtering and pagination
* Ongoing bug bashing and quality of life improvements
**Slash Commands in Input Box**
Quick-start your sessions with slash commands. Type `/plan`, `/review`, `/test`, or `/think-hard` in the input box to insert predefined task templates that help you structure your requests more effectively.
**Enterprise Knowledge Management**
Enterprise administrators can now create and manage organization-wide knowledge that's shared across all teams, making it easier to maintain consistent context and best practices throughout your enterprise.
**Enterprise Playbooks**
Playbooks are now available at the enterprise level, allowing administrators to create and manage reusable task templates that can be shared across all organizations within the enterprise.
**Repository Mentions as Attachments**
When you mention repositories in messages, they now appear as clean attachment badges with repository icons instead of inline text, providing a clearer visual distinction between message content and repository references.
**Knowledge Sharing by Default**
Knowledge entries now default to being shared within your organization.
**Minor Bug Fixes & Quality of Life Improvements**
Various bug fixes including improvements to steerable DeepWiki configuration, repository pagination, and general performance enhancements.
**Steerable DeepWiki**
Customize and guide your repository documentation with Steerable DeepWiki. Enterprise administrators can now add custom instructions and context to shape how wikis are generated for their repositories.
**Create Organization Page**
Redesigned UI of /settings/organizations/create for enterprise organization creation.
**Agent Dropdown Improvements**
When viewing an existing session, the agent dropdown now displays only the specific agent used for that session, making it clearer which agent version was used for each run.
**Agent Default Setting Hints**
The agent dropdown now includes helpful hint text explaining that starring an agent sets it as your default across all integrations, including Slack, VS Code, and the web interface.
**Slack Default Agent Tips**
Users receive a one-time ephemeral message in Slack with guidance on setting their default agent preference, helping teams adopt the latest agent versions more easily.
**Minor Bug Fixes & Quality of Life Improvements**
* Fixed bug preventing proper display of secrets page for organization members
* Fixed bug around gh CLI auth failing in certain circumstances on Devin's machine
* Enterprise API v2 git permissions endpoint now returns permission\_names dict mapping permission IDs to repo/group paths
* Enhanced member page tabs and navigation
* Ongoing stability improvements and bug fixes
**New Agent Preview using Sonnet 4.5**
A new version of Devin, built around the new capabilities and behaviors of Claude Sonnet 4.5, is now available. This agent is about twice as fast as the previous version of Devin, and can be enabled on a per-run basis or defaulted for all of a user's runs using the star in the dropdown. This agent is in beta, so not all functionality is supported at this time; it will not suggest knowledge, use cloud IDEs, or respect macros starting with ! (such as playbooks).
**Enterprise Opt-In for Agent Previews**
Enterprise customers can now opt-in to preview the new agent by enabling the "Use Sonnet 4.5" toggle in their enterprise settings.
**Inline Plan Display for Ask Devin**
When transitioning from an Ask Devin session into creating a prompt for the Devin agent to write code, the UX now displays generated plans inline with streaming content instead of in a modal.
**Session Analytics Consolidation**
The dedicated PR-only view has been consolidated with the "All Sessions" page for a unified view of session data and insights.
**MCP Observability for Enterprises**
Enhanced Model Context Protocol (MCP) observability tools are now available for enterprise customers, providing better visibility into MCP usage patterns and performance across your organization.
**Bitbucket Integration (Beta)**
Cloud Bitbucket integration is now rolling out in beta, providing improved git provider parity alongside existing GitHub, GitLab, and Azure DevOps support.
**GitHub PR Comment Improvements**
GitHub PR comments now support both `@devin` and `DevinAI` prefixes for triggering Devin, making it more intuitive to mention Devin in pull request discussions.
**Minor Bug Fixes & Quality of Life Improvements**
Fixed bug causing session URLs to not always work for enterprise administrators, as well as ongoing stability improvements.
**Session Analysis & Knowledge Management**
Enhanced session tracking and analysis capabilities with improved knowledge base management, curation tools, and prompt improvement system that preserves user context and @ mentions in the input box.
**Git permissions performance improvements**
Optimized git permissions page to support 200k+ elements with improved query performance, indexing, and pagination for GitHub repository listings.
**Minor Bug Fixes & Quality of Life Improvements**
* Fixed positioning of "Learn more" tooltip and link in message components by moving it inside a div container for better layout structure
* Removed login\_hint in new user authentication flow due to inconsistent behavior, preventing email from pre-filling during a user's first visit.
* Fixed a bug where you could not add more than one set of session-scoped secrets.
**API v2 knowledge sharing**
The `shared_in_org` field now controls knowledge visibility: true applies knowledge to the entire organization, false applies only to the creator of the knowledge.
**DeepWiki.com Thread Export Feature**
Added a "Copy Thread" button to the external deepwiki.com site for exporting Q\&A threads as markdown with citations. This feature is only available on the public deepwiki.com, not internal Devin wikis.
**Integrations page access**
All Devin users can now access integrations pages, expanding from previous restrictions that required specific management permissions to basic Devin usage permissions. Users still need admin in order to manage the specific integrations, but this enables all users to see which integrations are enabled.
**Enterprise Settings reorganization**
Reorganized Enterprise Settings sidebar into logical sections: Membership, Governance, Infrastructure, Integrations, and Analytics for improved navigation.
**UI text consistency**
Converted Title Case UI strings to sentence case throughout the application for improved consistency and readability.
**Slack UX improvements**
Enhanced integration for Slack with PR and webapp viewing buttons, more concise thread formatting, and improved overall user experience for Slack workflows.
**Enhanced MCP Configuration**
Improved MCP marketplace configuration page with inline raw secrets form, making it easier to configure MCP integrations by allowing users to create and link secrets directly within the configuration interface.
**API Secret Management**
Added new POST /v1/secrets endpoint for creating secrets via API.
**Enterprise Dashboard Enhancements**
Added sorting functionality to User Metrics table in enterprise consumption dashboard.
**Enterprise Infrastructure Management**
Added UI for updating hypervisor settings in enterprise configurations, providing administrators with better control over infrastructure management.
**Bug fixes and improvements**
Various reliability, performance, and usability improvements across the app.
**Wiki Sidebar Improvements**
The wiki sidebar now displays cleaner repository names without full paths, making it easier to navigate through your indexed repositories.
**Settings Navigation Enhancement**
Standardized breadcrumb styling across Settings > Integrations pages for more consistent navigation experience throughout the application.
**Self-Hosted GitLab Access**
Added query parameter support to enable self-hosted GitLab connection modal for enterprise users who need this integration option.
**Figma MCP OAuth Support**
Enhanced the Figma integration in the MCP marketplace with OAuth authentication support for secure access to Figma files and resources.
**Enterprise API Key Management**
Improved error handling and user experience for service API key provisioning, including better messaging for organizations with existing keys.
**Mobile Sidebar Improvements**
Fixed sidebar display issues on mobile devices for better navigation experience across all screen sizes.
**Bug fixes and improvements**
Various reliability, performance, and usability improvements across the app.
**Referral Information Alert**
Added informational alert to Settings → Referrals page explaining referral rewards and success criteria for better user guidance.
**Enhanced Linear Integration**
Improved Linear integration with per-team/organization trigger conditions and status-based Devin triggering for more granular control.
**GitHub Connection Management**
Added "Manage Connection" button for GitHub PAT connections and improved token display by removing @ prefix for non-individual tokens.
**Azure DevOps Display**
Enhanced Azure DevOps connection display by removing @ prefix and properly handling null connection names.
**JAM MCP Integration**
Added JAM integration to the MCP marketplace, expanding available tools and services for enhanced development workflows.
**Bug fixes and improvements**
Various reliability, performance, and usability improvements across the app.
**Repository Counters Display**
The repositories page now shows total repository count and indexed repository count in the format 'X/Y repos indexed' for better visibility into indexing status.
**Enhanced MCP Marketplace**
Fixed text overflow issues in MCP marketplace cards so long integration names now wrap properly instead of being truncated.
**Improved Integration for Slack**
Enhanced Slack thread functionality with better macro extraction and moved thread mode settings to the dedicated Slack panel for improved organization.
**Enterprise Logout Access**
Added logout button visibility for enterprise sub-organizations in the sidebar, improving navigation consistency across different organization types.
**Enhanced Enterprise Consumption Dashboard**
Added sorting functionality to the User Metrics table in the enterprise consumption dashboard, allowing administrators to sort by session count and ACU consumption.
**Text Wrapping Improvements**
Fixed text wrapping issues in ADA search and DeepWiki to ensure long content displays properly without overflow.
**Bug fixes and improvements**
Various reliability, performance, and usability improvements across the app.
**VPC Repo Indexing**
For Enterprise customers using a VPC installation, added support for indexing repositories inside of the VPC which enhances security.
**GPT-5 Preview Access**
Core and Teams users now have access to a preview version of Devin that includes GPT-5, available through Agent Preview while we conduct further reliability and safety testing.
**Enhanced Enterprise Members Management**
The Enterprise Members page now displays organization groups and roles, giving administrators better visibility into member permissions and organizational structure.
**Jira Integration for Enterprises**
Jira integration is now available in enterprise connected accounts settings, enabling better project management workflows for enterprise customers.
**Perplexity MCP Server**
Added Perplexity to the MCP marketplace, expanding research and information gathering capabilities through the Model Context Protocol.
**Bug fixes and improvements**
Various reliability, performance, and usability improvements across the app.
**IdP Groups Settings Page**
View and search your identity provider groups directly in Settings > IdP Groups to quickly reference group names and membership context within Devin.
**Enterprise Members Overhaul**
A refreshed Enterprise Members page adds improved filters, enterprise-wide stats, and streamlined bulk actions; admins can also add groups from this page where enabled.
**Enterprise API Key Governance**
Manage enterprise API keys with a new governance experience, including provisioning and revoking service keys for tighter control.
**Diff File Header Copy**
Session diff file headers now include a one-click copy button and tooltip with the full path, making it faster to share or navigate to files.
**Linear Org Auto-Switch**
When opening a Devin scope link from a Linear ticket, Devin automatically switches to the ticket’s organization to ensure correct context.
**Bug fixes and improvements**
Various reliability, performance, and usability improvements across the app.
**Organization Selector Improvements**
Fixed overflow issues in the organization selector dropdown for better navigation when managing multiple organizations.
**Linear Integration Enhancements**
Improved Linear settings page to hide unnecessary configuration options for non-enterprise users, providing a cleaner interface.
**Enhanced Sleep State Messaging**
Improved messaging when Devin goes to sleep, providing clearer status updates even when Devin is already in sleep mode.
**Linear Knowledge Management**
Enhanced Linear knowledge editing capabilities, allowing all users to modify organization-specific Linear knowledge for better ticket scoping.
**Performance Optimizations**
Various backend improvements including better database query optimization and enhanced retry mechanisms for repository information retrieval.
**Organization Switcher Search**
Superusers can now search organizations directly from the switcher, and the menu is wider for faster navigation across large org lists.
**Primary Org Session Sidebar**
While working inside a session, the primary organization sidebar now remains visible to speed up navigation and access to settings.
**Linear Mapping UX Improvements**
The Linear integration modal has clearer toggles and button layouts, warns before closing with unsaved mappings, and uses the updated integrations webhook path for a more reliable setup.
**Automatic Linear Notes**
Saving Linear project mappings now generates structured Linear notes to help Devin scope issues and plan work more effectively.
**Input Dropdown Cleanup**
We removed the Deep Agent option from the input box dropdown to simplify task kickoff choices.
**PR Merge Notifications**
You’ll receive notifications when PRs are merged so session status stays up to date without manual refresh.
**Knowledge Title Editing**
You can now edit knowledge entry titles while in edit mode for cleaner organization.
**Dictionary Secrets No Longer Supported**
Dictionary-type secrets are no longer supported; use individual string secrets per key instead.
**Bug fixes and polish**
Various minor UI polish and non-user-facing improvements.
**MCP (Model Context Protocol) Marketplace**
Access 1000s of tools and integrations from a dedicated marketplace at `/settings/mcp-marketplace`. Connect to services like Linear, Notion, AWS services, and many more with a single click.
**Inline Secrets Management for MCP Configurations**
Create and reference secrets directly when configuring MCP servers. Simply define secrets inline and reference them using `$SECRETNAME` syntax for secure credential management.
**Slack Thread Mode Preference**
Control how Devin responds in Slack conversations. Choose whether Devin should reply in threads to keep conversations organized when integrated with your Slack workspace.
**Session UI**
We updated the Session UI to streamline the interface and better highlight key decision points in each session: the Task, the Plan, the PR, and the Summary. You’ll still have full access to Devin’s session progress, now presented more clearly and intuitively.
**Enterprise Connected Accounts UI**
We’ve redesigned the Enterprise Connected Accounts UI to make it cleaner and more focused. Connecting accounts is now simpler, with less clutter and clearer navigation.
**Git Permissions UI**
For Enterprise users, Git Permissions has been moved out of the Connected Accounts section and into its own dedicated tab. This makes it much easier to view repo permissions on a per-org basis and assign or remove repos and groups with better clarity.
**Devin can now open PRs using your GitHub username.**
This feature is off by default. To turn it on, select "Open PRs as Devin" on the [Integrations page](https://app.devin.ai/settings/integrations). This setting applies to all org members and can be changed by the admin.
**Session Insights**
Session Insights is a new free feature that analyzes your Devin sessions and breaks down what happened and gives you actionable tips for next time. It also generates a new, improved prompt that you can use to kick off a new session.
To use Session Insights, click the "View Session Insights" button in the top bar of your completed Devin session (located next to the lightbulb icon), then click **Generate Analysis** to trigger the analysis. You can also trigger analysis programmatically via the [API](/api-reference/v3/sessions/post-organizations-session-insights-generate).
**DeepWiki MCP Server:**
* We've launched the [DeepWiki MCP server](/work-with-devin/deepwiki-mcp), providing programmatic access to DeepWiki's repository documentation and search capabilities.
* Connect your AI applications to DeepWiki using the Model Context Protocol (MCP) standard.
* Free, no authentication required.
**Devin 2.1**: Confidence Scores 🟢 🟡 🔴 and enhanced codebase intelligence
It's true: coding agents can be overconfident. That's why Devin 2.1 now provides **Confidence Scores** to indicate its likelihood of completing tasks. Answer Devin's questions to help it reach 🟢.
* At multiple points in each session, Devin will express its confidence:
* At the start of the session
* After creating a plan
* Whenever it answers a question about the code
* When Devin doesn't have 🟢 confidence (i.e., 🟡 or 🔴), it will now wait for user approval before proceeding with its plan. If it's 🟢, it proceeds automatically.
* You can still send feedback and adjust Devin's plan even after it has started working.
* Our data shows that Confidence Scores are highly correlated with success.
**Upgrades to Linear & Jira Integrations:**
* Easily get Confidence Scores for multiple issues at once directly through our [Linear integration](/integrations/linear) and [Jira integration](/integrations/jira).
* This occurs without starting actual Devin sessions, allowing you to score as many issues as you'd like and prioritize having Devin work on the highest-confidence tasks.
**Enhanced Codebase Intelligence (DeepWiki Built-in):**
* The codebase understanding and intelligence features from DeepWiki are now directly integrated into Devin.
* At any point during a session, ask a question, and Devin will provide a DeepWiki-like answer, complete with code citations.
* Devin auto-detects when it should scan your codebase, but you can also trigger this manually using `!ask`.
We shipped [Deep Wiki](http://www.deepwiki.com): Up-to-date documentation you can talk to.
Turn on Deep Research for agent-powered, in-depth answers.
Share wikis and answers to keep everyone on the same page.
[Watch the walkthrough](https://x.com/cognition_labs/status/1915816544480989288) and check it for your favorite open source repos out at [www.deepwiki.com](http://www.deepwiki.com)! It's free for open-source repos, with 30k+ repos already available!
We now support **Jira**, in addition to Linear! The best workflow:
* Add the "Devin" label to a Jira issue, or bulk add to multiple issues to begin issue scoping in parallel.
* Devin knows your codebase and will comment on each ticket in minutes with a summary of relevant code, implementation plan and open questions.
* Use Devin's analysis to get up to speed. Devin has the self-awareness to report 🔴/🟠/🟢 confidence estimates too.
We also shipped **Devin Spaces**, an interactive playground to refine your tasks before having Devin work on them (in early preview):
* Devin will now link to Devin Spaces in its comment on Jira and Linear - use Spaces to ask follow up questions and further plan out the task.
* Start a Devin session directly from the plan you create in Devin Spaces!
To get started, check out our [Jira documentation](/integrations/jira) or [Linear documentation](/integrations/linear). We're excited to hear your feedback!
Our native **Linear integration** is now available! Turn tickets into PRs by launching Devins directly from Linear.
Our Devin x Linear workflow 👇
* Use Cmd+A to multi-select Linear tickets. Then, add the Devin label to start ticket scoping in parallel.
* Devin knows your codebase and will comment on each ticket in minutes with:
* A summary of the current code
* An implementation plan
* Any edge cases or questions that need your attention
* Use Devin's analysis to get up to speed, or just click the provided link to have Devin take a first pass at the PR. Devin has the self-awareness to report 🔴/🟠/🟢 confidence estimates too.
To start assigning tickets, go to [Devin's integrations](https://app.devin.ai/settings/integrations) and connect to Linear.
**Introducing Devin 2.0:** an agent-native IDE experience. Generally available today starting at \$20.
Check out our [launch announcement on X](https://x.com/cognition_labs/status/1907836719061451067) to learn more!
**Devin 1.5 is live!** We've shipped an end-to-end revamp of the Devin experience that makes it much easier to collaborate with Devin.
### Devin IDE
**Devin now does its work in an interactive VSCode environment loaded with your repos.** Check in on Devin's edits in real time, then touch up the changes or test Devin's code directly using the IDE tools and shortcuts you're familiar with.
* Click "Review Changes" for a diff view of file edits so far. You're in a fully featured IDE, so you can open files in new tabs, jump to definition, etc.
* Devin may send citations or references to code. Clicking on these will deep link into VSCode!
* Click "Follow Devin" to follow Devin's edits in real time. Click stop to take over and use the IDE yourself.
* Use `⌘K` to generate terminal commands from natural language.
* Use `⌘I` for rapid responses to questions or rapid file edits.
* All of Devin's terminals, commands, and their outputs are available in VSCode. Toggle from **read-only to writable** to run your own commands.
* Test and fix changes end to end without leaving the Devin webapp. Ask Devin to run your app locally, or take over and run commands yourself. Then use Devin's browser to test the local build yourself!
### Interactive Planner
Each time you kick off a new session, **Devin responds in seconds with relevant files, findings, and an initial plan**. Scope out your changes and give feedback on Devin's plan before letting Devin work autonomously.
* Devin rapidly scans relevant files and code snippets to generate an initial plan. This initial plan and subsequent messages may now cite code snippets and files, and **clicking on these citations now deep links into the Devin IDE!**
* For more complex tasks, click "Wait for my approval" so that Devin waits for your feedback on its full plan. Brainstorm and explore the codebase together in VSCode to refine the plan.
* By default, if you don't click "Wait for my approval", Devin waits 30 seconds for your input before proceeding. You can always change the default behavior in [Settings > Customization.](https://app.devin.ai/customization)
### Ask Devin
[Ask Devin](https://app.devin.ai/search) is a **new tool built to rapidly answer questions about your codebase**. Use Ask Devin for one-off questions like "Figure out where the auth backend endpoint is defined" or "Find the commit that introduced the new support functionality," or use it to map out the initial spec for a task you want Devin to execute.
* 🔎 **Ask Devin -> Devin:** Ask Devin to make code changes after using Ask Devin to find the relevant code. Use **Cmd + Enter** to quickly construct a high quality Devin prompt using your search context.
* 🔬 **Deep Mode:** Toggle on deep mode for complex questions that require extended research.
* 📓 **DeepWiki** is used by Ask Devin to better understand your codebase, and may help you as well! It contains architecture diagrams, links to sources, and more. Check it out [at the bottom of your sidebar.](https://app.devin.ai/wiki)
* 💬 **Ask follow up questions** - you can scroll up/down or use the component on the right (appears on hover) to navigate your history
* 🔗 **Share your Ask Devin results:** Try sharing a link to your search results when discussing code with your co-workers
* 💡 Tip: For now, we recommend setting up a [Site Search Shortcut in Chrome](https://support.google.com/chrome/answer/95426?hl=en\&co=GENIE.Platform%3DDesktop) so you can more quickly start Ask Devin queries from your browser address bar. Just go to chrome://settings/searchEngines and add a site search with url [http://app.devin.ai/search?prompt=%s](http://app.devin.ai/search?prompt=%s)
* Connect **multiple GitHub orgs** to the same Devin account - you can easily set this up in [Settings > Organization Integrations](https://app.devin.ai/settings/integrations). Let us know if you'd like this enabled for your team.
* Manage all of Devin's tasks in the new [Session Manager](https://app.devin.ai/sessions). Easily filter for sessions by PR status, users, playbooks and export session data.
* Tag sessions with **custom tags** that you can filter by in the Session Manager. Click on the 3 dots icon of the session page to "Edit Tags".
* Customize when Devin auto-closes PRs due to inactivity under [Settings > Customizations](https://app.devin.ai/customization).
* Easily tag `@file_name` to reference files in Devin's input box so Devin can quickly find the right place in your codebase to review and/or edit. Note that this only works for files in repos that have been set up in Devin's Workspace.
* **Speed**: Devin is \~2x faster vs in October 2024 and takes \~7.8 minutes on average to complete junior developer tasks in our internal evaluations.
* **Copy/paste in Devin's browser**: You can now copy text from your browser and paste it into Devin's browser! This was a highly requested feature that removes a major friction with providing Devin access to accounts (you no longer need to type in your passwords)!
* **Helping users with their prompts**: Devin proactively gives you feedback on suboptimal prompts & proposes breaking tasks down when they're too complex.
* **Gitlab (beta)**: Connect both Gitlab and GitHub repos to Devin! Devin can now push, pull, and view/create Gitlab MRs. Contact us via [app.devin.ai/settings/support](https://app.devin.ai/settings/support) to set this up.
* **Batch edits**: Tell Devin to "find and edit" code to encourage Devin to "fan out" and edit an arbitrary number of files in parallel. This greatly improves speed, especially for repetitive refactors.
* **Multi-action**: Devin can choose to perform any set of diverse batch of actions optimistically (e.g. viewing the browser, while running a shell command, while reading 10 code files), improving speed.
* **Browser improvements**: We've shipped browser changes that allow Devin to:
* deal with auto-opening tabs (required for some complex auth flows)
* use multiple tabs (helpful for iteratively comparing 2+ webpages)
* **Local UI Testing**: Devin can better test + visually understand UI changes locally.
* **Customize chat vs workspace width**: Drag to make the chat as narrow or wide as you'd like! The editor in the workspace is also easier to navigate now, with file tree on the left.
* **Repo setup (in [Devin's Workspace](https://app.devin.ai/workspace))**: We verify that all the commands you provide Devin (to run lint, install dependencies, and run tests) run successfully, and Devin will surface in chat if any of these commands don't succeed.
* **Sonnet 3.7 in Devin**: We incorporated Sonnet 3.7 in Devin on 2/24, with optimizations to our use rolling out starting 2/26. In our testing, the new model is the best we have seen to-date on a variety of tasks including debugging, codebase search, and agentic planning.
* **Keyboard shortcuts**: Use **→ ←** or **↑ ↓** anywhere on the session page to step through Devin's workspace progress over time.
* **Devin PR Metrics**: [app.devin.ai/metrics](https://app.devin.ai/metrics) now shows all PRs opened by Devin, even when 2+ PRs were opened in the same session.
* **Faster startup**: Devin only installs dependencies for the repositories needed in a session.
* **Addressing your PR review feedback**: Devin is more reliable at remembering to address *all the review comments you left on its PR.*
* **Misc brain improvements**: Devin is less likely to loop while trying to fix CI/lint failures, is better at planning, is better with git, and many more improvements!
**Devin's thoughts and editor diagnostics are now visible**: In the Follow Devin tab, you'll now see:
* each action Devin took (e.g. "Edited github.py")
* Devin's thoughts explaining *why* the action was taken (e.g. "There was a type error….the fix involves XYZ")
* any editor diagnostics errors present after the action was taken (in red)
This information helps you debug why Devin is stuck or taking a long time. Use it to learn how to best work with Devin, and as you're getting started to make sure issues aren't caused by the way [Devin's Workspace (i.e. machine snapshot)](/onboard-devin/environment) was set up.
**The new Detailed View**:
There's a new "Detailed View" button in the top right corner of the session page!
Use up/down arrow keys to quickly navigate through Devin's actions. Actions are grouped under the plan step (e.g. 009 investigate\_existing\_pattern) they aim to achieve.
Devin's thoughts, action details, and editor diagnostics are shown on the right.
Use this view to dive even deeper into debugging why Devin is stuck or taking a long time.
**Prompt improvement button + customer education via docs.devin.ai**:
Improvements to your instructions to Devin and/or use cases can greatly improve your success with Devin.
Try our in-product "instruction improvement" button immediately improve your instructions to Devin, and receive personalize suggestions on how your instructions could be improved:
We've also revamped our docs at [our documentation](/) to include example good/bad instruction examples, recommended ways of working with Devin, and other Essential Guidelines!
**Improved support for non-English speakers**: Devin is now more reliable with using the user's preferred language.
We also added a translate feature which shows up when non-English languages are detected. We currently support Japanese, Chinese, Korean, Russian, Arabic, and Thai.
**Improved Repo Context**: We've made major improvements to Devin's ability to reason in context in a repository
Devin is now more likely to find all relevant files to edit, will notice and re-use existing code and patterns, and will make more accurate PRs overall. These changes will be gradually rolled out to all users by 1/17/25.
**Introducing Devin enterprise accounts**:
Enterprise accounts enable centralized management of multiple Devin organizations. Admins of enterprise accounts can:
* Manage members and access controls for all organizations
* Centrally manage billing across all organizations
Enterprise accounts are currently available to Devin Enterprise customers.
**Introducing usage based billing**:
Starting January 9, you can now pay-as-you-go to keep building without limits, up to the pay-as-you-go usage limit you set.
Your subscription includes a monthly ACU capacity. Once these ACUs are used, you can pay-as-you-go. You will be billed at the end of your billing cycle or whenever your usage exceeds \$2,000 — whichever comes first.
Set your pay-as-you-go usage limit in Settings > Plans > Manage Pay-as-You-Go Usage Limit or Settings > Usage & Limits > Manage Pay-as-You-Go Usage Limit.
**Solution for Docker storage & performance issues**:
If you use Docker, there's now a solution for storage and performance issues with Docker on Devin's machine. A new version of our VM infra is now enabled by default for new teams. Existing teams can enable it:
* Navigate to Settings > Devin's Workspace > Danger Zone
* Switch to `Large Performant (Beta)` - this will require resetting your machine setup. If you want to opt in to experimental auto-migration, reach out to [support@cognition.ai](mailto:support@cognition.ai) or via [Slack Connect](https://app.devin.ai/settings/support)
**Devin usage best practices**:
We've added nudges throughout our product towards some best practices, including:
* Keeping sessions under 10 ACUs (Devin's performance degrades in long sessions)
* Providing details in your very first instruction to Devin, including (1) specific requirements (2) high level description of the task (3) what Devin should do after making the requested changes - e.g. testing instructions, PR guidelines, or tell Devin to wait for CI to pass without testing locally
* If you find yourself often re-using instructions, add them to Devin's knowledge in Settings > Devin's Settings > Knowledge
**Use Devin's Browser when setting up Devin's workspace (i.e. machine snapshot)**:
It's now easier to get Devin started with testing websites that require login. If you log in for Devin during onboarding with Devin's browser, we'll save the cookie for future sessions (if the cookie expires, you'll need to provide credentials for Devin in Secrets as well).
This also unblocks authentication processes that require visiting a URL on Devin's machine.
**Talk to Devin in Slack - Devin can now respond to audio messages**:
Try verbally explaining your tasks and feedback for Devin! You can now send Devin audio clips via Slack.
# 2026
Source: https://docs.devinenterprise.com/release-notes/2026
Devin release notes for 2026: new features, improvements, and bug fixes across the product, organized by release date.
**Devin Coach Suggestions in the Input Box**
Introducing Devin Coach, a new feature that surfaces suggestions directly in the session input box as you write, helping you improve prompts before sending.
**Smarter Re-Review Behavior in Devin Review**
Devin Review now skips re-reviewing a PR when its diff against the base branch is unchanged (e.g. stacked PR restacks).
**Slack Thread Follow-Ups**
Devin sessions now subscribe to Slack threads they post in and route replies back to the session, so follow-ups in the thread reach Devin without re-tagging.
**Teams Polish**
Microsoft Teams user mentions now render as mention chips, emoji render inline, and channel-mention threading behavior now matches Slack.
**High Contrast Mode: System Option**
High contrast mode adds a "system" option that follows your OS preference, alongside broader accessibility improvements including a new accessibility submenu in the command palette.
**Sidebar Improvements**
The sidebar now reveals the active session when navigating via the command palette or a URL, newly created folders appear at the top of the list, and right-clicking a folder opens its options menu.
**Command Palette Improvements**
"Start session with a prompt" now supports multiline prompt editing, and "Search sessions" is pinned under Start session.
**Preview Toolbar Improvements**
Open-in-new-tab is now promoted to the preview toolbar, exposed ports moved into an overflow menu, and share/open-in-new-tab now follow the page currently being viewed.
**Platform Filter for Sessions**
The sessions list can now be filtered by platform.
**Ingest Scan Mode in Code Scan**
Ingest is now available as a scan mode directly in the new-scan sheet.
**Auto-Scan Schedules API**
Code scan auto-scan schedule routes are now generally available in the v3 org and enterprise APIs.
**Devin Local On by Default for Enterprise**
Devin Local is now enabled by default for enterprise customers.
**In-Page Search in Automations**
Automations pages now support in-page search via Cmd/Ctrl+F.
**Unified Workflow Permission Preview**
In Automations, the workflow permission preview pane now matches the live run pane.
**Side Chats**
Start a side conversation anchored to any point in a session to ask questions and dig into details without interrupting Devin's main work. Side chats open in a panel next to the worklog and support stopping in-flight responses.
**Syntax-Highlighted Code Blocks in Chat**
Fenced code blocks in chat messages now render with syntax highlighting.
**Command Palette Session Search Pagination**
Session search in the command palette is now paginated with an explicit "See more" option.
**Sidebar Organization Improvements**
The sessions sidebar now supports a "None" option in the Group by menu for a flat session list, a "New session in folder" action on folder menus, and a Cmd+K "Move to folder" command for the current session.
**Slack Improvements**
Users can now request channel access directly from Slack DMs, Slack-spawned sessions automatically get read access to their origin channel, and Devin posts a notice when a session is waiting for machine capacity. Workspace members beyond the first page no longer show as "Unknown User".
**Slack Connection Management**
The Slack integration settings now include a Reconnect option, with integration Manage menus aligned on a consistent Reconnect/Disconnect component.
**Playbook Mentions from Slack**
Playbooks mentioned in messages are now resolved when forwarding user messages from Slack.
**Agent Mode Selector Improvements in Automations**
The agent mode selector in Automations and On-Call now shows the resolved organization default (e.g. "Org default (Fusion)") and a description for each mode.
**Negated String Operators in Automation Conditions**
Automation conditions now support "not contains", "not starts with", and "not ends with" operators.
**Security Profile Safeguards in the Automation Editor**
The automation editor now warns when selected MCP servers or network-policy entries fall outside the governing security profile, and confirms security profile changes with a warning popup.
**Perplexity MCP in the Marketplace**
Perplexity is now available as an MCP server in the connectors marketplace.
**Queueing Support for Automations**
Automations now support queueing: set the maximum number of concurrent runs and queue depth per automation, see queue lifecycle states in the events table, and view an activity chart sourced from automation events. Concurrency groups are also available in the public v3 API.
**Automations API and Terraform Provider**
The automations API has been promoted from beta to the production v3 API spec, sessions can now be filtered by `automation_id`, and a `devin_automation` resource is available in the Devin Terraform provider.
**GitLab Support in Automations**
Automations now support GitLab triggers (issues, issue notes, pushes, and pipelines) with reply support on issue triggers, plus support for a GitLab service-account connection to automatically manage webhooks.
**Request Channel Access from Slack**
When Devin can't access a Slack channel, users now see a specific reason and can request access directly from Slack, with admin approval.
**Command Palette Improvements**
The command palette now surfaces session search results in top-level search, keeps rows on a single line, and nests navigation commands under a "Go to" command.
**Figma Live Embeds in Link Previews**
Figma links shared in chat can now render as live embeds in link preview cards.
**Accessibility Improvements**
A broad accessibility (WCAG 2.1 AA) pass across the webapp: proper labels and accessible names on controls, keyboard-accessible sortable tables and toggles, skip links, distinct navigation landmarks, document titles, and assertive error toast announcements.
**Security Profiles**
Security profiles are now generally available. Admins can define security profiles governing network access and apply them across sessions and automations, including an org-wide default and per-automation profile selection.
**Legacy Cascade Disabled by Default for Enterprises**
Legacy Cascade now defaults to disabled for enterprise tiers, with clarified settings copy.
**Personal Access Tokens**
Personal access tokens are now generally available for authenticating with Devin programmatically. Tokens are automatically revoked when a user loses account membership.
**MCP Connection Improvements**
MCP sessions resume automatically after completing OAuth, personal MCP connections are account-wide with OAuth scoped to the installation's organization, and marketplace MCP installs support custom server URLs.
**Easier Recovery from Failed Snapshot Builds**
Failed environment snapshot builds are now easier to find and fix in fewer clicks.
**Linear Reconnect Action**
The Linear connection manage menu now includes a Reconnect action.
**Redesigned Changes Tab**
The Changes tab now has a persistent file tree sidebar with a tree or flat list toggle, and full-width diffs with language icons.
**Session Sidebar Improvements**
A new "Empty folder" action archives all sessions in a sidebar folder, session menus are reorganized into submenus, and archived sessions have clearer indicators.
**Session Renames in the Timeline**
When a session is renamed, the change now appears in the session timeline.
**Approval Progress at a Glance**
The pull request merge status bar now shows approval progress as a count of received versus required approvals.
**Slack Access Defaults**
Devin's Slack channel access is now configurable for all accounts, including a default of all public channels plus direct messages and an account-level setting for DM access.
**MCP Execution from Devin's Servers**
MCP tools now run from Devin's servers rather than the session's remote machine.
**Connectors Page Improvements**
Plugin-provided MCP servers are grouped into their own section, organization marketplace installs are always organization-scoped, and MCP installations without a configured auth method can fall back to dynamic OAuth.
**Control Where Legacy Cascade Is Available**
The enterprise Cascade setting is now a scope choice — enabled everywhere, JetBrains plugin only, or disabled — so admins can move users to Devin Local while keeping Cascade in the JetBrains plugin.
**Opt-In Public GitHub Repo Support in Automations**
Admins can now opt a public GitHub repo into automation triggers.
**Primary Billing Organization Attribution**
All users will be automatically assigned a primary billing org that all Devin Desktop and CLI usage is attributed to.
**IP Allowlists Cover Automation Webhooks**
Account IP allowlists are now enforced on automation webhooks, with support for additive webhook-only ranges.
**Bug Fixes**
This release also includes many smaller fixes and improvements, including Slack and Teams thread cards rendering markdown, queued messages showing slash commands as command chips, quote captions preserved as drafts, smoother streaming in very long sessions, and various UI polish across the webapp.
**Word-Level Diff Highlights**
Unified diff views now highlight exactly which words changed within a line, making edits easier to scan.
**Link Preview Cards in Chat**
Links shared in your messages and in Devin's replies now render as rich preview cards.
**Remix Keeps the Playbook**
Remixing a session now carries the original session's playbook and rich message content into the new prompt.
**Expandable Knowledge Previews**
Knowledge cards now include an expand toggle so you can read the full note content in place.
**Session Organization Improvements**
You can now remove archived sessions from sidebar folders, and opening an information tab reveals the workspace, including on mobile.
**Slack DMs with Automation Devins**
Automations can now work over Slack direct messages, with a setting to control whether DMs are enabled.
**Simpler Automation Channel Access**
Configuring which Slack channels an automation can access is now a simple two-mode choice.
**Playbooks Scoped to the Right Organization**
Playbook references in Jira and Linear mappings and automation triggers are now validated against the correct organization, with clear removal notices when a mismatch is found.
**SCIM Provisioning Is Generally Available**
SCIM user and group provisioning is now generally available for enterprises, enabling automated user lifecycle management from your identity provider.
**Audit Logging for Devin Local Settings**
Changes to Devin Local settings are now recorded in the enterprise audit log.
**IdP Group Improvements**
The enterprise IdP groups tab now shows member counts, and the group popover is easier to read with middle-truncated names and a copy button.
**Bug Fixes**
This release also includes many smaller fixes and improvements, including clearer Slack channel mapping copy, smoother scrolling in long sessions, fixed lightbox arrow-key navigation, more reliable copying from the shell tab, and various UI polish across the webapp.
**Redesigned Model Picker**
The model picker has been redesigned into a single organized menu where you can choose a capability, toggle Fusion, adjust speed, and switch modes.
**Slash Commands in the Message Box**
Typing commands like /btw and /queue in the message box is now more discoverable, including a new /ask command that switches the session to Ask mode.
**Playbook Previews in the Message Box**
Hovering over a playbook macro in your message now shows a preview of its contents, with a button to copy the full text.
**Start Windows Sessions from Slack**
A new !windows command lets you start a session on a Windows machine directly from Slack.
**Approve Network Access Requests from Slack**
When Devin requests access to a blocked network destination, you can now approve or deny the request directly from Slack.
**Clickable Finding Counts in Devin Review**
Finding counts on PR cards are now clickable and take you straight to the relevant findings in the embedded review view.
**Required Approvals at a Glance**
Devin Review now shows how many approving reviews a pull request requires.
**Redesigned New-Scan Flow**
Starting a code scan now uses a streamlined flow with support for single-repository, multi-repository, and bulk scans.
**OIDC Identity Tokens**
Devin can now authenticate to cloud services using short-lived OIDC identity tokens.
**API Additions**
The API now supports unarchiving sessions and creating ingestion-mode code scans at the organization and enterprise level.
**Bug Fixes**
This release also includes many smaller fixes and improvements, including faster DeepWiki MCP question answering, links shared from Slack rendering correctly in chat, a clearer Approve button for environment changes, the session "Code files" tab renamed to "Editor", easier text quoting, and various UI polish across the webapp.
**Smarter Linear Thread Handling**
Replies in different Linear comment threads are now routed to the correct Devin session, and follow-up work on the same issue continues in the original session for better continuity.
**Automations Consumption Visibility**
A new Consumption tab on each automation shows the ACUs used by sessions the automation has started, so you can track the cost of your automated workflows.
**Slack Channel Improvements for Automations**
When configuring an automation's monitored channels, Devin can now automatically join public channels you select, and you can grant access to all public channels at once.
**Safer MCP Access Changes**
Switching an MCP server from personal to Organization access now shows a warning step explaining that your connection will be shared with other members before you confirm.
**Review Usage in Consumption Analytics**
Consumption analytics now shows what triggered each Devin Review run, making it easier to attribute review usage.
**Improved Quoted Attachments**
Quoting text from files or previous messages has a refreshed look, and clicking a quote reopens it on the original surface with the relevant lines highlighted.
**Performance Improvements**
The webapp loads faster and stays responsive in long sessions, including faster boot, smoother work logs, and better handling of large diffs.
**Devin Outposts**
This release introduces Devin Outposts, a new capability for running Devin workloads in your own environment. It is disabled by default — contact your Cognition representative if you are interested in enabling it.
**Quicker Access to Enterprise Settings**
Enterprise admins can now jump to enterprise settings pages, including from a child organization, using the cmd+K command palette.
**Code Scan Profile Filters**
The scan profiles tab now supports filtering profiles by type and mode.
**Snapshot Build History Filters**
Snapshot build history can now be filtered by build status and platform.
**API Additions**
Enterprise member API responses now include each member's enterprise join date, and organization consumption endpoints now report ACUs used by Devin Review.
**Bug Fixes**
This release also includes many smaller fixes and improvements, including icons on the enterprise MCP server list, the ability to switch an automation between session types after creation, clearer error messages, and various UI polish across the webapp.
**Centralized Skill Management via Plugins**
Skills can now be distributed via Plugins that can be installed and governed centrally, then applied consistently across Devin Cloud, Devin CLI, and Devin Desktop (via Devin Local).
**Enterprise-Grade Plugin Governance**
Admins can configure required, optional, and forbidden plugins in Settings → Marketplace, and organizations inherit enterprise-managed plugin policies automatically.
**Multi-Repository Code Scans**
Code scans can now span multiple repositories in a single scan, with per-repository details and a repository filter on findings.
**Chained Attack Paths in Findings**
Related findings are now linked together as chained attack paths, helping you understand how individual vulnerabilities combine into larger risks.
**Queued Messages Improvements**
You can now set a preference to automatically queue messages while Devin is working, send the next queued message by pressing Enter in an empty composer, and queued messages now default to sending immediately when Devin becomes available.
**Tasks Tab in the Workspace**
A new Tasks tab in the workspace tab picker shows Devin's latest task list so you can follow progress at a glance.
**Inline Link Previews**
Links shared in chat now render inline previews for markdown, PDF, HTML, and CSV content.
**Sortable Tables in Chat**
Tables in Devin's chat messages are now sortable by column.
**Custom Slack Emoji Rendering**
Your workspace's custom Slack emojis now render correctly in synced session message history.
**Instant Slack Unsync Command**
Sending "unsync" (or "!unsync") in a synced Slack thread now immediately stops syncing the conversation.
**Revamped Automations Pages**
The Automations pages have been redesigned with a streamlined editor, clearer trigger configuration, and a new option to create a long-running session that receives subsequent trigger events.
**GitHub Enterprise Server Support for Automations**
Automations can now target repositories hosted on GitHub Enterprise Server.
**Bug Fixes**
This release also includes improved bulk secret import with name validation, expanded keyboard shortcuts, better mobile layouts, a simplified Devin Desktop login button in settings, cleaner Slack send options in the composer, more reliable MCP tool listing for HTTP servers, and many performance improvements to session streaming and PR review loading.
**Quote Text in Your Messages**
You can now select text in a session — from files, the worklog, or Devin's messages — and quote it directly in your next message, making it easier to reference exactly what you're talking about.
**Filter Sessions by Skill**
The sessions list can now be filtered by which skill was activated during the session.
**Session Sizes Are Now ACU-Only**
Session t-shirt sizes (XS–XL) are now based solely on ACU consumption and no longer factor in the number of user messages sent.
**Promote Playbooks to Your Enterprise**
Admins can now promote a playbook from a single organization to the entire enterprise, making it available across all organizations.
**Interactive ACU Chart Legends**
Legend entries on the enterprise ACUs-by-product chart are now clickable, letting you toggle individual series on and off.
**Redesigned Account Switcher**
A redesigned account switcher makes it easier to move between your organizations, with a clearer two-pane layout for people who belong to an enterprise.
**Copy Commands from the Worklog**
Shell commands in the session worklog now have a copy button that copies the full command to your clipboard.
**Streamlined Copy Actions**
Copy actions in the command palette are now grouped together under a single "Copy…" menu.
**Lists That Load as You Scroll**
Long lists such as repository and snapshot pickers now load automatically as you scroll, instead of requiring a "Load more" button.
**Fullscreen Devin Desktop**
The Devin Desktop VNC viewer now supports native fullscreen.
**Clearer Bulk Secret Imports**
Importing multiple secrets at once now reports errors per line, so you can see exactly which entries need fixing.
**Bug Fixes**
This release also includes a working organization filter on the enterprise sessions view, self-serve removal of GitHub Enterprise Server app configurations, and various other UI improvements throughout the app.
**Redesigned Review Comment Composer**
The Devin Review comment composer now uses GitHub-style Cancel, Comment, and Start a review buttons, with Cmd+Enter to submit and Escape to dismiss. In the pull request view embedded in a session, a new Commits tab lets you browse the changes commit by commit.
**Apply Environment Config Suggestions from Slack**
When Devin suggests an environment configuration change in Slack, the message now includes a diff of the proposed change and an Apply button, so you can accept it without leaving Slack.
**Mobbin MCP Server**
The Mobbin MCP server is now available in the integrations marketplace.
**Reorganized Settings Navigation**
Skills & Rules and Plugins now live together under a new Resources section, the Plugins page has a wider and clearer layout, and your personal analytics have moved into your personal settings.
**Diff Line Permalinks**
You can now share direct links to specific lines in a Devin Review diff via the URL hash — useful for pointing teammates to exact code locations.
**Slack !agent Renamed to !normal**
The `!agent` Slack bang-command has been renamed to `!normal` for consistency with the standard Devin mode naming.
**Slack Sync Toast Improvements**
The Slack sync notification toast now has clearer copy, can be dismissed per-tab, and includes a "don't remind me" opt-out.
**Service User Automations**
Service users can now create and manage automations via the API, enabling programmatic automation workflows.
**Snapshot Build Trigger**
`snapshot_build:completed` is now available as an automation event trigger, letting you kick off workflows when a new environment snapshot finishes building.
**MCP Run-As-Creator Warning**
Automations now display a warning when a user-scoped MCP server is selected but run-as-creator is turned off, helping avoid permission mismatches at runtime.
**Code-Snippet Telemetry Audit Log**
Changes to code-snippet telemetry settings are now recorded in the customer-facing audit log.
**Security Scan Remediation API**
The v3 API now supports endpoints for remediating security scan findings.
**API Default Devin Version**
API-created sessions can now specify a default Devin version, giving teams programmatic control over which Devin version runs their workloads.
**Git-Backed Blueprints**
Blueprints can now be backed by a Git repository, letting you version-control and collaborate on environment configurations alongside your code.
**Blueprint Permission Descriptions**
Blueprint permission names and descriptions now clearly indicate their scope, making it easier to understand what each permission controls.
**Hover Copy for Tables**
Markdown tables in sessions now display a copy button on hover, letting you quickly copy table contents to your clipboard.
**Bug Fixes**
This release also includes fixes for virtualized Review comments hijacking scroll, diff-viewer partial-expand into file boundaries, collapsed worklog diff-stat clipping in WebKit, desktop VNC reconnection after session wake, terminal LF-to-CRLF conversion on non-PTY flush, PAT-authenticated webhook error comments now being allowed, and various other UI polish improvements throughout the app.
**No-Access Permission Popover**
When your connected account lacks write permission on a repository, Devin Review now shows a clear "no access" popover explaining what's needed instead of silently failing.
**Auto-Review Scoped to Your PRs**
The auto-review user preference now applies only to PRs you author, so enabling it won't trigger automatic reviews on other people's pull requests.
**PR-Link Preference**
Users can now control whether in-session PR links open in the Devin tab, in GitHub, or in Devin Review.
**Persist Model Selection**
Your chosen default model is now remembered when you select it in the agent picker, persisting across page reloads.
**Network Access Requests**
In network-restricted sessions, Devin can now request access to specific domains. The request surfaces to you for approval, removing the need to preconfigure every domain.
**GitLab Mention-Only Comments**
Devin now respects mention-only PR comment settings for GitLab merge requests, reducing notification noise for teams that prefer targeted mentions.
**Slack Thread Sync**
Sessions can now sync messages bidirectionally with Slack threads. A confirmation prompt appears for busy threads, and global sync is enabled by default for new sessions.
**Unarchive on Mention**
Mentioning @Devin in a Slack thread for an archived session now automatically unarchives it so you can continue the conversation.
**Slack Commands Anywhere**
Slack bang-command macros (like `!ultra` or `!fast`) are now recognized anywhere in your message, not just at the beginning.
**Inline Mute Reminder**
The mute/quiet-mode reminder now appears inline in the session footnote instead of as a separate message, reducing clutter.
**MCP Read-Only Mode**
The secure-mode profile UI now includes a toggle for restricting MCP servers to read-only access.
**Improved Webhook Trigger Setup**
The automation editor now shows the webhook URL and secret inline before you save, so you can configure the external service first.
**Usage Analytics: PR Ratio Chart**
A new weekly Devin PR ratio chart with repository filtering is available on the Repositories analytics tab, along with CSV export and improved number formatting across all analytics tables.
**Skills Analytics**
A new enterprise-level skills analytics page shows skill usage patterns, adoption rates, and performance across your organization.
**ACU Limit Audit Trail**
Organization ACU limit changes are now recorded in the customer-facing audit log, giving enterprise admins full visibility into limit adjustments.
**Read-Only Scan Profiles**
Enterprise-managed scan profiles now render as read-only in child organizations, preventing accidental modifications to centrally managed security policies.
**Analytics Page Improvements**
Analytics time-range and filter selections now persist in the URL for easy sharing, and the organization picker in productivity dashboards supports pagination for enterprises with many organizations.
**Redesigned Environment Page**
The environment page is redesigned with platform filters, an active snapshot grid layout, and platform-specific icons for better discoverability of your build configurations.
**Cross-Platform Repository Cloning**
Organizations can now clone configured repositories on every available build platform, not just the default — enabling consistent environments across Linux, macOS, and other platforms.
**Bug Fixes**
This release also includes numerous bug fixes across the platform — including fixes for the Slate editor crash on mobile, voice recording button visibility on narrow screens, Review header alignment, IDE frame layering over dialogs, MCP OAuth redirect handling, mentions preserving spaces correctly, false "Installation out of date" banners on fresh MCP installs, blueprint drawer state preservation, unsubscribe link routing for enterprise emails, and various UI polish improvements throughout the app.
**Archive/Unarchive Sessions from Command Palette**
Sessions can now be archived or unarchived directly from the Cmd+K command palette on session pages, without navigating to session settings.
**Run-Once Automation Schedules**
Automations now support a run-once schedule option for one-time executions, in addition to recurring schedules.
**MCP "Installation Out of Date" Banner**
Installed MCP integrations now surface an "Installation out of date" banner with one-click marketplace refresh when an update is available.
**Post-Build Section for Blueprints**
The blueprint editor now includes a Post Build guide item for organization and enterprise blueprints.
**Readable PR Review Label Colors**
PR Review labels now render with readable text in both light and dark themes.
**Usage Analytics Improvements**
The Consumption Dashboard now uses bar charts for the session activity chart, combines active and review users into a single chart with a metric selector, adds a counts/percentages toggle, and normalizes the per-tab export buttons to a consistent "Export" control.
**Pin/Unpin Sessions from Command Palette**
Sessions can now be pinned or unpinned directly from the Cmd+K command palette for faster access to important sessions.
**Start Session in Background**
A new "Start session in background" button on the home page lets you kick off a session without navigating away from your current view.
**View Latest Version for File Tabs**
File tabs in sessions now include a "View latest version" affordance, making it easy to jump to the most recent version of a file Devin has edited.
**Security Findings in Ask Devin**
When using Ask Devin within PR Review, the AI context now includes security findings, enabling more security-aware assistance during code review conversations.
**"Repo Rule" Badge on Lifeguard Findings**
Lifeguard bugs that were flagged from repository rule files now display a "Repo rule" badge, helping reviewers distinguish rule-sourced findings from general analysis.
**Split View Auto-Disable on Narrow Panels**
The Split view option in PR Review is now automatically disabled when the panel is too narrow to display it usefully, preventing layout issues on smaller screens.
**Usage Analytics — Top 10 Rankings**
Consumption analytics now includes Top 10 ranking charts for repositories (in Reviews usage) and for users and service users (in the Consumption tab), giving admins quick visibility into where usage is concentrated.
**Enterprise Wide Snapshot Build Schedule**
Enterprises can now configure a snapshot build schedule, controlling when environment builds run. Blueprint settings also display drift warnings when the environment is out of sync, with actionable buttons to trigger a re-sync.
**Add Enterprise Members When SSO Is Required**
Org admins can now add existing enterprise members to their organization even when SSO is required for enterprise membership.
**ACU Billing Schedule Warning**
Enterprises consuming ACUs without an active billing schedule now see a warning, helping admins avoid unexpected usage without payment coverage.
**MCP Marketplace Expansion**
48+ new engineering MCP connectors are now available, including Miro, Mixpanel, Honeycomb, Postman, monday.com, Klaviyo, and many more. 42 previously-beta MCPs have graduated to general availability. New additions include LaunchDarkly (with hosted OAuth), Fathom, Attio, and Calendly. Google Drive MCP is now available to all users.
**Dedicated MCP Management Page**
Enterprise admins now have a dedicated MCP management page with per-server detail views showing organization-wide and per-session usage, replacing the previous side panel.
**GitLab User Identity Linking**
Link your personal GitLab account so Devin creates Merge Requests under your GitLab user instead of the Devin identity. For enterprises with self-hosted GitLab instances, admins can register a GitLab OAuth Application under Advanced settings to enable user linking for self-hosted instances.
**Devin Review for GitLab**
Devin Review now supports GitLab Merge Requests. Intelligent diffs, inline comments, and AI chat all work on GitLab MRs. Your GitLab MRs appear in the sidebar organized by status (Needs your review, Returned to you, Approved, Waiting for reviewers, Drafts). GitLab repos can be added to auto-review in Review settings.
**File Path Visible During Streaming Edits**
The full file path is now shown while the edit tool is actively streaming changes, so you always know which file Devin is modifying.
**Deduplicated File Tabs with Version Switcher**
When multiple versions of the same file exist, they are consolidated into a single tab with a version dropdown instead of cluttering the tab bar.
**Slack Formatting in Webapp Comments**
Bold, links, code, and other Slack formatting now renders correctly in webapp thread comments forwarded from Slack.
**PR Context Visible While Waiting for CI**
PR-ready context is now shown while CI checks are still running, so you can start reviewing before checks complete.
**Improved Feedback Controls**
Both thumbs-up and thumbs-down buttons are now always visible on messages. Session-level feedback and a qualitative feedback modal make it easier to share detailed feedback.
**Incremental Generation Steps in Automation Input**
The AI-assisted automation input now shows incremental generating steps as it builds your automation configuration.
**Public Repos Shown as Disabled in Repo Picker**
Public repositories now appear greyed out in the repo picker instead of being hidden, making it clear they exist but are not selectable.
**"User Only" PR Author Enforcement**
A new "User only" option is available in the "Open PRs as" setting. When selected, Devin will only create PRs under the user's identity and will fail if their Git account is not connected. Automations and service users fall back to the Devin identity. Enterprise admins can enforce this setting across all organizations.
**Cmd+K: Switch Organization & Copy Org ID**
The command palette (Cmd+K / Ctrl+K) now supports switching between organizations and copying your org ID without navigating to settings.
**Sidebar: Unpin & Remove-from-Folder Quick Actions**
The sidebar archive button has been replaced with context-aware quick actions: pinned sessions show an "Unpin" button, and sessions in a folder show "Remove from folder." Archive remains accessible via the context menu.
**Wiki: Clean Page URLs**
Wiki pages now use cleaner `/page/` routes instead of the previous longer format, making links easier to share and bookmark.
**Automations Sidebar**
Automations now appear in the main navigation sidebar for quicker access to your configured automation rules.
**Japanese Translations: 100% Coverage**
All remaining Japanese translation keys have been filled across the platform, bringing Japanese language coverage to 100%.
**Ask Devin: @repos Picker Scoped to Search Repos**
The @repos file picker in Ask Devin now only shows repositories from your selected search scope, reducing noise when referencing files.
**Suggested Knowledge Visible in Session Worklog**
When Devin suggests a knowledge item during a session, it now appears as a standalone event in the worklog for easier visibility and review.
**Devin Review: Comment Language Selector**
When reviewing PRs in Devin Review, you can now select the language for AI-generated review comments (e.g., English, Japanese, Spanish).
**Devin Review: Security Findings**
All Devin reviews now include a security findings section. The security reviewer respects your repository's SECURITY.md file to tailor its analysis to your project's security policies.
**Devin Review: Code Owner Review Block**
The merge bar now shows when a PR is blocked waiting for code owner approval, making it clear which reviews are still required before merging.
**Devin Review: GitHub Alert Callouts**
GitHub-style alert callouts (note, warning, caution, etc.) in markdown files now render with proper styling in Devin Review.
**Slack: Preceding Thread Messages as Context**
When Devin is mentioned in a Slack thread, it now receives the preceding thread messages as context, enabling more informed responses without needing to repeat background information.
**Slack: !agent Bang Command**
Use `!agent` in Slack messages to Devin to explicitly route your request to a full Agent session instead of Ask mode.
**Default Sync with Slack Per Session**
New sessions can now default to syncing messages with Slack, configurable at the organization level so teams stay in the loop automatically.
**Automations: Slack Channel Updates**
Automation run results can now be posted to a designated Slack channel, keeping your team informed of automated session outcomes.
**Linear: Projects Filter for Triggers**
When configuring Linear-triggered automations, you can now filter by Linear project to scope which issues trigger Devin sessions.
**MCP Server: View Logs on Error**
MCP plugin error cards now include a "View logs" button linking directly to the MCP output channel, plus detailed error information surfaced in the plugin status card for faster debugging.
**Axiom MCP Server**
A new official Axiom MCP integration is available, allowing Devin to query your Axiom logs and observability data during sessions.
**Structured Output Schema for Playbooks**
Playbooks now support a structured output schema, enabling Devin to return results in a defined JSON format for easier programmatic consumption.
**Enterprise Knowledge Limit Increased to 300**
The maximum number of enterprise knowledge items has been increased from 200 to 300.
**Session Folders**
Group sessions into named folders in the sidebar. Move sessions via drag-and-drop or the three-dot menu. Folders are personal, so each user defines their own layout.
**!ultra and !fast Mid-Session Toggles**
You can now start sessions on Devin Ultra directly from Slack with the `!ultra` command. You can also switch between Ultra and Fast modes mid-session by typing `!ultra` or `!fast` in the Slack thread.
**Smarter Emoji Reactions**
Devin now only adds sleep/archive emoji reactions to messages that are explicit sleep or archive commands, reducing noise on other status messages.
**Custom OAuth for Marketplace MCP Servers**
Marketplace MCP servers that require organization-specific OAuth client credentials can now be configured directly from the integrations page.
**Markdown File Preview in Worklog**
Markdown files created during a session now render with a preview toggle, letting you see the formatted output alongside the raw content.
**Web Search Enterprise Setting**
Enterprise admins can now enable or disable Devin's web search capability via a new toggle in enterprise settings.
**"Users" Tab Renamed to "Members"**
The org membership page tab now reads "Members" for clarity.
**Devin Review: Pending PR Reviews Canceled on New Commits**
When new commits are pushed to a PR, any in-progress Devin reviews are now automatically canceled. The PR Review API also reflects this with a new `cancelled` status on review objects.
**Large Pastes Automatically Attached as Files**
Pasting large content (10k+ characters) into the composer now automatically attaches it as a file, regardless of existing message length. This keeps your prompt clean and avoids hitting size limits.
**User Mentions Rendered as Styled Links**
@mentions in session messages are now displayed as styled deeplinks instead of the raw "@Name (ID)" format.
**"Sent from Slack/Teams/Linear" Indicator**
Follow-up messages that originated from an integration now show a small badge indicating their source (e.g., "Sent from Slack").
**Echo Message to Slack Toggle**
A new toggle lets you bypass Slack message suppression and echo your webapp messages into the Slack thread, even in quiet-mode sessions.
**Improved Slack Message Rendering**
HTML entities in Slack messages are now properly decoded outside of code blocks, fixing garbled characters in forwarded content.
**Official Figma MCP Integration**
The official Figma MCP server is now available with suggestions enabled. The previous unofficial integration has been deactivated.
**IdP Group Role as First Assignment**
Org-scoped IdP groups can now use a group role as their very first role assignment, removing the previous requirement to set an individual role first.
**Success Confirmation After Org Creation**
Creating a new organization within an enterprise now shows a clear success state, confirming the operation completed.
**Start a New Session with This Prompt**
The first message in a session now shows a "Start a new session with this prompt" button, replacing the previous "Start duplicate session" menu action. Reuse any prompt for a fresh session in one click.
**Playbook Devin Mode**
Playbooks can now specify a Devin mode (e.g., Fast or Normal). When launching a session from a playbook, the agent picker reflects the playbook's configured mode.
**Configurable Auto-Reload Threshold**
You can now customize the balance threshold that triggers auto-reload in the billing usage modal.
**Jira Webhook Failure Recovery**
When a Jira webhook connection fails, a banner now appears in your Jira integration settings with a one-click reconnect action to restore the connection.
**Devin Review: Action-Required Flags on PRs by Default**
Devin Review now posts orange action-required flags to your GitHub pull requests by default when issues are found that need investigation.
**Webhook URL in Automation Editor**
The automation editor now displays the webhook URL directly under the webhook trigger, so you can copy it without navigating away.
**Improved Slack Message Formatting**
Devin's messages in Slack now use full markdown formatting for all users, providing richer text rendering with proper links, code blocks, and lists.
**Send Messages While Session Is Queued**
You can now send messages to a session that is waiting for capacity. Your messages will be delivered as soon as the session starts.
**Persist Chat Draft Across Panel Close**
Draft messages in the session composer are now preserved when the panel is closed and reopened, so you won't lose work in progress.
**Session Counts on Collapsed Sidebar**
Session counts are now visible on collapsed sidebar section headers, giving you a quick overview without expanding each section.
**Devin Review: Connect Personal Account from Blocked Controls**
In Devin Review, when Review, Merge, or comment actions are blocked because your personal identity isn't linked, you can now connect your GitHub or GitLab account directly from the blocked control without navigating to settings.
**Active Todo in Slack Plan Header**
The collapsed plan header in Slack threads now shows the currently active todo item, so you can see what Devin is working on at a glance.
**Detect @Devin Mentions After Inviting the Bot**
When you tag @Devin in a channel where the bot isn't present and then invite it, Devin now detects and responds to your original mention.
**Lower Minimum Per-Session Limit for Automations**
The minimum per-session limit for automations has been lowered from 3 to 1, giving you finer-grained control over automation budgets.
**Scratchpad Moved Under MCPs in Automations**
The scratchpad section in the automation editor has been moved to the top level under MCPs for easier discoverability.
**Prompt to Reconnect Linear**
When creating a Linear automation with an expired personal token, you'll now be prompted to reconnect before proceeding.
**Personal Automations**
You can now create personal automations that run under your own identity. Personal automations include a dedicated toggle, permission model, and badge in automation lists. The legacy Schedules page now shows migration guidance to help you transition to the new Automations system.
**Devin Review: Enrolled Users, Spend Limits, and GHES/GitLab Support**
Devin Review now includes an enrolled users management table in settings, a redesigned per-PR spend limit that acts as a soft block (you can re-enable if needed), and pinned section titles above file headers in the embedded review view. "Open in Devin Review" is now available for GitHub Enterprise Server and GitLab PRs.
**Pre-Approve Testing**
A new user preference lets you always approve testing for future sessions, so Devin can test changes without prompting each time. Access it from your profile settings or via the split-button on the "Test the app" action.
**V3 API: Organization Members and Automations**
New org-scoped `GET /v3beta1/organizations/{org_id}/members` endpoint for listing organization members. A full automations CRUD API is also now available via v3.
**SSO/SCIM: JIT Provisioning and Enterprise Redirect**
SSO just-in-time provisioning can now be toggled on or off, with group sync gated separately. SSO-only enterprise users are now automatically redirected to their enterprise webapp host on login.
**Settings Improvements**
The Repositories page now supports pagination. Search results in the settings sidebar are deduplicated with indent guides. A permission-gated "Add repositories" button and empty state have been added to Skills & Rules. Terminology has been updated from "org" to "organization" throughout.
**Child Sessions: Tree Connector**
Child sessions now display with a tree connector in the sidebar, making parent-child relationships visually clear.
**Bug Fixes**
Persisted orange sidebar indicator for quota-suspended sessions. Made question answer submission optimistic, removing click lag. Fixed send button centering at fractional zoom levels. Added email fallback for IdP users without a name in the session list. Fixed cross-org router links dropping query string and hash. Added cost column to scheduled sessions past sessions list. Cleared "Approve session" attention dot once the session is read. Restored question selections when an optimistic submit fails. Pinned bulk-edit bar to viewport bottom centered over content column. Included enterprise members in the session creator filter.
**New Command Palette**
The redesigned command palette is now available with improved search, keyboard navigation, and settings integration. Access it with Cmd+K (Mac) or Ctrl+K (Windows/Linux) to quickly navigate pages, settings, and actions.
**Automations: Files-Changed Trigger**
The automation builder now supports file-change triggers for GitHub push events. You can configure automations to run only when specific files or directories are modified in a push. Pull request triggers also automatically add the appropriate action filter.
**PR Review Sidebar Restructure**
The in-session PR review sidebar has been redesigned with collapsible sections, portalized toolbar actions, and a new diff settings menu replacing the previous split/unified toggle.
**Raindrop.ai MCP in Marketplace**
The Raindrop.ai MCP server is now available in the MCP marketplace.
**Disable Review/Analysis for Merged and Closed PRs**
The review and analysis trigger is now disabled for already-merged and closed pull requests, preventing unnecessary processing.
**Wake Sleeping Sessions on Retrigger**
Sleeping sessions now automatically wake up when a PR comment retrigger is posted, so you no longer need to manually restart them.
**Devin Review: Respect CI Monitoring Setting**
Devin Review now correctly honors the "Disable automatic comment and CI monitoring" checkbox for merge-conflict notifications.
**Bug Fixes**
Fixed intermittent Recent repos display issue. Fixed diff view flashing two-column layout before snapping to unified view. Added DeepWiki button to repo indexing header. Fixed infinite page spinner when a user is not a member of the resolved organization.
**Platform Default Settings**
Org admins can now set a default platform (Linux or Windows) for all new sessions, and individual users can star their personal preference. The default platform is honored across all session creation methods, including Slack, Linear, Jira, API, and automations.
**Slack Channel Override**
Type `!channel #channel-name` in Slack to override which channel Devin spawns its response thread in for that session.
**MCP OAuth Resource Parameter**
MCP OAuth flows now forward the RFC 8707 resource parameter, fixing authentication for MCP servers that require resource indicators (such as Snowflake and Runlayer).
**Custom RRULE Schedule Input**
Automation schedules now support pasting raw RFC 5545 recurrence rule strings directly, with validation and auto-detection, for schedules that go beyond the visual editor.
**GitLab Interactive PR Review**
GitLab repositories now support interactive PR review — Devin can post review comments and resolve threads as you — when the read-write GitLab connection is enabled.
**PR Review Status API**
A new `GET /v3/enterprise/pr-reviews` endpoint lets you poll Devin Review status programmatically, with optional commit SHA filtering.
**In-App Support Dialog**
"Contact support" now opens an in-app dialog where you can submit a ticket directly, replacing the previous email link.
**Inline Repo Permission Toggle**
You can now toggle repository permissions between "Read only" and "Read & write" directly from the permissions table, without needing to remove and re-add the repository.
**Enterprise Max Concurrent Snapshot Builds**
Enterprise admins can now set a maximum concurrent snapshot builds limit in enterprise settings, with backend enforcement to prevent build queue overload.
**GitLab OAuth Scope and Token Refresh**
GitLab user OAuth now requests the broader `api` scope for better compatibility, and tokens are automatically refreshed before they expire.
**Network Config Editor Redesign**
The network policy editor has been redesigned as an inline-editable list with multi-line paste support and duplicate detection, fixing the issue where domains typed but not submitted were silently lost on save.
**GitHub Connection No Longer Required for Automations**
GitHub-triggered automations no longer require a personal GitHub connection, allowing teams to rely on the org-level connection exclusively.
**PostHog MCP**
The PostHog MCP server is now available in the MCP marketplace, enabling product analytics integration directly from Devin sessions.
**Other Improvements**
Automation sessions now appear in a dedicated "Automations involving you" sidebar folder instead of being auto-pinned. Session @-mentions in chat are clickable links. A new Cmd+K action copies the session URL to clipboard. Archive undo now restores cascade-archived child sessions. MCP connection errors are surfaced instead of silently swallowed, and a new disconnect action removes stored OAuth tokens. Integration mappings for Linear, Slack, Teams, and Jira are validated at save time. The repo selector shows a Recent section and org labels. Tool calls in Watch Devin Work display timing. Automation-spawned sessions can be renamed by any org member. Integration page actions are permission-gated. File URLs in the timeline link to the correct git provider. GHES installations resolve bot identity per-config and scope webhook processing to the owning account.
**Collapsible Session Folders**
Sessions in the left sidebar can now be organized into collapsible folders. Click the chevron to expand or collapse a folder, and your preference is persisted per organization.
**Archive All Sessions**
A new "Archive all" option in the sidebar menu lets you archive all sessions or asks at once, with a confirmation dialog and undo support. Child sessions skip the confirmation step for faster cleanup.
**Sub-Devin Session Filter**
The sessions page now includes a "Sub-Devin" filter that lets you view child sessions independently, with support for combined parent and child filtering.
**Default Member Roles**
Enterprise admins can now configure default roles that are automatically assigned to new organization members on join, with badge display in the members list and safeguards against accidental deletion of roles in use.
**GHES App Registration Restriction**
GitHub Enterprise Server app registration is now restricted to one app per account and host combination, preventing duplicate registrations with a clear error message when a conflict is detected.
**Copyable Organization ID**
Your Organization ID is now displayed with a one-click copy button on both the Settings → General and Settings → Devin API pages, making it easy to share with support or use in API calls.
**Admin-Enforced Settings Lock Icon**
Settings that have been locked by an admin now display a lock icon with an explanatory tooltip, replacing the previous banner-style callout for a cleaner interface.
**MCP OAuth Client Credentials**
When installing MCP integrations that don't support Dynamic Client Registration (such as Salesforce), you can now supply your own OAuth client credentials directly in the configuration flow.
**Tavily MCP in Marketplace**
Tavily web search is now available in the MCP marketplace, providing AI-optimized real-time web search and content extraction capabilities for your Devin sessions.
**PR Actions & Auto-Review Settings**
The PR actions menu in Devin Review has been restored with an auto-review toggle and personal settings popover, giving you quick access to review preferences without leaving the review interface.
**Checks Tab Always Visible**
The Checks tab is now always visible in the embedded PR review experience, and the merge-status popover properly restores the checks UI so you can always see CI status at a glance.
**Improved @-Mention Search**
The @-mention search in the chat input now uses fuzzy bag-of-words matching, so queries like "setup-dev" will find "setup-devin-dev". Repositories are also ranked first in the dropdown for faster access.
**Slack Improvements**
This release includes several Slack integration improvements: channel names now resolve correctly even for channels you haven't joined, mentions display as styled blue pill badges, unmapped channel messaging is clearer, the Watch channel option appears at the top of the trigger submenu, stale channel lists are fixed, and duplicate webapp-to-Slack thread posts are suppressed.
**Slack Security Hardening**
Enterprise channel isolation for Slack thread-attach has been hardened with runtime authorization that validates channels against enterprise channel preferences, preventing cross-organization channel access.
**Video Recording Download**
You can now download session recording videos directly from the video player controls.
**Miscellaneous Improvements**
This release also includes: file re-upload fix, archived chip now clickable for non-owners with unarchive permission, network config available for finished sessions, test recording viewer close button visibility fix, settings search improvements, back buttons on MCP marketplace and knowledge detail pages, deep mode callout hidden when disabled, repo name truncation so filter stays visible, mobile agent selection single-tap fix, Devin Review file scroll and merge status fixes, skills link fix, Slack support channel in help popover, and wait tool rendered as standalone worklog event.
**Snapshot Build Delete**
You can now delete snapshot builds directly from the build history menu or detail page, with a confirmation dialog to prevent accidental removal. This makes it easier to clean up old or failed builds without navigating away from your environment settings.
**MCP Multiline Environment Variables**
When configuring MCP server connections in the marketplace, you can now enter multiline values for environment variables — such as PEM private keys, JSON service account credentials, and Snowflake key passphrases — without needing to escape or flatten them first.
**Sub-Devin Sidebar Improvements**
Sub-Devin sessions spawned by automations can now be pinned and reordered independently in the sidebar, and they appear expanded by default so you can see their status at a glance without clicking to expand.
**Voice Recording While Devin Is Working**
The microphone button now appears alongside the stop button while Devin is actively working, allowing you to record and send voice follow-ups without waiting for Devin to finish its current task.
**Settings Redesign**
Settings pages have been redesigned with a hub-style layout, improved search across all settings, and a streamlined navigation structure. An announcement dialog introduces the new experience on first visit, and legacy settings URLs automatically redirect to their new locations.
**Archive Active Session Warning**
When you archive a session that is still actively working, a warning dialog now informs you that archiving will put both the session and any child sessions to sleep before proceeding.
**Share Session on Mobile**
A new "Share session" action is available in the sidebar session menu on mobile devices, making it easy to share session links directly from your phone.
**Devin Review Mobile Improvements**
On mobile, tapping "Ask Devin" on a comment now opens the chat panel directly, pull-to-refresh is available on the review scroll container, and bug/flag tap targets have been fixed so they open on the first tap and reveal the associated comment.
**V3 API Enhancements**
The V3 API now supports filtering sessions by repository name via the `repo_names` parameter, filtering by archive status via `is_archived`, specifying `devin_mode` when creating sessions, and setting `folder_id` and `is_enabled` when creating or updating knowledge notes.
**Enterprise Member Invite Acknowledgement**
When inviting new members to an enterprise organization from the admin panel, an acknowledgement modal now confirms the invitation details before it is sent.
**Rename Context to Skills & Rules**
The "Context" section in settings has been renamed to "Skills & Rules" to better describe its purpose of managing Devin's skill definitions and behavioral rules for your organization.
**Blueprint Migration Improvements**
The blueprint migration page now displays per-repo session counts, supports filtering by repository, and shows a completed state when all migrations are finished, making it easier to track progress across large organizations.
**Miscellaneous Improvements**
This release also includes: autofocus on confirmation buttons in archive dialogs, plan artifact button polish, configurable CI status in search results, debounced enterprise snapshot builds, server-side event deduplication to prevent duplicate delivery, pinned sessions remaining visible when automations are hidden in the sidebar, removal of the misleading "Action required" label for Python sessions awaiting instructions, schedule list cap raised from 50 to 200, monitor trigger cleanup when adding new Slack triggers, repo setup status fix for Dynamic Repo Setup organizations, "Approve session" visibility in the sidebar even after all PRs are merged, inline image deduplication by URL, streaming scroll stability fix, high-resolution home screen icon for Android, beta Vite mode build fix, fast mode loading indicator reset on session switch, and sidebar hover cards on expanded non-active sections.
**Devin Review API**
You can now trigger Devin Review programmatically via the REST API. Use `POST /v3/organizations/{org_id}/pr-reviews` with a service user token or PAT to initiate reviews from CI pipelines, scripts, or custom integrations.
**Mermaid Diagram Rendering**
Mermaid code blocks in session messages now render as interactive SVG diagrams with zoom and pan controls, making it easier to explore flowcharts, sequence diagrams, and architecture diagrams that Devin produces.
**Close PRs on Session Archive**
When archiving a Devin session, a dialog now appears where you can optionally close any linked GitHub pull requests, keeping your repository tidy without manual cleanup.
**Per-PR Auto-Review Toggle**
You can now enable or disable automatic Devin Review on a per-PR basis from the PR actions menu, giving you granular control over which pull requests receive automated review without changing your organization-wide settings.
**Sidebar Session Notifications**
The session sidebar now shows persistent status labels, such as "PR created," "Awaiting instructions," or "Approve session," alongside timestamps so you can quickly see what each session needs. Sessions also display read/unread indicators: an orange dot marks sessions with unread updates, and the dot clears once you open the session.
**Service User Permission Management**
Enterprise administrators can now assign the `ManageAccountServiceUsers` permission in custom roles, providing granular control over who can create and manage service users and API keys within the organization.
**Ask Devin in PR Discussions**
The "Ask Devin" button is now available on discussion tab thread comments in Devin Review, making it easy to ask follow-up questions or request changes directly within review conversation threads.
**MCP Secret Scoping**
When adding secrets for custom MCP server connections, you can now choose between personal scope, visible only to you, or organization scope, shared with your team, via a new scope selector in the creation dialog.
**Clickable Diff Stats in Worklog**
Clicking the +N/-M diff stats in worklog group headers now opens a scoped diff tab showing only the file changes from that specific group, making it faster to review exactly what changed at each step.
**Repo Selector Fix**
The select-all checkbox in the repository selector now correctly toggles only the repositories matching your current search filter, rather than selecting all repositories regardless of the filter.
**Slack Tool Use in Worklog**
When Devin interacts with Slack during a session (sending messages, adding reactions, reading channels), these actions now appear in the worklog and progress UI with a dedicated Slack icon and action details.
**Settings Search Improvements**
Settings pages now use a centralized item registry with keyword-driven search, delivering more accurate and comprehensive results when searching across all settings pages.
**Command Palette Search**
Fixed search ordering in the command palette so results rank correctly, and resolved a scroll view issue in the search results window.
**Review Commit Links**
Fixed commit links in Devin Review to point to the correct URL path, and improved status indicators for review progress.
**Default Branch Detection**
Fixed an issue where repository indexing could use the wrong branch as the primary branch instead of the actual GitHub or GitLab default branch, which could affect DeepWiki and search results.
**Stacked Review Permissions**
Enterprise admins can now assign tiered PR Review access levels to their organization members: manual-only review, automatic review on PR creation, or automatic review on every push. This gives administrators granular control over how and when Devin Review engages with pull requests across their organization.
**Skill Slash Commands**
You can now invoke skills by typing `/name` in the prompt input, in addition to the existing @mention syntax. Skills are grouped by repository in the dropdown for easier discovery.
**Auto-Attach Large Paste**
Pasting a large block of text into the prompt input now automatically attaches it as a file instead of filling the text box, preserving any message you've already typed.
**Jira Project Mapping Redesign**
The Jira project mapping modal has been redesigned with a fixed header and scrollable content area, making it easier to configure mappings for organizations with many Jira projects.
**Auto-Fix Includes CI Checks**
The "Auto-fix with Devin" button on pull requests now includes failing CI check names in the prompt alongside review findings, giving Devin more context to resolve issues in a single pass.
**Linear Team Mapping Improvements**
The default organization is now optional when configuring enterprise Linear team mappings, and unmapped teams can be explicitly cleared to "None" instead of requiring a catch-all mapping.
**Session Origin in API**
The v3 API session response now includes an `origin` field indicating how the session was created (webapp, Slack, API, or CLI), making it easier for API consumers to categorize and filter sessions programmatically.
**Deleted Orgs in Enterprise Sessions API**
Enterprise session endpoints now support an `include_deleted_orgs` parameter, giving enterprise admins visibility into sessions from organizations that have been removed.
**Snapshot Revert for Declarative Setup**
Users with the ManageOrgSnapshots permission can now revert an organization from declarative environment configuration back to classic configuration, without needing the broader ManageOrgSettings permission.
**Revamped Blueprint Authoring Experience**
The blueprint editor has been redesigned with a shared layout, per-section play buttons, and a bottom terminal drawer. You can now deep-link directly into a repo's blueprint editor, making it faster to author and test environment setups.
**Enterprise Commit Email Lock**
Enterprise admins can now require all member commits to use the user's primary email. The lock is enforced across snapshot setup, session creation, and PR digest commits, helping enterprises keep commit attribution consistent for audit and compliance.
**PR Auto-Close Removed**
Devin sessions no longer automatically close their pull requests when the session ends. Open PRs now stay open by default so you can manage their lifecycle yourself, with no surprise closures.
**Hybrid Comment Mode in Devin Review**
When Devin Review is opened alongside a Devin session, review comments now default to hybrid mode — anchored to specific lines where possible and falling back to file-level comments otherwise — instead of forcing one or the other.
**Auth-Type Badges in Git Connections**
The git connection filter dropdown on the repository permissions page now shows a PAT, App, or OAuth badge next to each connection, making it easier to disambiguate connections that share a name.
**Slack Trigger Message in Sessions List**
Sessions started from Slack now display the user's triggering Slack message in the sessions list instead of the system prompt, making it easier to identify Slack-launched sessions at a glance.
**PR Digest List Redesign**
The PR digest list has been redesigned with a cleaner layout that matches the sessions list view, making it easier to scan and navigate through pull requests.
**Double-Click File Attachment Picker**
Double-click the plus button in the prompt input to directly open the file attachment picker, skipping the intermediate menu.
**Sensitive Toggle for Secrets**
When Devin requests a secret, you can now toggle whether the value should be masked (sensitive) or visible, instead of it always defaulting to masked.
**Merged Multi-Edits in Progress Tab**
Consecutive file edits to the same file are now merged into a single entry in the progress tab, showing a combined diff from the original to the final version instead of individual per-edit diffs.
**Session Category and Subcategory in API**
The v3 API session response now includes category and subcategory fields. A new category filter is available on session list endpoints, and session exports also include these fields.
**Wide Markdown Tables in Chat**
Markdown tables in Devin's chat messages can now extend beyond the chat column width, preventing cramped multi-column tables from being unreadable.
**SSO Connection Picker**
Organizations with multiple SSO connections for the same email domain now see a picker on the login page instead of being auto-redirected to the first match, letting users choose the correct identity provider.
**MCP OAuth Token Expiry Warnings**
Invalid or expired MCP OAuth tokens are now flagged with warning banners in the integrations UI. A reconnect button lets you re-authorize without navigating away from the page.
**Repository Permissions Decoupled from Git Integrations**
Repository permissions are now managed separately from git integration settings with a view/manage split, giving admins finer-grained control over who can modify repository access versus who can manage the underlying git connection.
**View Consumption Permission**
A new ViewAccountConsumption permission separates read access to usage and consumption data from billing write access, allowing admins to grant visibility without full billing control.
**Attachments in Question Answers**
File attachments are now included when you answer Devin's prompts. Previously, attached files were silently dropped.
**MCP Auth Status Feedback**
MCP authentication requests now show success or error status in both the webapp and Slack after completion, so you know immediately whether authorization succeeded.
**Merge Time Reduction in Review**
The Devin Review page now displays the merge time reduction percentage, showing how much faster PRs are merged with Devin Review enabled.
**PR Digest for Disconnected Users**
The Review page now shows a read-only digest of PRs from your Devin sessions — including open, draft, merged, and closed PRs — even if you haven't connected GitHub yet.
**GitHub Enterprise Server in Review**
GitHub Enterprise Server instances can now be selected in the Review page's Link GitHub flow, and GHES organizations appear in the Devin Review org selector.
**Review Permissions Enforcement**
Repository-level review permissions are now enforced, giving admins control over which repositories Devin Review can access.
**IDP Groups Management**
Enterprise settings now include a management UI for Identity Provider (Okta) groups, letting admins map groups to roles, view group members, and detect user conflicts with existing role assignments.
**Secure Mode Description**
The Secure mode description in enterprise settings has been rewritten to more clearly explain what Secure mode does and when to use it.
**WikiGenerationItem Card**
A new card is now displayed in sessions when the generate\_wiki MCP tool is invoked, giving better visibility into wiki generation progress.
**GHES Links in Integrations**
GitHub Enterprise Server user account links have been moved to the Integrations section of your profile for easier access.
**Minor Bug Fixes and Improvements**
This release also includes a range of smaller fixes and polish: sessions now indicate which are in an "Action Required" state, fixed the playback speed dropdown not opening on click, resolved invisible text in chat inputs on light backgrounds, fixed sidebar glyph flickering, corrected the Context Growth chart x-axis to use continuous datetime, removed checkboxes from combobox options, fixed seat type dropdown clipping, improved seat invitation copy for proper singular/plural phrasing, clarified the "available full seats" invite warning, updated flex seats to show as unlimited on the members page, and hid the Connect GitHub banner for GitLab MRs and during the Review intro overlay.
**Close PR or Convert to Draft in Review UI**
The PR review merge bar now includes options to close a PR or convert it to a draft directly from the review page.
**Inline Session Rename**
Sessions can now be renamed inline directly in the sidebar without opening a dialog.
**Smart Table Column Sizing**
Tables throughout the app now use content-aware column width sizing for better readability.
**Faster Sidebar Session Loading**
The sidebar now lists sessions faster and more reliably, with improved rendering performance and optimistic updates when creating new sessions.
**Datadog Remote MCP Server**
Datadog is now available in the MCP marketplace as a remote MCP server with OAuth-based authentication, so Devin can query your Datadog dashboards and metrics directly.
**ACP Summarizer**
Agent Client Protocol now supports a summarizer method for generating session summaries programmatically, useful for integrations that need a concise recap of what Devin accomplished.
**Granola MCP Server**
The Granola MCP server is now promoted out of beta, letting Devin access your Granola meeting notes during a session.
**Pagination and Search for Review Settings**
Enterprise review settings now support pagination and search for repository and user lists, making it easier to manage large configurations.
**Minor Bug Fixes and Improvements**
This release also includes a range of smaller fixes and polish, including a proper 404 error page for invalid URLs, frontend performance optimizations, and assorted stability improvements across the webapp.
**Theme Selector Generally Available**
The theme selector is now generally available, with system theme as the default so Devin automatically matches your OS light or dark mode.
**Wiki Effort Level Descriptions**
When choosing a DeepWiki effort level, each option now shows its expected ACU range so you can pick the right trade-off between cost and depth with confidence.
**DeepWiki Cost Breakdown Modal**
The DeepWiki cost breakdown modal is back, giving you an ACU-level view of where a wiki generation spent its budget.
**Cancel In-Progress Snapshot Builds**
You can now cancel an in-progress snapshot build directly from the snapshot list without waiting for it to finish or fail.
**Snapshot Blueprint Ordering**
Snapshot detail rails and repository-level blueprints now respect your configured blueprint ordering, so the list you see matches the order you set.
**Scheduled Session Failure Email Rate Limiting**
Failure email notifications for scheduled sessions are now rate limited, so a scheduled run hitting the same problem repeatedly will no longer flood your inbox.
**Knowledge Search Auto-Expand**
When you search your knowledge base, any folder containing a matching note now automatically expands so you can see the result in context without hunting for it.
**Profile Integrations Filter**
Your profile page now only shows integrations that are actually connected for your organization, cutting the clutter from services you do not use.
**Browser Tool Parity Improvements**
Devin's browser tool now handles native browser dialogs, intercepts file chooser prompts, respects navigation guards, and restores focus correctly, bringing its behavior much closer to a real user browsing the web.
**Amplitude MCP Server**
Amplitude is now available in the MCP marketplace, so Devin can pull product analytics directly into a session without a custom integration.
**One-Click MCP OAuth Install**
Installing an MCP server that uses OAuth now returns the authorization URL directly, skipping an extra click and getting you connected faster.
**Personal MCP Servers**
You can now connect personal MCP servers, which enable Devin to use MCPs with authorization provided by an individual user rather than shared across an organization.
**Richer ACP Methods and @-Mentions**
Agent Client Protocol now carries @-mentions as structured resource blocks and adds new methods for listing repositories, saving secrets, archiving sessions, approving deploys, and attaching to the interactive browser, giving ACP clients a much richer surface area to work with.
**Devin CLI Polish**
The Devin CLI now preserves streamed shell output alongside exit codes, supports a `/resume` alias, renders plan-mode exits more clearly, and uses focus pings to keep a session from sleeping while you are actively watching it.
**Reconnecting VNC Screen**
The interactive browser now shows a reconnecting screen while its VNC stream is recovering, so you get clear feedback instead of a frozen view when the connection briefly drops.
**Unlink GitHub Enterprise Server OAuth**
You can now unlink a GitHub Enterprise Server OAuth connection from your account, making it easy to rotate credentials or clean up stale integrations.
**Total ACUs Column in Usage Table**
The Users table in Usage analytics now includes a Total ACUs column, so enterprise admins can rank and compare per-user consumption at a glance.
**Bulk Repository Secrets Import**
Enterprise admins can now import multiple repository secrets at once through a new bulk import flow on the repository configuration page, replacing the old one-at-a-time workflow.
**Minor Bug Fixes and Improvements**
This release also includes a range of smaller fixes and polish across the webapp, including repository branch dropdowns that now size correctly, the DeepWiki section hidden when no branches are indexed, a fix for Linear OAuth cancellations returning errors, correct starting numbers on streamed ordered lists, a copy-message button that now copies only the selected message, and assorted other stability and layout improvements.
**Auto-merge from Devin Review**
You can now enable or disable GitHub auto-merge directly from the Devin Review merge button, so approved pull requests land as soon as checks pass without an extra trip to GitHub.
**Enterprise Review Consumption by Repository**
The Reviews tab on the Enterprise Consumption page now groups Devin Review spend by repository with current-cycle vs previous-cycle columns, a search box, and CSV export, making it much easier for enterprise admins to see where their review spend is going.
**Devin Review Breakdown in v3 Consumption API**
The v3 consumption API now reports Devin Review as its own line item in the product breakdown alongside sessions and indexing.
**Categorization and Subcategories**
Session categorization and subcategories are now generally available for every workspace, giving you a consistent way to organize and filter your Devin sessions.
**Pinned Organizations Sync Across Devices**
Your pinned organizations are now stored server-side and follow you across every device and browser you sign in from.
**Session Message Permalinks**
Every message in a session now has its own shareable link, so you can point teammates directly at the exact moment you want them to see.
**Larger Attachment Uploads**
Session attachments now support files up to 75 MB, up from the previous 20 MB limit.
**Higher-Quality Wiki v2**
Wiki v2 now uses stronger reasoning, subagents, and agentic page writers to produce noticeably better documentation, and shows the ACU cost of the last generation so you can see exactly what each refresh costs.
**Guardrails V3**
Our new pattern-based guardrail prompts significantly reduce false positives while keeping the same level of protection.
**Ask Sub-mode Renamed to Q\&A**
The Ask sub-mode is now simply labeled "Q\&A" to better reflect what it does.
**Consolidated Session Header Menu**
Session header links are now grouped into a single hyperlink menu for a cleaner, less crowded header.
**Faster Syntax Highlighting**
Code blocks across the app now render with an incremental, worker-based syntax highlighter for noticeably faster and smoother highlighting on large files.
**Scroll Restoration**
Navigating back through the app now restores your previous scroll position so you land where you left off.
**Japanese Localization Refresh**
Japanese localization strings have been refreshed across the webapp.
**MCP Marketplace Upgrades**
The MCP marketplace now includes a Recommended section, smarter Figma discovery, and a shared interactive OAuth flow that shows connection status and errors directly in chat as you install servers.
**MCP Audit Logs**
Enterprise audit logs now cover MCP server updates and secret link and unlink events for better visibility into integration changes.
**Session ACU Hard Caps**
Enterprises can now set a hard upper limit on total ACUs per session, with an acknowledgement modal and real-time validation so users always know when a session is approaching the cap.
**Cerebras Now Enterprise-Ready**
Cerebras is now available as an enterprise-ready inference provider for organizations that want to use it for their Devin workloads.
**US Privacy Controls**
Devin now honors Global Privacy Control signals and supports CCPA and CPRA opt-out requests for customers in the United States.
**Refreshed Settings Layout**
Insights, identity provider, and several other enterprise settings pages have been migrated to the new settings layout and design system for a more consistent look and faster navigation.
**Enterprise Secrets Table Polish**
The enterprise secrets table now includes an environment variable column and a build-only toggle, with a simplified layout that removes the Name column and type selector.
**Minor Bug Fixes and Improvements**
Numerous smaller fixes and polish, including sidebar collapse state persistence, sidebar pull requests loading without a GitHub connection, better multi-PR session isolation, deduplicated Slack file forwarding, quota reset on plan upgrade, billing cycle short-month correction, snapshots sorted alphabetically, an auto-organize tooltip explaining when it is disabled, and the Category beta label and Review beta badge retired for paying organizations.
**Classic Environment Setup Deprecation**
Classic environment setup is being deprecated on June 30, 2026, when all organizations move to declarative configuration (blueprints). Your classic machine configuration stays available as a read-only reference until July 31, 2026. See [Environment configuration](/onboard-devin/environment).
**Enterprise-Scoped Secrets**
Enterprise admins can manage secrets at the enterprise level, automatically shared across all organizations. Initially only available to users of declarative environment configuration.
**Enterprise ACU Visibility Control**
Enterprise admins can control whether users see ACU usage info.
**Enterprise MCP Registry Enforcement**
Enterprise admins can enforce an MCP server allowlist across their organization.
**Enterprise Build Pinning**
Enterprise admins can pin specific Devin builds and roll back to previous versions. Initially only available to users of declarative environment configuration.
**Devin Review Auto-Fix**
When Devin Review detects bugs in a PR, a new "Auto-fix with Devin" button launches a session to fix them in one click.
**PR Review Chat CI Tools**
Check CI status and view CI job logs directly within the PR review chat.
**Pin Sessions**
Pin important sessions from the three-dot menu for quick access.
**Organization Terminology**
All "team" references updated to "organization" across the product. No functional change.
**Improved Questions UI**
Navigation between questions, inline "Something else" input, cleaner design.
**Auto-Skip Pending Questions**
Devin auto-skips pending questions when you send a new message.
**Cleaner File Paths**
Relative paths with structured format instead of full absolute paths.
**PR Review Polish**
Sticky tabs, bug navigation, copy buttons, chat CTA at end of diffs, empty state for PRs without descriptions.
**Structured Output for Child Sessions**
Child sessions can return structured JSON via schema for automated workflows.
**Smarter Codebase Search**
Recency-based repository ordering for faster, more accurate results.
**/new Slash Command**
Alias for /clear to start a fresh conversation.
**Azure DevOps Service Principal**
Connect Azure DevOps via service principal instead of personal OAuth.
**Linear Assignee Filter**
Rich picker for Linear assignee filtering in automations.
**Linear Token Refresh**
Linear connections now auto-refresh OAuth tokens, preventing disconnection on expiry.
**Minor Bug Fixes and Improvements**
GitLab PAT rotation fix, responsive mobile layouts, startup command display improvements, build log scroll-to-bottom, Ctrl+O expand hint, shell security improvements, automations UI fixes.
**PR Resuming**
Devin can now take over and work on existing pull requests that weren't created in the current session, enabling continuation of work across sessions.
**Devin Review Improvements**
Added a "lines left to review" counter in the PR review diff viewer, and significantly faster page load times via parallel queries.
**Streaming Terminals**
Terminal output in the session view now streams in real time.
**Connected Accounts Pagination**
GitHub and GitLab connected accounts pages now support pagination and search for organizations with many connections.
**GHES Improvements**
Support for org-level GitHub App registration on GitHub Enterprise Server, with pre-filled app name in the manifest flow.
**Settings Page Redesign**
Multiple settings pages (Schedules, Playbooks, Knowledge, Secrets) have been redesigned with a new unified layout, along with consolidated dialog styles across the product.
**Sticky Sidebar Headers**
Sidebar section headers now stick to the top while scrolling for easier navigation.
**Light Mode Polish**
Multiple fixes for theme-aware colors across modals, dialogs, and components.
**Add or Create Team**
New button in the account dropdown to create a team without going through the GitHub integration flow.
**Auto-open Agents Tab**
The Agents tab auto-opens when child sessions are detected.
**Tab Title Simplification**
Browser tab title simplified to "Devin" with contextual page titles.
**Slack Thread Permissions**
Users without Devin accounts are now blocked from messaging in Devin Slack threads.
**Improved PR Comment Formatting**
Devin's PR comments now include line info and outside-diff context.
**IME Composition Fix**
Fixed an issue where pressing Enter during IME composition (e.g., Japanese input) in Safari would prematurely submit text.
**Ignore Comment Info**
More helpful information shown when Devin Review comments are ignored.
**Environment Setup Cleanup**
Clarified environment description copy and removed redundant buttons.
**Bash Syntax Highlighting**
Terminal output now has syntax highlighting for bash commands.
**Scheduled Session Pill**
Visual indicator for scheduled sessions in the sessions list.
**Minor bug fixes and improvements**
Various bug fixes, performance improvements, and visual polish across the platform.
**Preview Agent Toggle**
A new "Preview upcoming features" toggle is available in the agent selector, enabling streaming thoughts and faster execution. Stability may be limited as these features are still in development.
**Inline File Previews**
HTML, PDF, and SVG attachments can now be securely rendered inline in the session sidebar, with a code/render toggle and download button in the file toolbar.
**Focus Mode**
A new focus mode hides the sidebar, header, and right panel for a distraction-free chat experience. Access it from the session menu or with the keyboard shortcut Cmd+Shift+F.
**Agents Tab for Child Sessions**
A new "Agents" tab automatically appears when a session creates child sessions, showing their status, todos, and PRs in one place.
**Test Recording Viewer**
Devin's test recordings now display as rich cards with pass/fail summaries, playback speed controls, and loop functionality.
**Jira Integration Enhancements**
Jira now supports direct session creation from issues, service account connections, and per-project trigger options for controlling when Devin is activated.
**Redesigned Integration Settings**
The Linear, Jira, and Slack integration settings pages have been redesigned with cleaner layouts for team mapping, playbook management, bot allowlists, and automation rules.
**Minor bug fixes and improvements**
Various bug fixes and performance improvements across the platform.
**Light Mode (Beta)**
Devin now supports a light mode theme. You can switch between dark, light, and system themes from your profile settings.
**Streaming Shell Output in Worklog**
Background shell process output now streams inline within worklog items, so you can monitor long-running processes without switching to the terminal.
**Cookie JSON Builder for Secrets**
A new tabbed interface for cookie secrets lets users paste raw JSON (auto-encoded to base64) with validation, parsed previews, and expiration warnings.
**Org-Level Metrics API**
New organization-scoped API endpoints for metrics and consumption data.
**Session Insights UI Redesign**
The session insights modal has been redesigned with a refreshed layout, improved empty states, and updated copy.
**Secrets on Initial Prompt**
Users can now attach secrets when creating a new session from the home page, matching existing functionality for follow-up messages.
**Devin Reviews Analytics**
A new Devin Reviews section has been added to the usage analytics page showing review metrics.
**Minor bug fixes and improvements**
Various bug fixes and performance improvements across the platform.
**Devin Manages Devins**
Devin can now orchestrate Devins and manage your Devin setup directly from any session. This will replace the current Advanced Devin features.
Devin can delegate to a team of managed Devins that work in parallel. Each managed Devin is a full Devin with its own isolated virtual machine. The main Devin session acts as a coordinator — scoping the work, monitoring progress, resolving conflicts, and compiling the results.
New capabilities include:
* Session management – Create child sessions with structured output schemas and playbooks. Search and filter past sessions by tags, playbook, origin, or time range. Analyze past sessions with full search across shell, file, browser, git, and MCP activity.
* Knowledge management – Create, update, delete, and organize knowledge notes into folders. Review knowledge suggestions.
* Playbook management – Create, edit, and delete playbooks.
* Schedule management – Create and manage scheduled sessions including recurring or one-time runs, agent selection, and notification preferences.
**Redesigned Integration Pages**
The integration settings pages have been redesigned with a new layout including connection cards, support sections, and pagination.
**Improved Playbook Page**
The playbooks page now shows a table layout. Each playbook page now shows session count, unique users, and merged PRs per playbook, with a weekly activity chart. Playbooks now include a version history.
**Parent/Child Session Grouping**
Parent and child sessions are now grouped together in the sidebar, so child sessions stay nested under their parent regardless of sorting or filtering.
**Minor bug fixes and improvements**
Various bug fixes and performance improvements across the platform.
**On-Demand Session Insights**
Session insights are now generated on demand rather than automatically. You can trigger analysis from the Session Insights button in the UI or programmatically via the new [generate insights API endpoint](/api-reference/v3/sessions/post-organizations-session-insights-generate). Insights will continue to be automatically generated for L and XL sessions.
**New Session Inputs**
* An inline voice recording button is now available for hands-free messaging.
* Devin sessions can be @ mentioned to reference them directly in another session.
**Session List Improvements**
* Important sessions can be pinned to the top of the sidebar for quick access.
* A new sidebar filter hides scheduled sessions from the session list.
**Structured Output Modal**
The structured output from sessions created with the API with this parameter set can now be viewed and downloaded from the "Structured output" option in the session menu.
**Markdown Preview**
Markdown files can now be natively displayed in the right panel.
**Datadog MCP Integration**
Datadog is now available as an official integration in the MCP marketplace.
**Default Branch Management**
Users can set and manage the default branch for repository indexing from the repositories management page.
**Schedule: Run as User**
Schedules can now be reassigned to run as the current user via a "Run as me" button in the schedule detail view, also available via the v3 API.
**IdP Groups in Enterprise Settings**
The enterprise members table now shows IdP group memberships for each user.
**Minor bug fixes and improvements**
Various bug fixes, performance improvements, and visual polish across the platform.
**Install Devin as an App**
Devin can now be installed as a Progressive Web App on desktop and mobile. On Chrome or Edge, open app.devin.ai and click the install icon in the address bar (or Menu → Install Devin); on iOS Safari, tap Share → Add to Home Screen. Once installed, Devin links open directly in the app.
**Session Status in Browser Tab**
The browser tab favicon now shows a colored status dot on session pages (green when Devin is working, orange when it's waiting for you) so you can spot sessions that need attention without switching tabs.
**Minor bug fixes and improvements**
Various bug fixes, performance improvements, and visual polish across the platform.
**AskDevin Upgrade**
Expanded to support Ask and Plan modes. Now has more advanced code search capabilities which produce more detailed and accurate answers. The status of Devin sessions created from AskDevin can now be seen in the conversation.
**Devin Review: GitHub Commit Status Checks**
Status checks now displayed directly on pull request commits, giving visibility into review progress without leaving GitHub. The status links to the full Devin Review analysis.
To enable this, the Devin GitHub App will request the Commit Statuses and Checks permissions. If these permissions are not granted, all existing functionality is unaffected.
**Repository Selection for Schedules**
Schedules can now be configured with specific repositories that the session will be run with each time the schedule executes.
**Devin 2.2 Launch**
Devin 2.2 is the culmination of hundreds of improvements both big and small over the last few weeks including:
* 3x faster startup time to immediately see Devin's output and build trust that it's on the right track
* A new UI that connects every step of the dev lifecycle: start sessions from anywhere, review agent output directly in Devin, and jump back into sessions from code review.
* Smoother and faster Slack and Linear integrations to start sessions without having to switch context
See past release notes for the full list of the improvements.
**Full Desktop Testing**
Devin now supports end-to-end testing using computer use and can test any desktop app that can run on Linux. Devin will request to QA its PR, if you approve it, it will run your app, use its desktop to click around, and send you an edited recording of the testing for your review.
Existing users can enable Desktop mode in [Settings > Customization](https://app.devin.ai/customization).
**Devin v3 API Officially Released**
The v3 API is coming out of beta and is now the primary API for all Devin functionality. The new API provides all of the legacy API functionality and additionally provides role-based access control, session attribution, and new capabilities.
The legacy APIs (v1 and v2) will be deprecated in the future. The exact date will be announced in the product and in release notes. We commit to providing at least 30 days notice. During the deprecation period, the legacy APIs will continue to work but all new features will only be available in the v3 API.
**Sessions List Redesign**
The sessions list page has been redesigned with an updated layout featuring inline PR previews, message snippets, and status indicators. Sessions can now also be sorted by creation date.
**Merge Conflict Detection**
Devin will automatically notify users when a PR created in a Devin session has merge conflicts. Available on GitHub.com only.
**New Devin Scheduling Options**
Scheduled Devins can now be created as a one-time scheduled event, and existing schedules can be triggered on demand with the "Run now" button.
**Devin Review for GitHub Enterprise Server**
Devin Review now supports GitHub Enterprise Server (GHES) repositories. You can view PR diffs, run analysis, and use the Devin Review chat agent to propose and apply code changes. Some interactions with GitHub such as posting comments, submitting reviews, and merging are not yet supported on GHES.
**Repo Selector Enhancements**
The repository selector now features an "Only" button to quickly isolate a single repository and displays setup and indexed repo counts.
**Session Messages API**
A new `GET /messages` endpoint allows programmatic access to session message history.
**Minor bug fixes and improvements**
Various bug fixes and performance improvements across the platform.
**Visual Refresh and Polish**
The overall design has been improved and polished across the product. Some button locations have been minorly adjusted, but these changes do not impact the product functionality.
**Devin Fast Mode**
A new "Fast Mode" option is now available in the agent picker, delivering \~2x faster responses with the same intelligence at 4x ACU per session.
**Devin Review: Batch Comments**
When replying to PR review threads, you can now check "Start a review" to batch multiple review comments before submitting them all at once.
**Devin Review: Code Changes from Chat**
The Devin Review chat agent can now propose code edits directly in the conversation. You can review the suggested changes, then apply them as a commit to the PR branch without leaving Devin Review.
**Secure Mode for All Organizations**
Secure mode is now available for non-enterprise organizations. When enabled, Devin loses native internet deployment capabilities. You can find this setting under "Security settings" on the Customization page.
**Skills Support**
Devin now recognizes and uses skills defined in your codebase. Skills provide reusable instructions that Devin can activate, search, and invoke during sessions to follow your team's preferred workflows.
**Settings Search**
A search bar has been added to the settings sidebar, making it easy to quickly find any settings page by name or keyword.
**Minor bug fixes and improvements**
Various bug fixes and performance improvements across the platform.
**Schedule from the Input Box**
You can now quickly create a scheduled Devin session directly from the input box. Use the "Schedule Devin" option in the context menu or switch to the "Create schedule" tab in Advanced mode to set up recurring sessions without leaving the home page.
**Enterprise Organization Selection**
The enterprise landing page has been redesigned with a cleaner organization list, member counts, and sorting options for easier navigation across your enterprise.
**Devin Review: Auto-Review Settings**
Auto-review configuration is now accessible as a settings popover directly in the PR header, making it faster to enable or disable auto-reviews per repository.
**Devin Review: Hide Comment Highlights**
A new setting in the code diff viewer lets you hide comment highlight boxes for a cleaner reading experience when reviewing code.
**Git Permissions Update**
Removed the ability to index repos in the primary organization for enterprises.
**Minor bug fixes and improvements**
Various bug fixes and performance improvements across the platform.
**Scheduled Devins**
You can now create recurring Devin sessions that run automatically on a schedule. Configure frequency, prompt, and playbook from the new Schedules page in settings, and receive email notifications for schedule events.
**Devin Review: Draft PR Support**
Draft PRs now show a "Ready for review" button, allowing you to mark PRs as ready for review directly from Devin Review.
**Devin Review: File Comments and @Mentions**
You can now add file-level comments from the file header menu and use @mentions when editing existing comments in Devin Review.
**Settings Sidebar Reorganization**
The organization settings sidebar has been reorganized with clearer section headers including "Devin's resources," "Membership," "Settings," and "Integrations" for easier navigation.
**Per-Product Consumption Analytics API**
The v3 analytics API now includes a per-product breakdown of Agent Compute Unit consumption alongside existing totals. See [API Release Notes](/api-reference/release-notes) for details.
**Minor bug fixes and improvements**
Various bug fixes and performance improvements across the platform.
**[Devin Review Launch](/work-with-devin/devin-review)**
Devin Review is a reimagined interface for understanding complex PRs. Devin review groups related changes together logically, detects copied code, detects bugs and security issues, and an embedded PR chat interface.
**Repo Setup AI Suggestions**
The repository setup flow now provides inline AI-powered suggestions for setup commands, helping you configure repositories faster with less manual effort.
**Sessions API Enhancements**
New API endpoints allow you to retrieve session details by ID, send messages to active sessions, and filter sessions by origin (webapp, Slack, Teams, API, Linear, Jira). See [API Release Notes](/api-reference/release-notes) for details.
**Minor bug fixes and improvements**
Various bug fixes and performance improvements across the platform.
**Session Secrets via API**
You can now provide session-scoped secrets when creating sessions via the API, enabling secure credential management for automated workflows without manual intervention.
**Native Linear Integration**
Devin now has a built-in Linear tool for organizations with the Linear integration installed. This means you no longer need to install the Linear MCP separately to interact with Linear issues and projects.
**API Session Filters**
Added new filtering options to the sessions API endpoint, including the ability to filter sessions by user email for better session management and reporting.
**Syntax Highlighting for Kotlin and Protocol Buffers**
Code blocks now support syntax highlighting for Kotlin and Protocol Buffers (.proto files), improving readability when working with these languages.
**Git Settings Reorganization**
Personal git settings have been moved from the "Customization" section to the "Profile" tab in user settings for better organization and discoverability.
**Playbook Visual Distinction**
Playbooks now have a visual badge in the dropdown menu, making it easier to distinguish between playbooks and other options when starting a session.
**Machine Setup UX Improvements**
Small usability improvements to the machine setup flow for a smoother onboarding experience.
**Copy Context Button**
Each PR now has a "Copy Context" button that provides an AI-generated summary of the agent's work, context it found, and decisions it made, which is particularly useful when handing off work to other agents.
**Minor bug fixes and improvements**
Various bug fixes and performance improvements across the platform.
# Recent Updates
Source: https://docs.devinenterprise.com/release-notes/overview
The latest Devin updates: recently released features, improvements, and bug fixes across the product, updated with each release.
**Devin Coach Suggestions in the Input Box**
Introducing Devin Coach, a new feature that surfaces suggestions directly in the session input box as you write, helping you improve prompts before sending.
**Smarter Re-Review Behavior in Devin Review**
Devin Review now skips re-reviewing a PR when its diff against the base branch is unchanged (e.g. stacked PR restacks).
**Slack Thread Follow-Ups**
Devin sessions now subscribe to Slack threads they post in and route replies back to the session, so follow-ups in the thread reach Devin without re-tagging.
**Teams Polish**
Microsoft Teams user mentions now render as mention chips, emoji render inline, and channel-mention threading behavior now matches Slack.
**High Contrast Mode: System Option**
High contrast mode adds a "system" option that follows your OS preference, alongside broader accessibility improvements including a new accessibility submenu in the command palette.
**Sidebar Improvements**
The sidebar now reveals the active session when navigating via the command palette or a URL, newly created folders appear at the top of the list, and right-clicking a folder opens its options menu.
**Command Palette Improvements**
"Start session with a prompt" now supports multiline prompt editing, and "Search sessions" is pinned under Start session.
**Preview Toolbar Improvements**
Open-in-new-tab is now promoted to the preview toolbar, exposed ports moved into an overflow menu, and share/open-in-new-tab now follow the page currently being viewed.
**Platform Filter for Sessions**
The sessions list can now be filtered by platform.
**Ingest Scan Mode in Code Scan**
Ingest is now available as a scan mode directly in the new-scan sheet.
**Auto-Scan Schedules API**
Code scan auto-scan schedule routes are now generally available in the v3 org and enterprise APIs.
**Devin Local On by Default for Enterprise**
Devin Local is now enabled by default for enterprise customers.
**In-Page Search in Automations**
Automations pages now support in-page search via Cmd/Ctrl+F.
**Unified Workflow Permission Preview**
In Automations, the workflow permission preview pane now matches the live run pane.
**Side Chats**
Start a side conversation anchored to any point in a session to ask questions and dig into details without interrupting Devin's main work. Side chats open in a panel next to the worklog and support stopping in-flight responses.
**Syntax-Highlighted Code Blocks in Chat**
Fenced code blocks in chat messages now render with syntax highlighting.
**Command Palette Session Search Pagination**
Session search in the command palette is now paginated with an explicit "See more" option.
**Sidebar Organization Improvements**
The sessions sidebar now supports a "None" option in the Group by menu for a flat session list, a "New session in folder" action on folder menus, and a Cmd+K "Move to folder" command for the current session.
**Slack Improvements**
Users can now request channel access directly from Slack DMs, Slack-spawned sessions automatically get read access to their origin channel, and Devin posts a notice when a session is waiting for machine capacity. Workspace members beyond the first page no longer show as "Unknown User".
**Slack Connection Management**
The Slack integration settings now include a Reconnect option, with integration Manage menus aligned on a consistent Reconnect/Disconnect component.
**Playbook Mentions from Slack**
Playbooks mentioned in messages are now resolved when forwarding user messages from Slack.
**Agent Mode Selector Improvements in Automations**
The agent mode selector in Automations and On-Call now shows the resolved organization default (e.g. "Org default (Fusion)") and a description for each mode.
**Negated String Operators in Automation Conditions**
Automation conditions now support "not contains", "not starts with", and "not ends with" operators.
**Security Profile Safeguards in the Automation Editor**
The automation editor now warns when selected MCP servers or network-policy entries fall outside the governing security profile, and confirms security profile changes with a warning popup.
**Perplexity MCP in the Marketplace**
Perplexity is now available as an MCP server in the connectors marketplace.
**Queueing Support for Automations**
Automations now support queueing: set the maximum number of concurrent runs and queue depth per automation, see queue lifecycle states in the events table, and view an activity chart sourced from automation events. Concurrency groups are also available in the public v3 API.
**Automations API and Terraform Provider**
The automations API has been promoted from beta to the production v3 API spec, sessions can now be filtered by `automation_id`, and a `devin_automation` resource is available in the Devin Terraform provider.
**GitLab Support in Automations**
Automations now support GitLab triggers (issues, issue notes, pushes, and pipelines) with reply support on issue triggers, plus support for a GitLab service-account connection to automatically manage webhooks.
**Request Channel Access from Slack**
When Devin can't access a Slack channel, users now see a specific reason and can request access directly from Slack, with admin approval.
**Command Palette Improvements**
The command palette now surfaces session search results in top-level search, keeps rows on a single line, and nests navigation commands under a "Go to" command.
**Figma Live Embeds in Link Previews**
Figma links shared in chat can now render as live embeds in link preview cards.
**Accessibility Improvements**
A broad accessibility (WCAG 2.1 AA) pass across the webapp: proper labels and accessible names on controls, keyboard-accessible sortable tables and toggles, skip links, distinct navigation landmarks, document titles, and assertive error toast announcements.
**Security Profiles**
Security profiles are now generally available. Admins can define security profiles governing network access and apply them across sessions and automations, including an org-wide default and per-automation profile selection.
**Legacy Cascade Disabled by Default for Enterprises**
Legacy Cascade now defaults to disabled for enterprise tiers, with clarified settings copy.
**Personal Access Tokens**
Personal access tokens are now generally available for authenticating with Devin programmatically. Tokens are automatically revoked when a user loses account membership.
**MCP Connection Improvements**
MCP sessions resume automatically after completing OAuth, personal MCP connections are account-wide with OAuth scoped to the installation's organization, and marketplace MCP installs support custom server URLs.
**Easier Recovery from Failed Snapshot Builds**
Failed environment snapshot builds are now easier to find and fix in fewer clicks.
**Linear Reconnect Action**
The Linear connection manage menu now includes a Reconnect action.
**Redesigned Changes Tab**
The Changes tab now has a persistent file tree sidebar with a tree or flat list toggle, and full-width diffs with language icons.
**Session Sidebar Improvements**
A new "Empty folder" action archives all sessions in a sidebar folder, session menus are reorganized into submenus, and archived sessions have clearer indicators.
**Session Renames in the Timeline**
When a session is renamed, the change now appears in the session timeline.
**Approval Progress at a Glance**
The pull request merge status bar now shows approval progress as a count of received versus required approvals.
**Slack Access Defaults**
Devin's Slack channel access is now configurable for all accounts, including a default of all public channels plus direct messages and an account-level setting for DM access.
**MCP Execution from Devin's Servers**
MCP tools now run from Devin's servers rather than the session's remote machine.
**Connectors Page Improvements**
Plugin-provided MCP servers are grouped into their own section, organization marketplace installs are always organization-scoped, and MCP installations without a configured auth method can fall back to dynamic OAuth.
**Control Where Legacy Cascade Is Available**
The enterprise Cascade setting is now a scope choice — enabled everywhere, JetBrains plugin only, or disabled — so admins can move users to Devin Local while keeping Cascade in the JetBrains plugin.
**Opt-In Public GitHub Repo Support in Automations**
Admins can now opt a public GitHub repo into automation triggers.
**Primary Billing Organization Attribution**
All users will be automatically assigned a primary billing org that all Devin Desktop and CLI usage is attributed to.
**IP Allowlists Cover Automation Webhooks**
Account IP allowlists are now enforced on automation webhooks, with support for additive webhook-only ranges.
**Bug Fixes**
This release also includes many smaller fixes and improvements, including Slack and Teams thread cards rendering markdown, queued messages showing slash commands as command chips, quote captions preserved as drafts, smoother streaming in very long sessions, and various UI polish across the webapp.
**Word-Level Diff Highlights**
Unified diff views now highlight exactly which words changed within a line, making edits easier to scan.
**Link Preview Cards in Chat**
Links shared in your messages and in Devin's replies now render as rich preview cards.
**Remix Keeps the Playbook**
Remixing a session now carries the original session's playbook and rich message content into the new prompt.
**Expandable Knowledge Previews**
Knowledge cards now include an expand toggle so you can read the full note content in place.
**Session Organization Improvements**
You can now remove archived sessions from sidebar folders, and opening an information tab reveals the workspace, including on mobile.
**Slack DMs with Automation Devins**
Automations can now work over Slack direct messages, with a setting to control whether DMs are enabled.
**Simpler Automation Channel Access**
Configuring which Slack channels an automation can access is now a simple two-mode choice.
**Playbooks Scoped to the Right Organization**
Playbook references in Jira and Linear mappings and automation triggers are now validated against the correct organization, with clear removal notices when a mismatch is found.
**SCIM Provisioning Is Generally Available**
SCIM user and group provisioning is now generally available for enterprises, enabling automated user lifecycle management from your identity provider.
**Audit Logging for Devin Local Settings**
Changes to Devin Local settings are now recorded in the enterprise audit log.
**IdP Group Improvements**
The enterprise IdP groups tab now shows member counts, and the group popover is easier to read with middle-truncated names and a copy button.
**Bug Fixes**
This release also includes many smaller fixes and improvements, including clearer Slack channel mapping copy, smoother scrolling in long sessions, fixed lightbox arrow-key navigation, more reliable copying from the shell tab, and various UI polish across the webapp.
**Redesigned Model Picker**
The model picker has been redesigned into a single organized menu where you can choose a capability, toggle Fusion, adjust speed, and switch modes.
**Slash Commands in the Message Box**
Typing commands like /btw and /queue in the message box is now more discoverable, including a new /ask command that switches the session to Ask mode.
**Playbook Previews in the Message Box**
Hovering over a playbook macro in your message now shows a preview of its contents, with a button to copy the full text.
**Start Windows Sessions from Slack**
A new !windows command lets you start a session on a Windows machine directly from Slack.
**Approve Network Access Requests from Slack**
When Devin requests access to a blocked network destination, you can now approve or deny the request directly from Slack.
**Clickable Finding Counts in Devin Review**
Finding counts on PR cards are now clickable and take you straight to the relevant findings in the embedded review view.
**Required Approvals at a Glance**
Devin Review now shows how many approving reviews a pull request requires.
**Redesigned New-Scan Flow**
Starting a code scan now uses a streamlined flow with support for single-repository, multi-repository, and bulk scans.
**OIDC Identity Tokens**
Devin can now authenticate to cloud services using short-lived OIDC identity tokens.
**API Additions**
The API now supports unarchiving sessions and creating ingestion-mode code scans at the organization and enterprise level.
**Bug Fixes**
This release also includes many smaller fixes and improvements, including faster DeepWiki MCP question answering, links shared from Slack rendering correctly in chat, a clearer Approve button for environment changes, the session "Code files" tab renamed to "Editor", easier text quoting, and various UI polish across the webapp.
**Smarter Linear Thread Handling**
Replies in different Linear comment threads are now routed to the correct Devin session, and follow-up work on the same issue continues in the original session for better continuity.
**Automations Consumption Visibility**
A new Consumption tab on each automation shows the ACUs used by sessions the automation has started, so you can track the cost of your automated workflows.
**Slack Channel Improvements for Automations**
When configuring an automation's monitored channels, Devin can now automatically join public channels you select, and you can grant access to all public channels at once.
**Safer MCP Access Changes**
Switching an MCP server from personal to Organization access now shows a warning step explaining that your connection will be shared with other members before you confirm.
**Review Usage in Consumption Analytics**
Consumption analytics now shows what triggered each Devin Review run, making it easier to attribute review usage.
**Improved Quoted Attachments**
Quoting text from files or previous messages has a refreshed look, and clicking a quote reopens it on the original surface with the relevant lines highlighted.
**Performance Improvements**
The webapp loads faster and stays responsive in long sessions, including faster boot, smoother work logs, and better handling of large diffs.
**Devin Outposts**
This release introduces Devin Outposts, a new capability for running Devin workloads in your own environment. It is disabled by default — contact your Cognition representative if you are interested in enabling it.
**Quicker Access to Enterprise Settings**
Enterprise admins can now jump to enterprise settings pages, including from a child organization, using the cmd+K command palette.
**Code Scan Profile Filters**
The scan profiles tab now supports filtering profiles by type and mode.
**Snapshot Build History Filters**
Snapshot build history can now be filtered by build status and platform.
**API Additions**
Enterprise member API responses now include each member's enterprise join date, and organization consumption endpoints now report ACUs used by Devin Review.
**Bug Fixes**
This release also includes many smaller fixes and improvements, including icons on the enterprise MCP server list, the ability to switch an automation between session types after creation, clearer error messages, and various UI polish across the webapp.
**Centralized Skill Management via Plugins**
Skills can now be distributed via Plugins that can be installed and governed centrally, then applied consistently across Devin Cloud, Devin CLI, and Devin Desktop (via Devin Local).
**Enterprise-Grade Plugin Governance**
Admins can configure required, optional, and forbidden plugins in Settings → Marketplace, and organizations inherit enterprise-managed plugin policies automatically.
**Multi-Repository Code Scans**
Code scans can now span multiple repositories in a single scan, with per-repository details and a repository filter on findings.
**Chained Attack Paths in Findings**
Related findings are now linked together as chained attack paths, helping you understand how individual vulnerabilities combine into larger risks.
**Queued Messages Improvements**
You can now set a preference to automatically queue messages while Devin is working, send the next queued message by pressing Enter in an empty composer, and queued messages now default to sending immediately when Devin becomes available.
**Tasks Tab in the Workspace**
A new Tasks tab in the workspace tab picker shows Devin's latest task list so you can follow progress at a glance.
**Inline Link Previews**
Links shared in chat now render inline previews for markdown, PDF, HTML, and CSV content.
**Sortable Tables in Chat**
Tables in Devin's chat messages are now sortable by column.
**Custom Slack Emoji Rendering**
Your workspace's custom Slack emojis now render correctly in synced session message history.
**Instant Slack Unsync Command**
Sending "unsync" (or "!unsync") in a synced Slack thread now immediately stops syncing the conversation.
**Revamped Automations Pages**
The Automations pages have been redesigned with a streamlined editor, clearer trigger configuration, and a new option to create a long-running session that receives subsequent trigger events.
**GitHub Enterprise Server Support for Automations**
Automations can now target repositories hosted on GitHub Enterprise Server.
**Bug Fixes**
This release also includes improved bulk secret import with name validation, expanded keyboard shortcuts, better mobile layouts, a simplified Devin Desktop login button in settings, cleaner Slack send options in the composer, more reliable MCP tool listing for HTTP servers, and many performance improvements to session streaming and PR review loading.
**Quote Text in Your Messages**
You can now select text in a session — from files, the worklog, or Devin's messages — and quote it directly in your next message, making it easier to reference exactly what you're talking about.
**Filter Sessions by Skill**
The sessions list can now be filtered by which skill was activated during the session.
**Session Sizes Are Now ACU-Only**
Session t-shirt sizes (XS–XL) are now based solely on ACU consumption and no longer factor in the number of user messages sent.
**Promote Playbooks to Your Enterprise**
Admins can now promote a playbook from a single organization to the entire enterprise, making it available across all organizations.
**Interactive ACU Chart Legends**
Legend entries on the enterprise ACUs-by-product chart are now clickable, letting you toggle individual series on and off.
**Redesigned Account Switcher**
A redesigned account switcher makes it easier to move between your organizations, with a clearer two-pane layout for people who belong to an enterprise.
**Copy Commands from the Worklog**
Shell commands in the session worklog now have a copy button that copies the full command to your clipboard.
**Streamlined Copy Actions**
Copy actions in the command palette are now grouped together under a single "Copy…" menu.
**Lists That Load as You Scroll**
Long lists such as repository and snapshot pickers now load automatically as you scroll, instead of requiring a "Load more" button.
**Fullscreen Devin Desktop**
The Devin Desktop VNC viewer now supports native fullscreen.
**Clearer Bulk Secret Imports**
Importing multiple secrets at once now reports errors per line, so you can see exactly which entries need fixing.
**Bug Fixes**
This release also includes a working organization filter on the enterprise sessions view, self-serve removal of GitHub Enterprise Server app configurations, and various other UI improvements throughout the app.
**Redesigned Review Comment Composer**
The Devin Review comment composer now uses GitHub-style Cancel, Comment, and Start a review buttons, with Cmd+Enter to submit and Escape to dismiss. In the pull request view embedded in a session, a new Commits tab lets you browse the changes commit by commit.
**Apply Environment Config Suggestions from Slack**
When Devin suggests an environment configuration change in Slack, the message now includes a diff of the proposed change and an Apply button, so you can accept it without leaving Slack.
**Mobbin MCP Server**
The Mobbin MCP server is now available in the integrations marketplace.
**Reorganized Settings Navigation**
Skills & Rules and Plugins now live together under a new Resources section, the Plugins page has a wider and clearer layout, and your personal analytics have moved into your personal settings.
**Diff Line Permalinks**
You can now share direct links to specific lines in a Devin Review diff via the URL hash — useful for pointing teammates to exact code locations.
**Slack !agent Renamed to !normal**
The `!agent` Slack bang-command has been renamed to `!normal` for consistency with the standard Devin mode naming.
**Slack Sync Toast Improvements**
The Slack sync notification toast now has clearer copy, can be dismissed per-tab, and includes a "don't remind me" opt-out.
**Service User Automations**
Service users can now create and manage automations via the API, enabling programmatic automation workflows.
**Snapshot Build Trigger**
`snapshot_build:completed` is now available as an automation event trigger, letting you kick off workflows when a new environment snapshot finishes building.
**MCP Run-As-Creator Warning**
Automations now display a warning when a user-scoped MCP server is selected but run-as-creator is turned off, helping avoid permission mismatches at runtime.
**Code-Snippet Telemetry Audit Log**
Changes to code-snippet telemetry settings are now recorded in the customer-facing audit log.
**Security Scan Remediation API**
The v3 API now supports endpoints for remediating security scan findings.
**API Default Devin Version**
API-created sessions can now specify a default Devin version, giving teams programmatic control over which Devin version runs their workloads.
**Git-Backed Blueprints**
Blueprints can now be backed by a Git repository, letting you version-control and collaborate on environment configurations alongside your code.
**Blueprint Permission Descriptions**
Blueprint permission names and descriptions now clearly indicate their scope, making it easier to understand what each permission controls.
**Hover Copy for Tables**
Markdown tables in sessions now display a copy button on hover, letting you quickly copy table contents to your clipboard.
**Bug Fixes**
This release also includes fixes for virtualized Review comments hijacking scroll, diff-viewer partial-expand into file boundaries, collapsed worklog diff-stat clipping in WebKit, desktop VNC reconnection after session wake, terminal LF-to-CRLF conversion on non-PTY flush, PAT-authenticated webhook error comments now being allowed, and various other UI polish improvements throughout the app.
**No-Access Permission Popover**
When your connected account lacks write permission on a repository, Devin Review now shows a clear "no access" popover explaining what's needed instead of silently failing.
**Auto-Review Scoped to Your PRs**
The auto-review user preference now applies only to PRs you author, so enabling it won't trigger automatic reviews on other people's pull requests.
**PR-Link Preference**
Users can now control whether in-session PR links open in the Devin tab, in GitHub, or in Devin Review.
**Persist Model Selection**
Your chosen default model is now remembered when you select it in the agent picker, persisting across page reloads.
**Network Access Requests**
In network-restricted sessions, Devin can now request access to specific domains. The request surfaces to you for approval, removing the need to preconfigure every domain.
**GitLab Mention-Only Comments**
Devin now respects mention-only PR comment settings for GitLab merge requests, reducing notification noise for teams that prefer targeted mentions.
**Slack Thread Sync**
Sessions can now sync messages bidirectionally with Slack threads. A confirmation prompt appears for busy threads, and global sync is enabled by default for new sessions.
**Unarchive on Mention**
Mentioning @Devin in a Slack thread for an archived session now automatically unarchives it so you can continue the conversation.
**Slack Commands Anywhere**
Slack bang-command macros (like `!ultra` or `!fast`) are now recognized anywhere in your message, not just at the beginning.
**Inline Mute Reminder**
The mute/quiet-mode reminder now appears inline in the session footnote instead of as a separate message, reducing clutter.
**MCP Read-Only Mode**
The secure-mode profile UI now includes a toggle for restricting MCP servers to read-only access.
**Improved Webhook Trigger Setup**
The automation editor now shows the webhook URL and secret inline before you save, so you can configure the external service first.
**Usage Analytics: PR Ratio Chart**
A new weekly Devin PR ratio chart with repository filtering is available on the Repositories analytics tab, along with CSV export and improved number formatting across all analytics tables.
**Skills Analytics**
A new enterprise-level skills analytics page shows skill usage patterns, adoption rates, and performance across your organization.
**ACU Limit Audit Trail**
Organization ACU limit changes are now recorded in the customer-facing audit log, giving enterprise admins full visibility into limit adjustments.
**Read-Only Scan Profiles**
Enterprise-managed scan profiles now render as read-only in child organizations, preventing accidental modifications to centrally managed security policies.
**Analytics Page Improvements**
Analytics time-range and filter selections now persist in the URL for easy sharing, and the organization picker in productivity dashboards supports pagination for enterprises with many organizations.
**Redesigned Environment Page**
The environment page is redesigned with platform filters, an active snapshot grid layout, and platform-specific icons for better discoverability of your build configurations.
**Cross-Platform Repository Cloning**
Organizations can now clone configured repositories on every available build platform, not just the default — enabling consistent environments across Linux, macOS, and other platforms.
**Bug Fixes**
This release also includes numerous bug fixes across the platform — including fixes for the Slate editor crash on mobile, voice recording button visibility on narrow screens, Review header alignment, IDE frame layering over dialogs, MCP OAuth redirect handling, mentions preserving spaces correctly, false "Installation out of date" banners on fresh MCP installs, blueprint drawer state preservation, unsubscribe link routing for enterprise emails, and various UI polish improvements throughout the app.
**Archive/Unarchive Sessions from Command Palette**
Sessions can now be archived or unarchived directly from the Cmd+K command palette on session pages, without navigating to session settings.
**Run-Once Automation Schedules**
Automations now support a run-once schedule option for one-time executions, in addition to recurring schedules.
**MCP "Installation Out of Date" Banner**
Installed MCP integrations now surface an "Installation out of date" banner with one-click marketplace refresh when an update is available.
**Post-Build Section for Blueprints**
The blueprint editor now includes a Post Build guide item for organization and enterprise blueprints.
**Readable PR Review Label Colors**
PR Review labels now render with readable text in both light and dark themes.
**Usage Analytics Improvements**
The Consumption Dashboard now uses bar charts for the session activity chart, combines active and review users into a single chart with a metric selector, adds a counts/percentages toggle, and normalizes the per-tab export buttons to a consistent "Export" control.
**Pin/Unpin Sessions from Command Palette**
Sessions can now be pinned or unpinned directly from the Cmd+K command palette for faster access to important sessions.
**Start Session in Background**
A new "Start session in background" button on the home page lets you kick off a session without navigating away from your current view.
**View Latest Version for File Tabs**
File tabs in sessions now include a "View latest version" affordance, making it easy to jump to the most recent version of a file Devin has edited.
**Security Findings in Ask Devin**
When using Ask Devin within PR Review, the AI context now includes security findings, enabling more security-aware assistance during code review conversations.
**"Repo Rule" Badge on Lifeguard Findings**
Lifeguard bugs that were flagged from repository rule files now display a "Repo rule" badge, helping reviewers distinguish rule-sourced findings from general analysis.
**Split View Auto-Disable on Narrow Panels**
The Split view option in PR Review is now automatically disabled when the panel is too narrow to display it usefully, preventing layout issues on smaller screens.
**Usage Analytics — Top 10 Rankings**
Consumption analytics now includes Top 10 ranking charts for repositories (in Reviews usage) and for users and service users (in the Consumption tab), giving admins quick visibility into where usage is concentrated.
**Enterprise Wide Snapshot Build Schedule**
Enterprises can now configure a snapshot build schedule, controlling when environment builds run. Blueprint settings also display drift warnings when the environment is out of sync, with actionable buttons to trigger a re-sync.
**Add Enterprise Members When SSO Is Required**
Org admins can now add existing enterprise members to their organization even when SSO is required for enterprise membership.
**ACU Billing Schedule Warning**
Enterprises consuming ACUs without an active billing schedule now see a warning, helping admins avoid unexpected usage without payment coverage.
**MCP Marketplace Expansion**
48+ new engineering MCP connectors are now available, including Miro, Mixpanel, Honeycomb, Postman, monday.com, Klaviyo, and many more. 42 previously-beta MCPs have graduated to general availability. New additions include LaunchDarkly (with hosted OAuth), Fathom, Attio, and Calendly. Google Drive MCP is now available to all users.
**Dedicated MCP Management Page**
Enterprise admins now have a dedicated MCP management page with per-server detail views showing organization-wide and per-session usage, replacing the previous side panel.
**GitLab User Identity Linking**
Link your personal GitLab account so Devin creates Merge Requests under your GitLab user instead of the Devin identity. For enterprises with self-hosted GitLab instances, admins can register a GitLab OAuth Application under Advanced settings to enable user linking for self-hosted instances.
**Devin Review for GitLab**
Devin Review now supports GitLab Merge Requests. Intelligent diffs, inline comments, and AI chat all work on GitLab MRs. Your GitLab MRs appear in the sidebar organized by status (Needs your review, Returned to you, Approved, Waiting for reviewers, Drafts). GitLab repos can be added to auto-review in Review settings.
**File Path Visible During Streaming Edits**
The full file path is now shown while the edit tool is actively streaming changes, so you always know which file Devin is modifying.
**Deduplicated File Tabs with Version Switcher**
When multiple versions of the same file exist, they are consolidated into a single tab with a version dropdown instead of cluttering the tab bar.
**Slack Formatting in Webapp Comments**
Bold, links, code, and other Slack formatting now renders correctly in webapp thread comments forwarded from Slack.
**PR Context Visible While Waiting for CI**
PR-ready context is now shown while CI checks are still running, so you can start reviewing before checks complete.
**Improved Feedback Controls**
Both thumbs-up and thumbs-down buttons are now always visible on messages. Session-level feedback and a qualitative feedback modal make it easier to share detailed feedback.
**Incremental Generation Steps in Automation Input**
The AI-assisted automation input now shows incremental generating steps as it builds your automation configuration.
**Public Repos Shown as Disabled in Repo Picker**
Public repositories now appear greyed out in the repo picker instead of being hidden, making it clear they exist but are not selectable.
**"User Only" PR Author Enforcement**
A new "User only" option is available in the "Open PRs as" setting. When selected, Devin will only create PRs under the user's identity and will fail if their Git account is not connected. Automations and service users fall back to the Devin identity. Enterprise admins can enforce this setting across all organizations.
**Cmd+K: Switch Organization & Copy Org ID**
The command palette (Cmd+K / Ctrl+K) now supports switching between organizations and copying your org ID without navigating to settings.
**Sidebar: Unpin & Remove-from-Folder Quick Actions**
The sidebar archive button has been replaced with context-aware quick actions: pinned sessions show an "Unpin" button, and sessions in a folder show "Remove from folder." Archive remains accessible via the context menu.
**Wiki: Clean Page URLs**
Wiki pages now use cleaner `/page/` routes instead of the previous longer format, making links easier to share and bookmark.
**Automations Sidebar**
Automations now appear in the main navigation sidebar for quicker access to your configured automation rules.
**Japanese Translations: 100% Coverage**
All remaining Japanese translation keys have been filled across the platform, bringing Japanese language coverage to 100%.
**Ask Devin: @repos Picker Scoped to Search Repos**
The @repos file picker in Ask Devin now only shows repositories from your selected search scope, reducing noise when referencing files.
**Suggested Knowledge Visible in Session Worklog**
When Devin suggests a knowledge item during a session, it now appears as a standalone event in the worklog for easier visibility and review.
**Devin Review: Comment Language Selector**
When reviewing PRs in Devin Review, you can now select the language for AI-generated review comments (e.g., English, Japanese, Spanish).
**Devin Review: Security Findings**
All Devin reviews now include a security findings section. The security reviewer respects your repository's SECURITY.md file to tailor its analysis to your project's security policies.
**Devin Review: Code Owner Review Block**
The merge bar now shows when a PR is blocked waiting for code owner approval, making it clear which reviews are still required before merging.
**Devin Review: GitHub Alert Callouts**
GitHub-style alert callouts (note, warning, caution, etc.) in markdown files now render with proper styling in Devin Review.
**Slack: Preceding Thread Messages as Context**
When Devin is mentioned in a Slack thread, it now receives the preceding thread messages as context, enabling more informed responses without needing to repeat background information.
**Slack: !agent Bang Command**
Use `!agent` in Slack messages to Devin to explicitly route your request to a full Agent session instead of Ask mode.
**Default Sync with Slack Per Session**
New sessions can now default to syncing messages with Slack, configurable at the organization level so teams stay in the loop automatically.
**Automations: Slack Channel Updates**
Automation run results can now be posted to a designated Slack channel, keeping your team informed of automated session outcomes.
**Linear: Projects Filter for Triggers**
When configuring Linear-triggered automations, you can now filter by Linear project to scope which issues trigger Devin sessions.
**MCP Server: View Logs on Error**
MCP plugin error cards now include a "View logs" button linking directly to the MCP output channel, plus detailed error information surfaced in the plugin status card for faster debugging.
**Axiom MCP Server**
A new official Axiom MCP integration is available, allowing Devin to query your Axiom logs and observability data during sessions.
**Structured Output Schema for Playbooks**
Playbooks now support a structured output schema, enabling Devin to return results in a defined JSON format for easier programmatic consumption.
**Enterprise Knowledge Limit Increased to 300**
The maximum number of enterprise knowledge items has been increased from 200 to 300.
**Session Folders**
Group sessions into named folders in the sidebar. Move sessions via drag-and-drop or the three-dot menu. Folders are personal, so each user defines their own layout.
**!ultra and !fast Mid-Session Toggles**
You can now start sessions on Devin Ultra directly from Slack with the `!ultra` command. You can also switch between Ultra and Fast modes mid-session by typing `!ultra` or `!fast` in the Slack thread.
**Smarter Emoji Reactions**
Devin now only adds sleep/archive emoji reactions to messages that are explicit sleep or archive commands, reducing noise on other status messages.
**Custom OAuth for Marketplace MCP Servers**
Marketplace MCP servers that require organization-specific OAuth client credentials can now be configured directly from the integrations page.
**Markdown File Preview in Worklog**
Markdown files created during a session now render with a preview toggle, letting you see the formatted output alongside the raw content.
**Web Search Enterprise Setting**
Enterprise admins can now enable or disable Devin's web search capability via a new toggle in enterprise settings.
**"Users" Tab Renamed to "Members"**
The org membership page tab now reads "Members" for clarity.
**Devin Review: Pending PR Reviews Canceled on New Commits**
When new commits are pushed to a PR, any in-progress Devin reviews are now automatically canceled. The PR Review API also reflects this with a new `cancelled` status on review objects.
**Large Pastes Automatically Attached as Files**
Pasting large content (10k+ characters) into the composer now automatically attaches it as a file, regardless of existing message length. This keeps your prompt clean and avoids hitting size limits.
**User Mentions Rendered as Styled Links**
@mentions in session messages are now displayed as styled deeplinks instead of the raw "@Name (ID)" format.
**"Sent from Slack/Teams/Linear" Indicator**
Follow-up messages that originated from an integration now show a small badge indicating their source (e.g., "Sent from Slack").
**Echo Message to Slack Toggle**
A new toggle lets you bypass Slack message suppression and echo your webapp messages into the Slack thread, even in quiet-mode sessions.
**Improved Slack Message Rendering**
HTML entities in Slack messages are now properly decoded outside of code blocks, fixing garbled characters in forwarded content.
**Official Figma MCP Integration**
The official Figma MCP server is now available with suggestions enabled. The previous unofficial integration has been deactivated.
**IdP Group Role as First Assignment**
Org-scoped IdP groups can now use a group role as their very first role assignment, removing the previous requirement to set an individual role first.
**Success Confirmation After Org Creation**
Creating a new organization within an enterprise now shows a clear success state, confirming the operation completed.
**Start a New Session with This Prompt**
The first message in a session now shows a "Start a new session with this prompt" button, replacing the previous "Start duplicate session" menu action. Reuse any prompt for a fresh session in one click.
**Playbook Devin Mode**
Playbooks can now specify a Devin mode (e.g., Fast or Normal). When launching a session from a playbook, the agent picker reflects the playbook's configured mode.
**Configurable Auto-Reload Threshold**
You can now customize the balance threshold that triggers auto-reload in the billing usage modal.
**Jira Webhook Failure Recovery**
When a Jira webhook connection fails, a banner now appears in your Jira integration settings with a one-click reconnect action to restore the connection.
**Devin Review: Action-Required Flags on PRs by Default**
Devin Review now posts orange action-required flags to your GitHub pull requests by default when issues are found that need investigation.
**Webhook URL in Automation Editor**
The automation editor now displays the webhook URL directly under the webhook trigger, so you can copy it without navigating away.
**Improved Slack Message Formatting**
Devin's messages in Slack now use full markdown formatting for all users, providing richer text rendering with proper links, code blocks, and lists.
**Send Messages While Session Is Queued**
You can now send messages to a session that is waiting for capacity. Your messages will be delivered as soon as the session starts.
**Persist Chat Draft Across Panel Close**
Draft messages in the session composer are now preserved when the panel is closed and reopened, so you won't lose work in progress.
**Session Counts on Collapsed Sidebar**
Session counts are now visible on collapsed sidebar section headers, giving you a quick overview without expanding each section.
**Devin Review: Connect Personal Account from Blocked Controls**
In Devin Review, when Review, Merge, or comment actions are blocked because your personal identity isn't linked, you can now connect your GitHub or GitLab account directly from the blocked control without navigating to settings.
**Active Todo in Slack Plan Header**
The collapsed plan header in Slack threads now shows the currently active todo item, so you can see what Devin is working on at a glance.
**Detect @Devin Mentions After Inviting the Bot**
When you tag @Devin in a channel where the bot isn't present and then invite it, Devin now detects and responds to your original mention.
**Lower Minimum Per-Session Limit for Automations**
The minimum per-session limit for automations has been lowered from 3 to 1, giving you finer-grained control over automation budgets.
**Scratchpad Moved Under MCPs in Automations**
The scratchpad section in the automation editor has been moved to the top level under MCPs for easier discoverability.
**Prompt to Reconnect Linear**
When creating a Linear automation with an expired personal token, you'll now be prompted to reconnect before proceeding.
**Personal Automations**
You can now create personal automations that run under your own identity. Personal automations include a dedicated toggle, permission model, and badge in automation lists. The legacy Schedules page now shows migration guidance to help you transition to the new Automations system.
**Devin Review: Enrolled Users, Spend Limits, and GHES/GitLab Support**
Devin Review now includes an enrolled users management table in settings, a redesigned per-PR spend limit that acts as a soft block (you can re-enable if needed), and pinned section titles above file headers in the embedded review view. "Open in Devin Review" is now available for GitHub Enterprise Server and GitLab PRs.
**Pre-Approve Testing**
A new user preference lets you always approve testing for future sessions, so Devin can test changes without prompting each time. Access it from your profile settings or via the split-button on the "Test the app" action.
**V3 API: Organization Members and Automations**
New org-scoped `GET /v3beta1/organizations/{org_id}/members` endpoint for listing organization members. A full automations CRUD API is also now available via v3.
**SSO/SCIM: JIT Provisioning and Enterprise Redirect**
SSO just-in-time provisioning can now be toggled on or off, with group sync gated separately. SSO-only enterprise users are now automatically redirected to their enterprise webapp host on login.
**Settings Improvements**
The Repositories page now supports pagination. Search results in the settings sidebar are deduplicated with indent guides. A permission-gated "Add repositories" button and empty state have been added to Skills & Rules. Terminology has been updated from "org" to "organization" throughout.
**Child Sessions: Tree Connector**
Child sessions now display with a tree connector in the sidebar, making parent-child relationships visually clear.
**Bug Fixes**
Persisted orange sidebar indicator for quota-suspended sessions. Made question answer submission optimistic, removing click lag. Fixed send button centering at fractional zoom levels. Added email fallback for IdP users without a name in the session list. Fixed cross-org router links dropping query string and hash. Added cost column to scheduled sessions past sessions list. Cleared "Approve session" attention dot once the session is read. Restored question selections when an optimistic submit fails. Pinned bulk-edit bar to viewport bottom centered over content column. Included enterprise members in the session creator filter.
**New Command Palette**
The redesigned command palette is now available with improved search, keyboard navigation, and settings integration. Access it with Cmd+K (Mac) or Ctrl+K (Windows/Linux) to quickly navigate pages, settings, and actions.
**Automations: Files-Changed Trigger**
The automation builder now supports file-change triggers for GitHub push events. You can configure automations to run only when specific files or directories are modified in a push. Pull request triggers also automatically add the appropriate action filter.
**PR Review Sidebar Restructure**
The in-session PR review sidebar has been redesigned with collapsible sections, portalized toolbar actions, and a new diff settings menu replacing the previous split/unified toggle.
**Raindrop.ai MCP in Marketplace**
The Raindrop.ai MCP server is now available in the MCP marketplace.
**Disable Review/Analysis for Merged and Closed PRs**
The review and analysis trigger is now disabled for already-merged and closed pull requests, preventing unnecessary processing.
**Wake Sleeping Sessions on Retrigger**
Sleeping sessions now automatically wake up when a PR comment retrigger is posted, so you no longer need to manually restart them.
**Devin Review: Respect CI Monitoring Setting**
Devin Review now correctly honors the "Disable automatic comment and CI monitoring" checkbox for merge-conflict notifications.
**Bug Fixes**
Fixed intermittent Recent repos display issue. Fixed diff view flashing two-column layout before snapping to unified view. Added DeepWiki button to repo indexing header. Fixed infinite page spinner when a user is not a member of the resolved organization.
**Platform Default Settings**
Org admins can now set a default platform (Linux or Windows) for all new sessions, and individual users can star their personal preference. The default platform is honored across all session creation methods, including Slack, Linear, Jira, API, and automations.
**Slack Channel Override**
Type `!channel #channel-name` in Slack to override which channel Devin spawns its response thread in for that session.
**MCP OAuth Resource Parameter**
MCP OAuth flows now forward the RFC 8707 resource parameter, fixing authentication for MCP servers that require resource indicators (such as Snowflake and Runlayer).
**Custom RRULE Schedule Input**
Automation schedules now support pasting raw RFC 5545 recurrence rule strings directly, with validation and auto-detection, for schedules that go beyond the visual editor.
**GitLab Interactive PR Review**
GitLab repositories now support interactive PR review — Devin can post review comments and resolve threads as you — when the read-write GitLab connection is enabled.
**PR Review Status API**
A new `GET /v3/enterprise/pr-reviews` endpoint lets you poll Devin Review status programmatically, with optional commit SHA filtering.
**In-App Support Dialog**
"Contact support" now opens an in-app dialog where you can submit a ticket directly, replacing the previous email link.
**Inline Repo Permission Toggle**
You can now toggle repository permissions between "Read only" and "Read & write" directly from the permissions table, without needing to remove and re-add the repository.
**Enterprise Max Concurrent Snapshot Builds**
Enterprise admins can now set a maximum concurrent snapshot builds limit in enterprise settings, with backend enforcement to prevent build queue overload.
**GitLab OAuth Scope and Token Refresh**
GitLab user OAuth now requests the broader `api` scope for better compatibility, and tokens are automatically refreshed before they expire.
**Network Config Editor Redesign**
The network policy editor has been redesigned as an inline-editable list with multi-line paste support and duplicate detection, fixing the issue where domains typed but not submitted were silently lost on save.
**GitHub Connection No Longer Required for Automations**
GitHub-triggered automations no longer require a personal GitHub connection, allowing teams to rely on the org-level connection exclusively.
**PostHog MCP**
The PostHog MCP server is now available in the MCP marketplace, enabling product analytics integration directly from Devin sessions.
**Other Improvements**
Automation sessions now appear in a dedicated "Automations involving you" sidebar folder instead of being auto-pinned. Session @-mentions in chat are clickable links. A new Cmd+K action copies the session URL to clipboard. Archive undo now restores cascade-archived child sessions. MCP connection errors are surfaced instead of silently swallowed, and a new disconnect action removes stored OAuth tokens. Integration mappings for Linear, Slack, Teams, and Jira are validated at save time. The repo selector shows a Recent section and org labels. Tool calls in Watch Devin Work display timing. Automation-spawned sessions can be renamed by any org member. Integration page actions are permission-gated. File URLs in the timeline link to the correct git provider. GHES installations resolve bot identity per-config and scope webhook processing to the owning account.
**Collapsible Session Folders**
Sessions in the left sidebar can now be organized into collapsible folders. Click the chevron to expand or collapse a folder, and your preference is persisted per organization.
**Archive All Sessions**
A new "Archive all" option in the sidebar menu lets you archive all sessions or asks at once, with a confirmation dialog and undo support. Child sessions skip the confirmation step for faster cleanup.
**Sub-Devin Session Filter**
The sessions page now includes a "Sub-Devin" filter that lets you view child sessions independently, with support for combined parent and child filtering.
**Default Member Roles**
Enterprise admins can now configure default roles that are automatically assigned to new organization members on join, with badge display in the members list and safeguards against accidental deletion of roles in use.
**GHES App Registration Restriction**
GitHub Enterprise Server app registration is now restricted to one app per account and host combination, preventing duplicate registrations with a clear error message when a conflict is detected.
**Copyable Organization ID**
Your Organization ID is now displayed with a one-click copy button on both the Settings → General and Settings → Devin API pages, making it easy to share with support or use in API calls.
**Admin-Enforced Settings Lock Icon**
Settings that have been locked by an admin now display a lock icon with an explanatory tooltip, replacing the previous banner-style callout for a cleaner interface.
**MCP OAuth Client Credentials**
When installing MCP integrations that don't support Dynamic Client Registration (such as Salesforce), you can now supply your own OAuth client credentials directly in the configuration flow.
**Tavily MCP in Marketplace**
Tavily web search is now available in the MCP marketplace, providing AI-optimized real-time web search and content extraction capabilities for your Devin sessions.
**PR Actions & Auto-Review Settings**
The PR actions menu in Devin Review has been restored with an auto-review toggle and personal settings popover, giving you quick access to review preferences without leaving the review interface.
**Checks Tab Always Visible**
The Checks tab is now always visible in the embedded PR review experience, and the merge-status popover properly restores the checks UI so you can always see CI status at a glance.
**Improved @-Mention Search**
The @-mention search in the chat input now uses fuzzy bag-of-words matching, so queries like "setup-dev" will find "setup-devin-dev". Repositories are also ranked first in the dropdown for faster access.
**Slack Improvements**
This release includes several Slack integration improvements: channel names now resolve correctly even for channels you haven't joined, mentions display as styled blue pill badges, unmapped channel messaging is clearer, the Watch channel option appears at the top of the trigger submenu, stale channel lists are fixed, and duplicate webapp-to-Slack thread posts are suppressed.
**Slack Security Hardening**
Enterprise channel isolation for Slack thread-attach has been hardened with runtime authorization that validates channels against enterprise channel preferences, preventing cross-organization channel access.
**Video Recording Download**
You can now download session recording videos directly from the video player controls.
**Miscellaneous Improvements**
This release also includes: file re-upload fix, archived chip now clickable for non-owners with unarchive permission, network config available for finished sessions, test recording viewer close button visibility fix, settings search improvements, back buttons on MCP marketplace and knowledge detail pages, deep mode callout hidden when disabled, repo name truncation so filter stays visible, mobile agent selection single-tap fix, Devin Review file scroll and merge status fixes, skills link fix, Slack support channel in help popover, and wait tool rendered as standalone worklog event.
**Snapshot Build Delete**
You can now delete snapshot builds directly from the build history menu or detail page, with a confirmation dialog to prevent accidental removal. This makes it easier to clean up old or failed builds without navigating away from your environment settings.
**MCP Multiline Environment Variables**
When configuring MCP server connections in the marketplace, you can now enter multiline values for environment variables — such as PEM private keys, JSON service account credentials, and Snowflake key passphrases — without needing to escape or flatten them first.
**Sub-Devin Sidebar Improvements**
Sub-Devin sessions spawned by automations can now be pinned and reordered independently in the sidebar, and they appear expanded by default so you can see their status at a glance without clicking to expand.
**Voice Recording While Devin Is Working**
The microphone button now appears alongside the stop button while Devin is actively working, allowing you to record and send voice follow-ups without waiting for Devin to finish its current task.
**Settings Redesign**
Settings pages have been redesigned with a hub-style layout, improved search across all settings, and a streamlined navigation structure. An announcement dialog introduces the new experience on first visit, and legacy settings URLs automatically redirect to their new locations.
**Archive Active Session Warning**
When you archive a session that is still actively working, a warning dialog now informs you that archiving will put both the session and any child sessions to sleep before proceeding.
**Share Session on Mobile**
A new "Share session" action is available in the sidebar session menu on mobile devices, making it easy to share session links directly from your phone.
**Devin Review Mobile Improvements**
On mobile, tapping "Ask Devin" on a comment now opens the chat panel directly, pull-to-refresh is available on the review scroll container, and bug/flag tap targets have been fixed so they open on the first tap and reveal the associated comment.
**V3 API Enhancements**
The V3 API now supports filtering sessions by repository name via the `repo_names` parameter, filtering by archive status via `is_archived`, specifying `devin_mode` when creating sessions, and setting `folder_id` and `is_enabled` when creating or updating knowledge notes.
**Enterprise Member Invite Acknowledgement**
When inviting new members to an enterprise organization from the admin panel, an acknowledgement modal now confirms the invitation details before it is sent.
**Rename Context to Skills & Rules**
The "Context" section in settings has been renamed to "Skills & Rules" to better describe its purpose of managing Devin's skill definitions and behavioral rules for your organization.
**Blueprint Migration Improvements**
The blueprint migration page now displays per-repo session counts, supports filtering by repository, and shows a completed state when all migrations are finished, making it easier to track progress across large organizations.
**Miscellaneous Improvements**
This release also includes: autofocus on confirmation buttons in archive dialogs, plan artifact button polish, configurable CI status in search results, debounced enterprise snapshot builds, server-side event deduplication to prevent duplicate delivery, pinned sessions remaining visible when automations are hidden in the sidebar, removal of the misleading "Action required" label for Python sessions awaiting instructions, schedule list cap raised from 50 to 200, monitor trigger cleanup when adding new Slack triggers, repo setup status fix for Dynamic Repo Setup organizations, "Approve session" visibility in the sidebar even after all PRs are merged, inline image deduplication by URL, streaming scroll stability fix, high-resolution home screen icon for Android, beta Vite mode build fix, fast mode loading indicator reset on session switch, and sidebar hover cards on expanded non-active sections.
**Devin Review API**
You can now trigger Devin Review programmatically via the REST API. Use `POST /v3/organizations/{org_id}/pr-reviews` with a service user token or PAT to initiate reviews from CI pipelines, scripts, or custom integrations.
**Mermaid Diagram Rendering**
Mermaid code blocks in session messages now render as interactive SVG diagrams with zoom and pan controls, making it easier to explore flowcharts, sequence diagrams, and architecture diagrams that Devin produces.
**Close PRs on Session Archive**
When archiving a Devin session, a dialog now appears where you can optionally close any linked GitHub pull requests, keeping your repository tidy without manual cleanup.
**Per-PR Auto-Review Toggle**
You can now enable or disable automatic Devin Review on a per-PR basis from the PR actions menu, giving you granular control over which pull requests receive automated review without changing your organization-wide settings.
**Sidebar Session Notifications**
The session sidebar now shows persistent status labels, such as "PR created," "Awaiting instructions," or "Approve session," alongside timestamps so you can quickly see what each session needs. Sessions also display read/unread indicators: an orange dot marks sessions with unread updates, and the dot clears once you open the session.
**Service User Permission Management**
Enterprise administrators can now assign the `ManageAccountServiceUsers` permission in custom roles, providing granular control over who can create and manage service users and API keys within the organization.
**Ask Devin in PR Discussions**
The "Ask Devin" button is now available on discussion tab thread comments in Devin Review, making it easy to ask follow-up questions or request changes directly within review conversation threads.
**MCP Secret Scoping**
When adding secrets for custom MCP server connections, you can now choose between personal scope, visible only to you, or organization scope, shared with your team, via a new scope selector in the creation dialog.
**Clickable Diff Stats in Worklog**
Clicking the +N/-M diff stats in worklog group headers now opens a scoped diff tab showing only the file changes from that specific group, making it faster to review exactly what changed at each step.
**Repo Selector Fix**
The select-all checkbox in the repository selector now correctly toggles only the repositories matching your current search filter, rather than selecting all repositories regardless of the filter.
**Slack Tool Use in Worklog**
When Devin interacts with Slack during a session (sending messages, adding reactions, reading channels), these actions now appear in the worklog and progress UI with a dedicated Slack icon and action details.
**Settings Search Improvements**
Settings pages now use a centralized item registry with keyword-driven search, delivering more accurate and comprehensive results when searching across all settings pages.
**Command Palette Search**
Fixed search ordering in the command palette so results rank correctly, and resolved a scroll view issue in the search results window.
**Review Commit Links**
Fixed commit links in Devin Review to point to the correct URL path, and improved status indicators for review progress.
**Default Branch Detection**
Fixed an issue where repository indexing could use the wrong branch as the primary branch instead of the actual GitHub or GitLab default branch, which could affect DeepWiki and search results.
**Stacked Review Permissions**
Enterprise admins can now assign tiered PR Review access levels to their organization members: manual-only review, automatic review on PR creation, or automatic review on every push. This gives administrators granular control over how and when Devin Review engages with pull requests across their organization.
**Skill Slash Commands**
You can now invoke skills by typing `/name` in the prompt input, in addition to the existing @mention syntax. Skills are grouped by repository in the dropdown for easier discovery.
**Auto-Attach Large Paste**
Pasting a large block of text into the prompt input now automatically attaches it as a file instead of filling the text box, preserving any message you've already typed.
**Jira Project Mapping Redesign**
The Jira project mapping modal has been redesigned with a fixed header and scrollable content area, making it easier to configure mappings for organizations with many Jira projects.
**Auto-Fix Includes CI Checks**
The "Auto-fix with Devin" button on pull requests now includes failing CI check names in the prompt alongside review findings, giving Devin more context to resolve issues in a single pass.
**Linear Team Mapping Improvements**
The default organization is now optional when configuring enterprise Linear team mappings, and unmapped teams can be explicitly cleared to "None" instead of requiring a catch-all mapping.
**Session Origin in API**
The v3 API session response now includes an `origin` field indicating how the session was created (webapp, Slack, API, or CLI), making it easier for API consumers to categorize and filter sessions programmatically.
**Deleted Orgs in Enterprise Sessions API**
Enterprise session endpoints now support an `include_deleted_orgs` parameter, giving enterprise admins visibility into sessions from organizations that have been removed.
**Snapshot Revert for Declarative Setup**
Users with the ManageOrgSnapshots permission can now revert an organization from declarative environment configuration back to classic configuration, without needing the broader ManageOrgSettings permission.
**Revamped Blueprint Authoring Experience**
The blueprint editor has been redesigned with a shared layout, per-section play buttons, and a bottom terminal drawer. You can now deep-link directly into a repo's blueprint editor, making it faster to author and test environment setups.
**Enterprise Commit Email Lock**
Enterprise admins can now require all member commits to use the user's primary email. The lock is enforced across snapshot setup, session creation, and PR digest commits, helping enterprises keep commit attribution consistent for audit and compliance.
**PR Auto-Close Removed**
Devin sessions no longer automatically close their pull requests when the session ends. Open PRs now stay open by default so you can manage their lifecycle yourself, with no surprise closures.
**Hybrid Comment Mode in Devin Review**
When Devin Review is opened alongside a Devin session, review comments now default to hybrid mode — anchored to specific lines where possible and falling back to file-level comments otherwise — instead of forcing one or the other.
**Auth-Type Badges in Git Connections**
The git connection filter dropdown on the repository permissions page now shows a PAT, App, or OAuth badge next to each connection, making it easier to disambiguate connections that share a name.
**Slack Trigger Message in Sessions List**
Sessions started from Slack now display the user's triggering Slack message in the sessions list instead of the system prompt, making it easier to identify Slack-launched sessions at a glance.
**PR Digest List Redesign**
The PR digest list has been redesigned with a cleaner layout that matches the sessions list view, making it easier to scan and navigate through pull requests.
**Double-Click File Attachment Picker**
Double-click the plus button in the prompt input to directly open the file attachment picker, skipping the intermediate menu.
**Sensitive Toggle for Secrets**
When Devin requests a secret, you can now toggle whether the value should be masked (sensitive) or visible, instead of it always defaulting to masked.
**Merged Multi-Edits in Progress Tab**
Consecutive file edits to the same file are now merged into a single entry in the progress tab, showing a combined diff from the original to the final version instead of individual per-edit diffs.
**Session Category and Subcategory in API**
The v3 API session response now includes category and subcategory fields. A new category filter is available on session list endpoints, and session exports also include these fields.
**Wide Markdown Tables in Chat**
Markdown tables in Devin's chat messages can now extend beyond the chat column width, preventing cramped multi-column tables from being unreadable.
**SSO Connection Picker**
Organizations with multiple SSO connections for the same email domain now see a picker on the login page instead of being auto-redirected to the first match, letting users choose the correct identity provider.
**MCP OAuth Token Expiry Warnings**
Invalid or expired MCP OAuth tokens are now flagged with warning banners in the integrations UI. A reconnect button lets you re-authorize without navigating away from the page.
**Repository Permissions Decoupled from Git Integrations**
Repository permissions are now managed separately from git integration settings with a view/manage split, giving admins finer-grained control over who can modify repository access versus who can manage the underlying git connection.
**View Consumption Permission**
A new ViewAccountConsumption permission separates read access to usage and consumption data from billing write access, allowing admins to grant visibility without full billing control.
**Attachments in Question Answers**
File attachments are now included when you answer Devin's prompts. Previously, attached files were silently dropped.
**MCP Auth Status Feedback**
MCP authentication requests now show success or error status in both the webapp and Slack after completion, so you know immediately whether authorization succeeded.
**Merge Time Reduction in Review**
The Devin Review page now displays the merge time reduction percentage, showing how much faster PRs are merged with Devin Review enabled.
**PR Digest for Disconnected Users**
The Review page now shows a read-only digest of PRs from your Devin sessions — including open, draft, merged, and closed PRs — even if you haven't connected GitHub yet.
**GitHub Enterprise Server in Review**
GitHub Enterprise Server instances can now be selected in the Review page's Link GitHub flow, and GHES organizations appear in the Devin Review org selector.
**Review Permissions Enforcement**
Repository-level review permissions are now enforced, giving admins control over which repositories Devin Review can access.
**IDP Groups Management**
Enterprise settings now include a management UI for Identity Provider (Okta) groups, letting admins map groups to roles, view group members, and detect user conflicts with existing role assignments.
**Secure Mode Description**
The Secure mode description in enterprise settings has been rewritten to more clearly explain what Secure mode does and when to use it.
**WikiGenerationItem Card**
A new card is now displayed in sessions when the generate\_wiki MCP tool is invoked, giving better visibility into wiki generation progress.
**GHES Links in Integrations**
GitHub Enterprise Server user account links have been moved to the Integrations section of your profile for easier access.
**Minor Bug Fixes and Improvements**
This release also includes a range of smaller fixes and polish: sessions now indicate which are in an "Action Required" state, fixed the playback speed dropdown not opening on click, resolved invisible text in chat inputs on light backgrounds, fixed sidebar glyph flickering, corrected the Context Growth chart x-axis to use continuous datetime, removed checkboxes from combobox options, fixed seat type dropdown clipping, improved seat invitation copy for proper singular/plural phrasing, clarified the "available full seats" invite warning, updated flex seats to show as unlimited on the members page, and hid the Connect GitHub banner for GitLab MRs and during the Review intro overlay.
**Close PR or Convert to Draft in Review UI**
The PR review merge bar now includes options to close a PR or convert it to a draft directly from the review page.
**Inline Session Rename**
Sessions can now be renamed inline directly in the sidebar without opening a dialog.
**Smart Table Column Sizing**
Tables throughout the app now use content-aware column width sizing for better readability.
**Faster Sidebar Session Loading**
The sidebar now lists sessions faster and more reliably, with improved rendering performance and optimistic updates when creating new sessions.
**Datadog Remote MCP Server**
Datadog is now available in the MCP marketplace as a remote MCP server with OAuth-based authentication, so Devin can query your Datadog dashboards and metrics directly.
**ACP Summarizer**
Agent Client Protocol now supports a summarizer method for generating session summaries programmatically, useful for integrations that need a concise recap of what Devin accomplished.
**Granola MCP Server**
The Granola MCP server is now promoted out of beta, letting Devin access your Granola meeting notes during a session.
**Pagination and Search for Review Settings**
Enterprise review settings now support pagination and search for repository and user lists, making it easier to manage large configurations.
**Minor Bug Fixes and Improvements**
This release also includes a range of smaller fixes and polish, including a proper 404 error page for invalid URLs, frontend performance optimizations, and assorted stability improvements across the webapp.
**Theme Selector Generally Available**
The theme selector is now generally available, with system theme as the default so Devin automatically matches your OS light or dark mode.
**Wiki Effort Level Descriptions**
When choosing a DeepWiki effort level, each option now shows its expected ACU range so you can pick the right trade-off between cost and depth with confidence.
**DeepWiki Cost Breakdown Modal**
The DeepWiki cost breakdown modal is back, giving you an ACU-level view of where a wiki generation spent its budget.
**Cancel In-Progress Snapshot Builds**
You can now cancel an in-progress snapshot build directly from the snapshot list without waiting for it to finish or fail.
**Snapshot Blueprint Ordering**
Snapshot detail rails and repository-level blueprints now respect your configured blueprint ordering, so the list you see matches the order you set.
**Scheduled Session Failure Email Rate Limiting**
Failure email notifications for scheduled sessions are now rate limited, so a scheduled run hitting the same problem repeatedly will no longer flood your inbox.
**Knowledge Search Auto-Expand**
When you search your knowledge base, any folder containing a matching note now automatically expands so you can see the result in context without hunting for it.
**Profile Integrations Filter**
Your profile page now only shows integrations that are actually connected for your organization, cutting the clutter from services you do not use.
**Browser Tool Parity Improvements**
Devin's browser tool now handles native browser dialogs, intercepts file chooser prompts, respects navigation guards, and restores focus correctly, bringing its behavior much closer to a real user browsing the web.
**Amplitude MCP Server**
Amplitude is now available in the MCP marketplace, so Devin can pull product analytics directly into a session without a custom integration.
**One-Click MCP OAuth Install**
Installing an MCP server that uses OAuth now returns the authorization URL directly, skipping an extra click and getting you connected faster.
**Personal MCP Servers**
You can now connect personal MCP servers, which enable Devin to use MCPs with authorization provided by an individual user rather than shared across an organization.
**Richer ACP Methods and @-Mentions**
Agent Client Protocol now carries @-mentions as structured resource blocks and adds new methods for listing repositories, saving secrets, archiving sessions, approving deploys, and attaching to the interactive browser, giving ACP clients a much richer surface area to work with.
**Devin CLI Polish**
The Devin CLI now preserves streamed shell output alongside exit codes, supports a `/resume` alias, renders plan-mode exits more clearly, and uses focus pings to keep a session from sleeping while you are actively watching it.
**Reconnecting VNC Screen**
The interactive browser now shows a reconnecting screen while its VNC stream is recovering, so you get clear feedback instead of a frozen view when the connection briefly drops.
**Unlink GitHub Enterprise Server OAuth**
You can now unlink a GitHub Enterprise Server OAuth connection from your account, making it easy to rotate credentials or clean up stale integrations.
**Total ACUs Column in Usage Table**
The Users table in Usage analytics now includes a Total ACUs column, so enterprise admins can rank and compare per-user consumption at a glance.
**Bulk Repository Secrets Import**
Enterprise admins can now import multiple repository secrets at once through a new bulk import flow on the repository configuration page, replacing the old one-at-a-time workflow.
**Minor Bug Fixes and Improvements**
This release also includes a range of smaller fixes and polish across the webapp, including repository branch dropdowns that now size correctly, the DeepWiki section hidden when no branches are indexed, a fix for Linear OAuth cancellations returning errors, correct starting numbers on streamed ordered lists, a copy-message button that now copies only the selected message, and assorted other stability and layout improvements.
**Auto-merge from Devin Review**
You can now enable or disable GitHub auto-merge directly from the Devin Review merge button, so approved pull requests land as soon as checks pass without an extra trip to GitHub.
**Enterprise Review Consumption by Repository**
The Reviews tab on the Enterprise Consumption page now groups Devin Review spend by repository with current-cycle vs previous-cycle columns, a search box, and CSV export, making it much easier for enterprise admins to see where their review spend is going.
**Devin Review Breakdown in v3 Consumption API**
The v3 consumption API now reports Devin Review as its own line item in the product breakdown alongside sessions and indexing.
**Categorization and Subcategories**
Session categorization and subcategories are now generally available for every workspace, giving you a consistent way to organize and filter your Devin sessions.
**Pinned Organizations Sync Across Devices**
Your pinned organizations are now stored server-side and follow you across every device and browser you sign in from.
**Session Message Permalinks**
Every message in a session now has its own shareable link, so you can point teammates directly at the exact moment you want them to see.
**Larger Attachment Uploads**
Session attachments now support files up to 75 MB, up from the previous 20 MB limit.
**Higher-Quality Wiki v2**
Wiki v2 now uses stronger reasoning, subagents, and agentic page writers to produce noticeably better documentation, and shows the ACU cost of the last generation so you can see exactly what each refresh costs.
**Guardrails V3**
Our new pattern-based guardrail prompts significantly reduce false positives while keeping the same level of protection.
**Ask Sub-mode Renamed to Q\&A**
The Ask sub-mode is now simply labeled "Q\&A" to better reflect what it does.
**Consolidated Session Header Menu**
Session header links are now grouped into a single hyperlink menu for a cleaner, less crowded header.
**Faster Syntax Highlighting**
Code blocks across the app now render with an incremental, worker-based syntax highlighter for noticeably faster and smoother highlighting on large files.
**Scroll Restoration**
Navigating back through the app now restores your previous scroll position so you land where you left off.
**Japanese Localization Refresh**
Japanese localization strings have been refreshed across the webapp.
**MCP Marketplace Upgrades**
The MCP marketplace now includes a Recommended section, smarter Figma discovery, and a shared interactive OAuth flow that shows connection status and errors directly in chat as you install servers.
**MCP Audit Logs**
Enterprise audit logs now cover MCP server updates and secret link and unlink events for better visibility into integration changes.
**Session ACU Hard Caps**
Enterprises can now set a hard upper limit on total ACUs per session, with an acknowledgement modal and real-time validation so users always know when a session is approaching the cap.
**Cerebras Now Enterprise-Ready**
Cerebras is now available as an enterprise-ready inference provider for organizations that want to use it for their Devin workloads.
**US Privacy Controls**
Devin now honors Global Privacy Control signals and supports CCPA and CPRA opt-out requests for customers in the United States.
**Refreshed Settings Layout**
Insights, identity provider, and several other enterprise settings pages have been migrated to the new settings layout and design system for a more consistent look and faster navigation.
**Enterprise Secrets Table Polish**
The enterprise secrets table now includes an environment variable column and a build-only toggle, with a simplified layout that removes the Name column and type selector.
**Minor Bug Fixes and Improvements**
Numerous smaller fixes and polish, including sidebar collapse state persistence, sidebar pull requests loading without a GitHub connection, better multi-PR session isolation, deduplicated Slack file forwarding, quota reset on plan upgrade, billing cycle short-month correction, snapshots sorted alphabetically, an auto-organize tooltip explaining when it is disabled, and the Category beta label and Review beta badge retired for paying organizations.
**Classic Environment Setup Deprecation**
Classic environment setup is being deprecated on June 30, 2026, when all organizations move to declarative configuration (blueprints). Your classic machine configuration stays available as a read-only reference until July 31, 2026. See [Environment configuration](/onboard-devin/environment).
**Enterprise-Scoped Secrets**
Enterprise admins can manage secrets at the enterprise level, automatically shared across all organizations. Initially only available to users of declarative environment configuration.
**Enterprise ACU Visibility Control**
Enterprise admins can control whether users see ACU usage info.
**Enterprise MCP Registry Enforcement**
Enterprise admins can enforce an MCP server allowlist across their organization.
**Enterprise Build Pinning**
Enterprise admins can pin specific Devin builds and roll back to previous versions. Initially only available to users of declarative environment configuration.
**Devin Review Auto-Fix**
When Devin Review detects bugs in a PR, a new "Auto-fix with Devin" button launches a session to fix them in one click.
**PR Review Chat CI Tools**
Check CI status and view CI job logs directly within the PR review chat.
**Pin Sessions**
Pin important sessions from the three-dot menu for quick access.
**Organization Terminology**
All "team" references updated to "organization" across the product. No functional change.
**Improved Questions UI**
Navigation between questions, inline "Something else" input, cleaner design.
**Auto-Skip Pending Questions**
Devin auto-skips pending questions when you send a new message.
**Cleaner File Paths**
Relative paths with structured format instead of full absolute paths.
**PR Review Polish**
Sticky tabs, bug navigation, copy buttons, chat CTA at end of diffs, empty state for PRs without descriptions.
**Structured Output for Child Sessions**
Child sessions can return structured JSON via schema for automated workflows.
**Smarter Codebase Search**
Recency-based repository ordering for faster, more accurate results.
**/new Slash Command**
Alias for /clear to start a fresh conversation.
**Azure DevOps Service Principal**
Connect Azure DevOps via service principal instead of personal OAuth.
**Linear Assignee Filter**
Rich picker for Linear assignee filtering in automations.
**Linear Token Refresh**
Linear connections now auto-refresh OAuth tokens, preventing disconnection on expiry.
**Minor Bug Fixes and Improvements**
GitLab PAT rotation fix, responsive mobile layouts, startup command display improvements, build log scroll-to-bottom, Ctrl+O expand hint, shell security improvements, automations UI fixes.
**PR Resuming**
Devin can now take over and work on existing pull requests that weren't created in the current session, enabling continuation of work across sessions.
**Devin Review Improvements**
Added a "lines left to review" counter in the PR review diff viewer, and significantly faster page load times via parallel queries.
**Streaming Terminals**
Terminal output in the session view now streams in real time.
**Connected Accounts Pagination**
GitHub and GitLab connected accounts pages now support pagination and search for organizations with many connections.
**GHES Improvements**
Support for org-level GitHub App registration on GitHub Enterprise Server, with pre-filled app name in the manifest flow.
**Settings Page Redesign**
Multiple settings pages (Schedules, Playbooks, Knowledge, Secrets) have been redesigned with a new unified layout, along with consolidated dialog styles across the product.
**Sticky Sidebar Headers**
Sidebar section headers now stick to the top while scrolling for easier navigation.
**Light Mode Polish**
Multiple fixes for theme-aware colors across modals, dialogs, and components.
**Add or Create Team**
New button in the account dropdown to create a team without going through the GitHub integration flow.
**Auto-open Agents Tab**
The Agents tab auto-opens when child sessions are detected.
**Tab Title Simplification**
Browser tab title simplified to "Devin" with contextual page titles.
**Slack Thread Permissions**
Users without Devin accounts are now blocked from messaging in Devin Slack threads.
**Improved PR Comment Formatting**
Devin's PR comments now include line info and outside-diff context.
**IME Composition Fix**
Fixed an issue where pressing Enter during IME composition (e.g., Japanese input) in Safari would prematurely submit text.
**Ignore Comment Info**
More helpful information shown when Devin Review comments are ignored.
**Environment Setup Cleanup**
Clarified environment description copy and removed redundant buttons.
**Bash Syntax Highlighting**
Terminal output now has syntax highlighting for bash commands.
**Scheduled Session Pill**
Visual indicator for scheduled sessions in the sessions list.
**Minor bug fixes and improvements**
Various bug fixes, performance improvements, and visual polish across the platform.
**Preview Agent Toggle**
A new "Preview upcoming features" toggle is available in the agent selector, enabling streaming thoughts and faster execution. Stability may be limited as these features are still in development.
**Inline File Previews**
HTML, PDF, and SVG attachments can now be securely rendered inline in the session sidebar, with a code/render toggle and download button in the file toolbar.
**Focus Mode**
A new focus mode hides the sidebar, header, and right panel for a distraction-free chat experience. Access it from the session menu or with the keyboard shortcut Cmd+Shift+F.
**Agents Tab for Child Sessions**
A new "Agents" tab automatically appears when a session creates child sessions, showing their status, todos, and PRs in one place.
**Test Recording Viewer**
Devin's test recordings now display as rich cards with pass/fail summaries, playback speed controls, and loop functionality.
**Jira Integration Enhancements**
Jira now supports direct session creation from issues, service account connections, and per-project trigger options for controlling when Devin is activated.
**Redesigned Integration Settings**
The Linear, Jira, and Slack integration settings pages have been redesigned with cleaner layouts for team mapping, playbook management, bot allowlists, and automation rules.
**Minor bug fixes and improvements**
Various bug fixes and performance improvements across the platform.
**Light Mode (Beta)**
Devin now supports a light mode theme. You can switch between dark, light, and system themes from your profile settings.
**Streaming Shell Output in Worklog**
Background shell process output now streams inline within worklog items, so you can monitor long-running processes without switching to the terminal.
**Cookie JSON Builder for Secrets**
A new tabbed interface for cookie secrets lets users paste raw JSON (auto-encoded to base64) with validation, parsed previews, and expiration warnings.
**Org-Level Metrics API**
New organization-scoped API endpoints for metrics and consumption data.
**Session Insights UI Redesign**
The session insights modal has been redesigned with a refreshed layout, improved empty states, and updated copy.
**Secrets on Initial Prompt**
Users can now attach secrets when creating a new session from the home page, matching existing functionality for follow-up messages.
**Devin Reviews Analytics**
A new Devin Reviews section has been added to the usage analytics page showing review metrics.
**Minor bug fixes and improvements**
Various bug fixes and performance improvements across the platform.
**Devin Manages Devins**
Devin can now orchestrate Devins and manage your Devin setup directly from any session. This will replace the current Advanced Devin features.
Devin can delegate to a team of managed Devins that work in parallel. Each managed Devin is a full Devin with its own isolated virtual machine. The main Devin session acts as a coordinator — scoping the work, monitoring progress, resolving conflicts, and compiling the results.
New capabilities include:
* Session management – Create child sessions with structured output schemas and playbooks. Search and filter past sessions by tags, playbook, origin, or time range. Analyze past sessions with full search across shell, file, browser, git, and MCP activity.
* Knowledge management – Create, update, delete, and organize knowledge notes into folders. Review knowledge suggestions.
* Playbook management – Create, edit, and delete playbooks.
* Schedule management – Create and manage scheduled sessions including recurring or one-time runs, agent selection, and notification preferences.
**Redesigned Integration Pages**
The integration settings pages have been redesigned with a new layout including connection cards, support sections, and pagination.
**Improved Playbook Page**
The playbooks page now shows a table layout. Each playbook page now shows session count, unique users, and merged PRs per playbook, with a weekly activity chart. Playbooks now include a version history.
**Parent/Child Session Grouping**
Parent and child sessions are now grouped together in the sidebar, so child sessions stay nested under their parent regardless of sorting or filtering.
**Minor bug fixes and improvements**
Various bug fixes and performance improvements across the platform.
**On-Demand Session Insights**
Session insights are now generated on demand rather than automatically. You can trigger analysis from the Session Insights button in the UI or programmatically via the new [generate insights API endpoint](/api-reference/v3/sessions/post-organizations-session-insights-generate).
**New Session Inputs**
* An inline voice recording button is now available for hands-free messaging.
* Devin sessions can be @ mentioned to reference them directly in another session.
**Session List Improvements**
* Important sessions can be pinned to the top of the sidebar for quick access.
* A new sidebar filter hides scheduled sessions from the session list.
**Structured Output Modal**
The structured output from sessions created with the API with this parameter set can now be viewed and downloaded from the "Structured output" option in the session menu.
**Markdown Preview**
Markdown files can now be natively displayed in the right panel.
**Datadog MCP Integration**
Datadog is now available as an official integration in the MCP marketplace.
**Default Branch Management**
Users can set and manage the default branch for repository indexing from the repositories management page.
**Schedule: Run as User**
Schedules can now be reassigned to run as the current user via a "Run as me" button in the schedule detail view, also available via the v3 API.
**IdP Groups in Enterprise Settings**
The enterprise members table now shows IdP group memberships for each user.
**Minor bug fixes and improvements**
Various bug fixes, performance improvements, and visual polish across the platform.
**Install Devin as an App**
Devin can now be installed as a Progressive Web App on desktop and mobile. On Chrome or Edge, open app.devin.ai and click the install icon in the address bar (or Menu → Install Devin); on iOS Safari, tap Share → Add to Home Screen. Once installed, Devin links open directly in the app.
**Session Status in Browser Tab**
The browser tab favicon now shows a colored status dot on session pages (green when Devin is working, orange when it's waiting for you) so you can spot sessions that need attention without switching tabs.
**Minor bug fixes and improvements**
Various bug fixes, performance improvements, and visual polish across the platform.
**AskDevin Upgrade**
Expanded to support Ask and Plan modes. Now has more advanced code search capabilities which produce more detailed and accurate answers. The status of Devin sessions created from AskDevin can now be seen in the conversation.
**Devin Review: GitHub Commit Status Checks**
Status checks now displayed directly on pull request commits, giving visibility into review progress without leaving GitHub. The status links to the full Devin Review analysis.
To enable this, the Devin GitHub App will request the Commit Statuses and Checks permissions. If these permissions are not granted, all existing functionality is unaffected.
**Repository Selection for Schedules**
Schedules can now be configured with specific repositories that the session will be run with each time the schedule executes.
**Devin 2.2 Launch**
Devin 2.2 is the culmination of hundreds of improvements both big and small over the last few weeks including:
* 3x faster startup time to immediately see Devin's output and build trust that it's on the right track
* A new UI that connects every step of the dev lifecycle: start sessions from anywhere, review agent output directly in Devin, and jump back into sessions from code review.
* Smoother and faster Slack and Linear integrations to start sessions without having to switch context
See past release notes for the full list of the improvements.
**Full Desktop Testing**
Devin now supports end-to-end testing using computer use and can test any desktop app that can run on Linux. Devin will request to QA its PR, if you approve it, it will run your app, use its desktop to click around, and send you an edited recording of the testing for your review.
Existing users can enable Desktop mode in [Settings > Customization](https://app.devin.ai/customization).
**Devin v3 API Officially Released**
The v3 API is coming out of beta and is now the primary API for all Devin functionality. The new API provides all of the legacy API functionality and additionally provides role-based access control, session attribution, and new capabilities.
The legacy APIs (v1 and v2) will be deprecated in the future. The exact date will be announced in the product and in release notes. We commit to providing at least 30 days notice. During the deprecation period, the legacy APIs will continue to work but all new features will only be available in the v3 API.
**Sessions List Redesign**
The sessions list page has been redesigned with an updated layout featuring inline PR previews, message snippets, and status indicators. Sessions can now also be sorted by creation date.
**Merge Conflict Detection**
Devin will automatically notify users when a PR created in a Devin session has merge conflicts. Available on GitHub.com only.
**New Devin Scheduling Options**
Scheduled Devins can now be created as a one-time scheduled event, and existing schedules can be triggered on demand with the "Run now" button.
**Devin Review for GitHub Enterprise Server**
Devin Review now supports GitHub Enterprise Server (GHES) repositories. You can view PR diffs, run analysis, and use the Devin Review chat agent to propose and apply code changes. Some interactions with GitHub such as posting comments, submitting reviews, and merging are not yet supported on GHES.
**Repo Selector Enhancements**
The repository selector now features an "Only" button to quickly isolate a single repository and displays setup and indexed repo counts.
**Session Messages API**
A new `GET /messages` endpoint allows programmatic access to session message history.
**Minor bug fixes and improvements**
Various bug fixes and performance improvements across the platform.
**Visual Refresh and Polish**
The overall design has been improved and polished across the product. Some button locations have been minorly adjusted, but these changes do not impact the product functionality.
**Devin Fast Mode**
A new "Fast Mode" option is now available in the agent picker, delivering \~2x faster responses with the same intelligence at 4x ACU per session.
**Devin Review: Batch Comments**
When replying to PR review threads, you can now check "Start a review" to batch multiple review comments before submitting them all at once.
**Devin Review: Code Changes from Chat**
The Devin Review chat agent can now propose code edits directly in the conversation. You can review the suggested changes, then apply them as a commit to the PR branch without leaving Devin Review.
**Secure Mode for All Organizations**
Secure mode is now available for non-enterprise organizations. When enabled, Devin loses native internet deployment capabilities. You can find this setting under "Security settings" on the Customization page.
**Skills Support**
Devin now recognizes and uses skills defined in your codebase. Skills provide reusable instructions that Devin can activate, search, and invoke during sessions to follow your team's preferred workflows.
**Settings Search**
A search bar has been added to the settings sidebar, making it easy to quickly find any settings page by name or keyword.
**Minor bug fixes and improvements**
Various bug fixes and performance improvements across the platform.
**Schedule from the Input Box**
You can now quickly create a scheduled Devin session directly from the input box. Use the "Schedule Devin" option in the context menu or switch to the "Create schedule" tab in Advanced mode to set up recurring sessions without leaving the home page.
**Enterprise Organization Selection**
The enterprise landing page has been redesigned with a cleaner organization list, member counts, and sorting options for easier navigation across your enterprise.
**Devin Review: Auto-Review Settings**
Auto-review configuration is now accessible as a settings popover directly in the PR header, making it faster to enable or disable auto-reviews per repository.
**Devin Review: Hide Comment Highlights**
A new setting in the code diff viewer lets you hide comment highlight boxes for a cleaner reading experience when reviewing code.
**Git Permissions Update**
Removed the ability to index repos in the primary organization for enterprises.
**Minor bug fixes and improvements**
Various bug fixes and performance improvements across the platform.
***
## All Release Notes
* [2026 Release Notes](/release-notes/2026)
* [2025 Release Notes](/release-notes/2025)
* [2024 Release Notes](/release-notes/2024)
# Advanced Capabilities
Source: https://docs.devinenterprise.com/work-with-devin/advanced-capabilities
Devin can orchestrate managed sessions, analyze past work, create playbooks, and manage your knowledge base
**These capabilities are available in every Devin session — just ask.** You can also access prompt templates for each capability from the **Explore Advanced Capabilities** page on the Devin home page.
Devin goes beyond writing code. It can break large tasks into parallel workstreams, learn from past sessions, build reusable playbooks, and keep your organization's knowledge base current — all from any session.
## What Devin can do for you
* **Orchestrate managed Devins in parallel**: Break down a large task and delegate pieces to a team of managed Devin sessions, each running in its own isolated VM
* **Analyze session outcomes**: Understand why a session succeeded or failed, identify patterns, and extract learnings
* **Create and improve playbooks**: Turn successful sessions into reusable playbooks, or refine existing ones based on feedback
* **Manage knowledge**: Deduplicate, consolidate, or create new knowledge entries from your codebase
* **Manage schedules**: Set up recurring or one-time automated Devin sessions
These features work in any Devin session — just describe what you need. The **Explore Advanced Capabilities** page on the Devin home page provides ready-made prompt templates for common workflows.
## Managed Devins
Devin can break down large tasks and delegate them to a team of managed Devins working in parallel, each running in its own isolated VM. The coordinator session scopes the work, monitors progress, resolves conflicts, and compiles results.
Devin automatically breaks down large tasks and delegates to managed Devins when it makes sense. You can also explicitly ask Devin to parallelize work — for example, "spin up a managed Devin for each module" or "run this playbook across all services in parallel." Either way, Devin acts as the coordinator: scoping work, monitoring progress, resolving conflicts, and compiling results.
This is the most powerful way to tackle work that spans many files, modules, or repositories — migrations, bulk test coverage, parallel research, and more.
**What the coordinator can do:**
* **Spin up managed Devins** — launch child sessions with specific prompts, playbooks, tags, and ACU limits
* **Message child sessions** — send follow-up instructions or clarifications to running sessions
* **Monitor ACU consumption** — track how much compute each child session is using
* **Put child sessions to sleep or terminate them** — pause or stop sessions that are stuck or no longer needed
* **Schedule messages to itself** — set reminders to check back on long-running child sessions
**Example: Parallelize a 50-file migration**
Ask Devin to analyze your codebase, group files into independent work packages, and launch one session per package — all running simultaneously:
```
Analyze our codebase for all files using the legacy REST client.
Group them into independent work packages that won't conflict,
then start a parallel Devin session for each package to migrate
to the new GraphQL client. Use the "REST to GraphQL Migration"
playbook for each session.
```
See [Migrate 50 Files from REST to GraphQL](/use-cases/gallery/parallelize-migration) for a full walkthrough.
**Example: Run the same task across multiple modules**
Launch multiple Devin sessions at once for repetitive tasks — each session runs independently on its own machine:
```
Run the test coverage report, find the 8 modules below 50%
coverage, and start a parallel Devin session for each module
using our test-writing playbook. Open a separate PR for each.
```
Devin analyzes your request and proposes the sessions for your approval before launching them. See [Batch Test Coverage](/use-cases/gallery/batch-test-coverage) for a full walkthrough.
## Analyzing sessions
Have Devin examine one or more past sessions to understand what happened and why. This is useful for:
* Understanding why a session didn't complete as expected
* Identifying what worked well in a successful session
* Extracting patterns and insights from multiple sessions
To analyze a session, share the session link and describe what you want to learn:
```
This session used 42 ACUs to add pagination to GET /api/users.
I expected ~12. Break down where Devin spent the most time,
what dead ends it tried, and give me a revised prompt that
would avoid these issues.
```
Devin examines the session history, identifies key events, and provides actionable insights.
## Creating and improving playbooks
Turn a successful session into a reusable playbook, or refine an existing one based on real-world feedback.
**Creating a playbook from a session:**
Share one or more session links and describe the playbook you want. Devin analyzes the sessions and produces a structured playbook with procedures, specifications, and advice.
```
This session diagnosed and fixed a memory leak in our payments
service. Create a reusable hotfix playbook for memory-leak
incidents that any on-call engineer can attach to a new session.
```
**Improving an existing playbook:**
Reference the playbook and share sessions where it fell short. Devin compares successes and failures to propose targeted improvements.
```
Our !db-migration playbook keeps failing on foreign key
constraints. Here are 4 recent sessions — analyze the failures,
compare them to the successes, and update the playbook to handle
FK dependencies.
```
## Managing knowledge
Maintain and improve your organization's knowledge base:
* Find and merge duplicate knowledge entries
* Resolve conflicting guidance
* Create new knowledge from codebase patterns
```
Review all knowledge entries and identify duplicates or highly
similar entries. For each set of duplicates, propose a
consolidated version.
```
## Managing schedules
Set up recurring or one-time scheduled Devin sessions for automated workflows like nightly test runs, weekly knowledge maintenance, or daily health checks.
```
Create a schedule that runs every Monday at 8 AM to review
pending knowledge suggestions, deduplicate entries, and resolve
conflicting guidance.
```
See [Scheduled Sessions](/product-guides/scheduled-sessions) for more details.
## Best practices
### Analyzing sessions effectively
When analyzing sessions, be specific about what you want to learn. Instead of asking "What happened?", try:
* "Why did Devin choose this approach instead of the alternative?"
* "What caused the test failures in this session?"
* "What patterns can we extract to create a playbook?"
### Creating useful playbooks
When creating playbooks from sessions:
* Provide multiple successful sessions if available to help Devin identify common patterns
* Describe the intended audience and use case for the playbook
* Specify any constraints or requirements that should be included
### Managing knowledge at scale
For large knowledge bases:
* Start with deduplication to reduce noise
* Then resolve conflicts to ensure consistency
* Finally, fill gaps by creating knowledge from codebase analysis
## Using these features via the Devin MCP
All of the capabilities described above — and more — are available through the [Devin MCP server](/work-with-devin/devin-mcp). Any Devin session or MCP-compatible AI agent can access them directly.
### Session management
Create one or more Devin sessions programmatically, each with its own prompt, playbook, tags, and ACU limit. Search and filter across your organization's sessions by tags, playbook, origin, user, or time range. Inspect any session's full event timeline — list event summaries, fetch detailed event contents, or search across events by text. Send messages to running sessions, terminate or archive them, and manage session tags. After launching parallel sessions, wait for all of them to finish in a single call instead of polling individually.
### Playbook management
List, create, update, and delete playbooks. Attach automation macros to playbooks for trigger-based workflows. Use this to build playbooks from scratch, iterate on existing ones, or clean up unused playbooks.
### Knowledge management
Full control over your organization's knowledge base: create, read, update, and delete knowledge notes. Browse the folder structure, filter notes by repo or folder, and search across note names, triggers, and content. Review, view, and dismiss pending knowledge suggestions that Devin generates from sessions.
### Schedule management
Create and manage scheduled Devin sessions — both recurring (via cron expressions) and one-time. Update schedule frequency, toggle schedules on and off, choose notification preferences, and select which agent to run. This lets you set up automated workflows like nightly test runs, weekly knowledge maintenance, or daily health checks.
### Integration management
View all native integrations (such as GitHub, Jira, and Slack) and MCP servers configured for your organization. Check which integrations are installed, find setup URLs for ones that aren't, and get configuration links for ones that are — letting Devin help you manage your integration landscape.
### Repository documentation
Query and search documentation for any GitHub repository your account has access to. Get a structured list of documentation topics, read full wiki contents, or ask natural-language questions and receive AI-powered, context-grounded answers. List all repositories available to your Devin account.
See the [Devin MCP documentation](/work-with-devin/devin-mcp) for setup instructions and the full tool reference.
## Permissions
These advanced capabilities require the `UseDevinExpert` permission, which is included in the default `org_member` and `org_admin` roles, so all organization members have access by default.
If you need to restrict access, you can create a custom role without this permission and assign it to specific users.
# Ask Devin
Source: https://docs.devinenterprise.com/work-with-devin/ask-devin
Use Ask Devin to ask questions about your codebase, plan tasks, and generate high-context sessions
## Overview
**Ask Devin** is your AI assistant's window into your codebase. Once you've added a repository to Devin, it is automatically indexed so Devin can understand and reason about your code. With Ask Devin, you can:
* **Ask questions** about how your code works, explore architecture, dependencies, and key functions. Ask Devin uses advanced code search capabilities to produce detailed, accurate, and well-cited answers grounded in your codebase.
* **Plan tasks** by working with Devin to scope and plan implementation before writing code. Devin generates a context-rich prompt based on what it learns, ready to hand off to an Agent session.
Whether you're onboarding to a new repo, planning a feature, or exploring unfamiliar parts of the codebase, Ask Devin gives you a fast and reliable way to work with your code using natural language.
When you start a Devin session from Ask Devin, the **status of that session is visible directly in the Ask Devin conversation**, so you can track progress without switching context.
## Recommended Workflow
To get the most out of Devin, follow this workflow:
### 1. Index Your Repository
After connecting your GitHub, GitLab, or other source code provider, [index your repository](/onboard-devin/index-repo). Devin automatically indexes your codebase in the background, enabling powerful tools like **DeepWiki** and **Ask Devin**.
Index any repo after git permissions have been granted
### 2. Use Ask Devin to Explore and Plan
Go to [Ask Devin](https://app.devin.ai/search) to:
* Ask technical questions about your code and get detailed, accurately cited answers powered by advanced code search
* Plan and scope projects, break down tasks, and generate context-aware prompts for Agent sessions
Ask Devin any question about your repo, or use Plan mode to scope tasks Devin answers in natural language with code citations, always grounded in your codebase
### 3. Start a Session from Ask Devin
Once you have used Ask Devin to understand the code and clarify your goal, you can start a session directly from the conversation. This is the best way to initiate work with Devin because:
* Devin starts with clear context from your Ask Devin conversation
* The prompt is automatically tailored to your task and codebase
* You are more likely to get successful, relevant results
* The **session status is displayed directly in the Ask Devin conversation**, letting you monitor progress without leaving the page
Devin writes a context-rich prompt from your sessionTrack session progress in the conversationView completed results and PRs
# Computer Use
Source: https://docs.devinenterprise.com/work-with-devin/computer-use
How Devin uses a full desktop environment to interact with GUIs, test applications, and visually verify changes
Devin has access to a full desktop environment — not just a browser. It can move the mouse, click on UI elements, type on the keyboard, take screenshots, and interact with any application that runs on the desktop. This capability is called **Computer Use**, and it allows Devin to test and interact with your software the same way a human would.
Computer Use works on **Linux** (the default session platform) and **Windows** sessions, and on [Outposts](/cloud/outposts/overview) machines — including **macOS** — that have a graphical desktop. See [Supported platforms](#supported-platforms) for details.
## What Is Computer Use?
Computer Use gives Devin direct access to a graphical desktop environment with a mouse and keyboard. This goes beyond browser automation — Devin can interact with **any application** that renders on screen, including:
* **Web applications** in Chrome (clicking buttons, filling forms, navigating pages)
* **Desktop applications** that run on the session's platform (Linux or Windows), including Electron apps, IDEs, and platform-native GUIs
* **Terminal-based UIs** (TUI programs, interactive CLIs)
* **Any visual interface** that can be displayed on the desktop
Devin sees the screen as a 1024×768 pixel display and can perform actions like clicking, typing, scrolling, dragging, and taking screenshots — just like a human sitting at the computer.
## Supported Platforms
| Platform | Computer Use support |
| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Linux (default) | Supported — sessions run a full Linux desktop environment |
| Windows | Supported — sessions on [Windows environments](/onboard-devin/environment/windows-support) run a full Windows desktop environment |
| Outposts (Linux) | Supported when the machine has a running X session (`DISPLAY` set for the worker, e.g. a desktop session or Xvfb). Headless machines get a clear error instead. See [Computer Use on Outposts](#computer-use-on-outposts). |
| Outposts (macOS) | Supported — Devin uses the machine's existing desktop session. Screenshots require the **Screen Recording** permission; mouse/keyboard actions additionally require the **Accessibility** permission. See [Computer Use on Outposts](#computer-use-on-outposts). |
| macOS (Devin Cloud) | Not available — macOS sessions run only on [Outposts](/cloud/outposts/overview) |
The Computer Use experience is the same on all platforms: Devin uses the mouse and keyboard, takes screenshots, runs Chrome for web apps, and can record its testing sessions. On Windows, Devin can additionally test Windows-native desktop applications (e.g. WPF, WinForms, and other apps that only run on Windows). To run sessions on Windows, configure a Windows blueprint as described in [Windows support](/onboard-devin/environment/windows-support).
## How to Enable It
Computer Use is controlled by the **Enable desktop mode** toggle in your organization's customization options.
1. Go to [**Settings > Customization**](https://app.devin.ai/customization)
2. Under the **Browser interaction** section, toggle **Enable desktop mode** on
3. Devin will now use its desktop environment during sessions
Desktop mode is available on all plans. Only organization admins can change this setting.
## When Computer Use Runs
Once Desktop mode is enabled, Computer Use is available in every session. There are three ways it gets used:
### After creating a PR
When Devin creates a PR, it offers a **Test the app** button. Clicking it triggers the full [testing workflow](/work-with-devin/testing-and-recordings) — Devin starts your app, uses Computer Use to interact with the desktop, tests the changes, and sends you a recording.
### On request during a session
You can ask Devin to test at any point during a session — no special syntax needed, just natural language. For example:
* "Test the changes you just made and send me a recording"
* "Open the app in the browser and verify the login page works"
* "Launch the desktop app and check that the new menu item appears"
### Autonomously when appropriate
Devin decides on its own when desktop interaction is the right tool for the job. If a task involves clicking UI elements, navigating an app, filling out forms, or visually verifying something, Devin will use Computer Use without being explicitly asked. You don't need to tell Devin *how* to interact with the screen — just tell it *what* to accomplish.
## What Devin Can Do with Computer Use
### Test web applications end-to-end
Devin can start your app locally, open it in Chrome, and click through entire user flows — login, navigation, form submission, checkout — verifying that everything works as expected.
### Test desktop applications
Any application that runs on Devin's session platform can be tested. On Linux sessions this includes Electron apps, Java Swing/AWT applications, GTK/Qt apps, and more. On [Windows sessions](/onboard-devin/environment/windows-support), Devin can also test Windows-native applications such as WPF and WinForms apps. Devin launches the app, interacts with its GUI, and verifies behavior.
### Visual verification
Devin can take screenshots at specific points during testing to verify that layouts, styling, and UI elements look correct. It can compare what it sees on screen against expected behavior and flag visual issues.
### Interact with complex UI flows
Some testing scenarios require multi-step GUI interactions that go beyond simple API calls or browser automation — things like drag-and-drop, context menus, keyboard shortcuts, or navigating between multiple windows. Computer Use handles all of these.
### Record testing sessions
Devin can record its screen while testing, annotating key moments in the video. The recording is then processed and sent to you so you can watch Devin interact with your app and confirm the changes work. See [Testing & Video Recordings](/work-with-devin/testing-and-recordings) for full details on the recording workflow.
## How Computer Use Works
When Devin uses Computer Use during a session, it follows this process:
1. **Takes a screenshot** of the current screen to understand what's visible
2. **Identifies interactive elements** — buttons, text fields, menus, links — and decides what to interact with
3. **Performs an action** — clicks, types, scrolls, or uses keyboard shortcuts
4. **Waits and observes** — takes another screenshot to see the result of the action
5. **Repeats** until the task is complete
This screenshot-action loop allows Devin to adapt to whatever is on screen, handling dynamic content, loading states, pop-ups, and unexpected dialogs just like a human would.
## Computer Use and Testing
Computer Use is the foundation of Devin's [testing and recording](/work-with-devin/testing-and-recordings) workflow. When Devin tests your application after creating a PR:
1. **Setup** — Devin installs dependencies, starts your app, and prepares the environment
2. **Test planning** — Devin reads the diff and creates a focused test plan
3. **Execution via Computer Use** — Devin uses its desktop to interact with your app, following the test plan step by step
4. **Recording** — The entire process is captured on video with annotations, then sent to you for review
The key difference between Computer Use and the Testing & Recordings workflow is scope: **Computer Use** is the underlying capability (desktop interaction), while **Testing & Recordings** is the structured workflow that uses Computer Use to test your PRs and deliver video proof.
## Computer Use on Outposts
On [Outposts](/cloud/outposts/overview), sessions run on machines you manage, so Devin uses whatever desktop environment the machine already has instead of provisioning its own. The `computer` tool is available in every desktop-mode session; if the machine can't support an action, the action fails with a clear, actionable error rather than the tool being silently missing.
### Requirements by platform
**Linux**: the worker must run with access to a graphical session — `DISPLAY` must be set in the worker's environment and point at a running X server. On a headless machine you can start one yourself (e.g. `Xvfb :0` plus a window manager) and export `DISPLAY` before starting the worker. Without a display, computer actions return an error explaining that no graphical desktop is available and how to provide one.
**macOS**: Devin reuses the machine's existing desktop session. Two separate macOS permissions (TCC) apply to the process that runs the Devin worker:
* **Screen Recording** — required for screenshots.
* **Accessibility** — required for synthetic mouse and keyboard input.
Grant both to the worker's launching process in **System Settings > Privacy & Security**, or pre-authorize them with an MDM PPPC profile on managed fleets, then restart the worker.
**Windows**: Devin uses the machine's existing interactive desktop session. Unlike Devin-managed Windows environments — where the worker starts and configures its own Chrome instance — on a Windows Outpost the worker leaves Chrome management to you: install Chrome as described in [machine dependencies](/cloud/outposts/overview#machine-dependencies) for browser features, and Devin interacts with the desktop as-is.
### Partial capability is expected
Capabilities are checked independently, so Devin degrades gracefully instead of losing the whole tool:
* If Screen Recording is granted but Accessibility is not (a common default), **screenshots work** while click/type/scroll actions return an error telling you exactly which permission to grant.
* If no display is available at all, every computer action returns the reason (e.g. `DISPLAY` not set) and what to change.
Screen recording of testing sessions additionally requires `ffmpeg` on the machine — see [machine dependencies](/cloud/outposts/overview#machine-dependencies).
## Tips for Getting the Best Results
* "Open the app, click the Settings button in the top-right, toggle dark mode, and verify all text remains readable"
* "Launch the Electron app, create a new document, type some text, and verify it saves when you close the window"
* "The dashboard should show three charts with no error messages"
* "After submitting the form, a green success banner should appear at the top of the page"
### Pre-configure access
If your app requires authentication, set up [secrets](/product-guides/secrets) ahead of time so Devin can log in without asking you during the session. Complete [environment configuration](/onboard-devin/environment) to ensure Devin can install dependencies and start your app without issues.
### Create testing skills
For apps you test frequently, create a [Skill](/product-guides/skills) that tells Devin exactly how to set up and test your application. This saves time on repeated sessions and ensures consistent testing. See [Testing & Video Recordings — Skill Suggestions](/work-with-devin/testing-and-recordings#skill-suggestions) for examples.
## Scripted Browser Use via Playwright
Devin's Chrome browser exposes a **Chrome DevTools Protocol (CDP)** endpoint that Playwright can connect to. Devin can write and run Playwright scripts to automate browser interactions — such as login flows or systematic data entry — against its own running browser. You can also write these scripts yourself and check them into your repo. For most other browser actions, Devin's native Computer Use or browser tools are recommended.
### How it works
Devin's Chrome instance listens for CDP connections on port **29229**. A Playwright script can attach to this browser, perform actions (fill forms, click buttons, handle redirects), and then disconnect. Because the script connects to the *existing* browser rather than launching a new one, all state changes — cookies, localStorage, auth tokens — persist after the script exits.
This means Devin can immediately use the authenticated session: refresh pages, navigate, and interact with the app normally.
### Example: connecting to Devin's browser
```python theme={null}
from playwright.sync_api import sync_playwright
with sync_playwright() as p:
browser = p.chromium.connect_over_cdp("http://localhost:29229")
context = browser.contexts[0]
page = context.pages[0] if context.pages else context.new_page()
# Example: navigate and log in
page.goto("https://example.com/login")
page.fill('input[name="email"]', "user@example.com")
page.fill('input[name="password"]', "password")
page.click('button[type="submit"]')
page.wait_for_url("**/dashboard")
print("Login successful!")
```
After this script runs, Devin's browser is logged in and ready to use — no manual interaction required.
### When to use this
Automate multi-step login flows (e.g., Okta, Auth0, Google SSO) that would be tedious to click through manually every session.
Include a login script in your [environment setup](/onboard-devin/environment) so Devin starts every session already authenticated.
Store login or data entry scripts in a [Skill](/product-guides/skills) so Devin can invoke them automatically when needed.
Script repetitive form submissions or bulk data entry that would be slow and error-prone via point-and-click.
### Tips
* Store login scripts in your repo's `.agents/skills/` directory so they persist across sessions
* Use [Secrets](/product-guides/secrets) to store credentials — reference them via environment variables in your scripts
* The CDP endpoint is always `http://localhost:29229` — this is the same port whether Desktop mode is enabled or not
* After the script runs, Devin can use either Computer Use or browser tools to interact with the authenticated session
## Troubleshooting
### Devin can't find a UI element
If Devin is unable to locate a button or element on screen, try being more specific in your instructions — describe the element's location, label, or surrounding context. For example, "click the blue **Save** button at the bottom-right of the modal" is better than "click Save."
### The app doesn't render on Devin's desktop
By default, Devin runs a Linux environment. If your application only runs on Windows, run your sessions on a [Windows environment](/onboard-devin/environment/windows-support) so Devin can test it there. macOS-only applications require a macOS [Outpost](/cloud/outposts/overview) machine with a desktop session. Web applications work regardless of platform since they run in Chrome. For desktop apps, ensure they have a build for the platform your sessions run on.
### Devin is clicking the wrong things
If Devin is misinteracting with your UI, provide a [Skill](/product-guides/skills) or [Knowledge](/product-guides/knowledge) entry with specific navigation instructions for your app. Describing the exact steps ("click the hamburger menu in the top-left, then click **Settings** in the dropdown") reduces ambiguity.
# Data Analyst Agent
Source: https://docs.devinenterprise.com/work-with-devin/data-analyst
Use the Data Analyst agent for fast database queries, data analysis, and visualizations
The **Data Analyst Agent**, also known as **DANA** (Data ANAlyst), is a specialized version of Devin optimized for querying databases, analyzing data, and creating visualizations. It's designed to be fast, concise, and tuned specifically for data analytics workflows.
## When to use the Data Analyst Agent
The Data Analyst Agent is ideal when you need to:
* **Query databases**: Write and execute SQL queries against your connected data sources
* **Analyze data**: Explore patterns, calculate metrics, and investigate trends in your data
* **Create visualizations**: Generate professional charts and graphs using seaborn
* **Answer data questions**: Get quick, accurate answers to questions about your data
* **Generate insights**: Discover patterns, anomalies, and actionable findings
## Accessing the Data Analyst Agent
### From the web app
1. Go to the Devin home page
2. Click the agent picker dropdown
3. Select **Data Analyst** from the dropdown menu
4. Start your session with a data-related question or task
### From Slack
You can start a Data Analyst session directly from Slack using either method:
**Using the slash command:**
```
/dana What were our top 10 customers by revenue last month?
```
**Using a mention with the `!dana` macro:**
```
@Devin !dana What were our top 10 customers by revenue last month?
```
Both methods will create a Data Analyst session and respond in-thread with the results.
## Prerequisites
Before using the Data Analyst Agent, you'll need to connect at least one data source via MCP (Model Context Protocol). Common integrations include:
* **Database MCPs**: Redshift, PostgreSQL, Snowflake, BigQuery, and other SQL databases
* **Analytics MCPs**: Datadog, Metabase, and other observability platforms
Without a connected data source, the agent will notify you and ask you to connect one before proceeding.
Learn how to connect databases and other data sources via MCP
## How it works
### Database Knowledge
The Data Analyst Agent maintains a **Database Knowledge** note that contains schema documentation for your connected databases. This knowledge is automatically referenced before running queries, allowing the agent to quickly identify the right tables and columns.
## Example prompts
Here are some effective ways to use the Data Analyst Agent across different query types:
### Simple lookups
* "How many active users did we have last week?"
* "What's our daily revenue trend for the past month?"
* "Which customers have the highest usage?"
### Aggregations and metrics
* "What's the average session duration by plan tier for the past 30 days?"
* "Show me total revenue grouped by region and product line for Q4"
* "Calculate the 95th percentile response time for each API endpoint this week"
### Joins and cross-table analysis
* "Join our users table with the orders table and show the top 20 customers by lifetime value"
* "Correlate signup source with 30-day retention — which acquisition channels have the best retention rates?"
* "Combine session data with billing records to find accounts with high usage but low spend"
### Filtering and segmentation
* "Show me only enterprise customers who signed up after January 2025 and have more than 100 sessions"
* "Filter error logs to 5xx errors from the payments service in the last 48 hours"
* "Break down consumption by enterprise vs. self-serve customers, excluding trial accounts"
### Time-series analysis
* "Plot weekly active users over the past 6 months — highlight any weeks with more than 10% change"
* "Show me a month-over-month comparison of signup rates for 2025 vs. 2024"
* "What's the daily trend for API calls over the past 90 days? Overlay a 7-day moving average"
### Investigations and anomaly detection
* "Why did signups drop last Tuesday? Check if there were any related incidents or deployments"
* "Are there any anomalies in our error rates this week?"
* "Compare this month's metrics to the same period last year and flag significant deviations"
### Multi-step analysis
* "Analyze user retention by cohort for Q4, then identify which cohorts have the steepest drop-off and suggest possible causes"
* "Find the top 10 users by session count, show their activity over time, and flag any that look like potential churns"
## Supported data sources
The Data Analyst Agent connects to your data through MCP (Model Context Protocol) integrations. You can connect multiple data sources and query across them. Below are some of the most common data sources available in the [MCP Marketplace](https://app.devin.ai/settings/connections?tab=mcps) — this is not an exhaustive list.
### SQL databases
| Data source | MCP name | Setup |
| ----------------------------------------- | ---------- | ------------------------------- |
| Amazon Redshift | Redshift | Connection string + credentials |
| PostgreSQL | PostgreSQL | Connection string |
| Snowflake | Snowflake | Account + credentials |
| Google BigQuery | BigQuery | OAuth or service account |
| MySQL | MySQL | Connection string |
| SQL Server | SQL Server | Connection string |
| Neon | Neon | OAuth |
| Supabase | Supabase | Personal access token |
| Cloud SQL (PostgreSQL, MySQL, SQL Server) | Cloud SQL | OAuth |
### Analytics and observability platforms
| Data source | MCP name | Setup |
| ----------- | -------- | --------------------------- |
| Datadog | Datadog | API key + app key |
| Metabase | Metabase | OAuth |
| Grafana | Grafana | URL + service account token |
| Sentry | Sentry | OAuth |
### Connecting a data source
1. Navigate to [Settings > Connections > MCP servers](https://app.devin.ai/settings/connections?tab=mcps)
2. Find your data source and click **Enable**
3. Provide any required credentials (connection strings, API keys, or OAuth)
4. Start a Data Analyst session — the agent will automatically discover your connected data sources
Need a data source that isn't in the Marketplace? Use **Add Your Own** to connect any MCP server by providing its configuration directly.
Full setup instructions for each data source
You can connect multiple data sources simultaneously. The Data Analyst Agent will use the appropriate MCP tools based on your query context.
## Best practices
### Be specific about metrics
Instead of asking vague questions, define exactly what you want to measure:
```text Good theme={null}
"What's our 7-day active user count, defined as users who started at least one session?"
```
```text Less effective theme={null}
"How are our users doing?"
```
### Specify time periods
Always include the time range you're interested in. The agent defaults to UTC when interpreting relative dates.
```text Good theme={null}
"Show me daily revenue for the past 30 days"
```
```text Less effective theme={null}
"Show me revenue"
```
### Request specific output formats
Tell the agent how you want to see results — as a table, chart, or summary:
```text Good theme={null}
"Plot a line chart of weekly signups for the past quarter, with a table of the raw numbers below"
```
```text Less effective theme={null}
"Get signup numbers"
```
### Define business logic upfront
If your metrics have specific definitions, state them in your prompt to avoid ambiguity:
```text Good theme={null}
"Show monthly churn rate, where churn is defined as accounts with zero sessions in the past 30 days that had at least one session in the prior 30 days"
```
```text Less effective theme={null}
"What's our churn rate?"
```
### Ask for comparisons and context
Adding comparison periods or benchmarks makes results more actionable:
```text Good theme={null}
"Show this week's daily active users compared to the same week last month, and highlight any days with more than 15% deviation"
```
```text Less effective theme={null}
"Show daily active users"
```
### Iterate on results
You can ask follow-up questions in the same session to drill deeper:
1. Start broad: *"What are our top 10 customers by revenue this quarter?"*
2. Drill down: *"For the top 3, show me their monthly revenue trend over the past year"*
3. Investigate: *"Customer X had a revenue spike in March — what drove that?"*
### Validate the SQL
The agent always includes the SQL query it used. Review it to ensure the logic matches your expectations, especially for complex analyses involving joins, filters, or aggregations.
## Output formats
The Data Analyst Agent returns results in several formats depending on the type of analysis:
### Tables
For data lookups and aggregations, results are returned as formatted tables:
```
| Customer | Revenue | Sessions | Avg Duration |
|----------------|-----------|----------|--------------|
| Acme Corp | $125,400 | 1,247 | 34 min |
| Globex Inc | $98,200 | 983 | 28 min |
| Initech | $87,600 | 876 | 41 min |
```
### Charts and visualizations
When you request visual analysis or the data is best understood graphically, the agent generates charts using seaborn. Common chart types include:
* **Line charts** — time-series trends, comparisons over time
* **Bar charts** — categorical comparisons, rankings
* **Heatmaps** — correlation matrices, activity patterns
* **Scatter plots** — relationship analysis between two metrics
Request a specific chart type if you have a preference, or let the agent choose the most appropriate visualization for your data.
### Summaries and insights
For investigation-style prompts, the agent provides a structured response that includes:
* **Analysis summary** — a plain-language answer to your question
* **SQL query** — the exact query used, so you can verify the logic
* **Key numbers** — the most important metrics highlighted
* **Data insights** — patterns, anomalies, or notable findings
* **Metabase link** — if your organization has Metabase connected via MCP, the agent may include a link to an interactive dashboard for further exploration
## Knowledge management
The Data Analyst Agent can persist learnings across sessions using the knowledge system. When it discovers:
* New schema information or table relationships
* Business logic or metric definitions
* Data quality patterns or caveats
It will save these to knowledge notes so future sessions benefit from what was learned.
Understand how Devin's knowledge system works
## Differences from standard Devin
| Capability | Data Analyst Agent | Standard Devin |
| ------------------------- | ------------------------ | --------------------- |
| SQL query execution | Optimized | Supported |
| Data visualizations | Built-in seaborn support | Manual setup |
| Database schema awareness | Pre-loaded knowledge | On-demand exploration |
| Response style | Concise, metrics-focused | Detailed explanations |
| Code changes | Not primary focus | Full support |
| MCP integrations | Required | Optional |
The Data Analyst Agent is purpose-built for data work. For tasks involving code changes, deployments, or general software engineering, use standard Devin instead.
# DeepWiki
Source: https://docs.devinenterprise.com/work-with-devin/deepwiki
Architecture diagrams, documentation, links to sources, and more for all your repos
## Overview
Devin now automatically indexes your repos and produces wikis with architecture diagrams, links to sources, and summaries of your codebase.
Use it to get up to speed on unfamiliar parts of your codebase - check it out [in your sidebar](https://app.devin.ai/wiki).
[Ask Devin](/work-with-devin/ask-devin) will use information in the Wiki to better understand and find the relevant context in your codebase. Ask Devin's advanced code search capabilities, combined with DeepWiki, produce detailed and accurate answers grounded in your code.
DeepWiki will be autogenerated when connecting repositories during onboarding.
## For Public Repos
A free version of **DeepWiki** and [Ask Devin](/work-with-devin/ask-devin) that works with public GitHub repositories is now available. It automatically generates architecture diagrams, documentation, and links to source code to help you understand unfamiliar codebases quickly. You can also ask complex questions about the codebase to get context-grounded specific answers.
The full Ask Devin experience, including advanced code search, planning, and session creation, is available in the [Devin app](https://app.devin.ai). Public DeepWiki and the DeepWiki MCP provide basic documentation and Q\&A capabilities.
Visit [deepwiki.com](https://deepwiki.com/) to start exploring popular open-source repositories like React, TensorFlow, LangChain, and many more. You can also submit your own public GitHub repository URL for indexing.
[Try DeepWiki Now →](https://deepwiki.com/)
## Effort levels and cost
Wiki generation runs at one of three effort levels, configurable per org (and overridable per repo) from the wiki page:
| Effort level | Approximate cost | Requirements |
| ------------- | --------------------- | ---------------------------------------- |
| Low (default) | Free | None |
| Medium | \~5-10 ACUs per wiki | Active subscription or available credits |
| High | \~20-40 ACUs per wiki | Active subscription or available credits |
Medium and high effort wikis are billed against your team's ACU usage, so they require an active subscription or a positive credit balance. If your team has neither, generation is rejected and no wiki is produced — add credits or switch the effort level to low.
Enterprise orgs always run at low effort; the setting is not configurable for them.
## Steering DeepWiki
The `.devin/wiki.json` file allows you to steer Devin's default wiki generation behavior, which is especially important for large repositories that may hit built-in limits.
If a `.devin/wiki.json` file is found in your repository's root directory during wiki generation, we'll use the provided `repo_notes` and `pages` to steer wiki generation. If `pages` is provided, we'll bypass the default cluster-based planning and create exactly the pages you specify. This ensures that the important parts of your codebase are documented even when the automatic system would otherwise skip them.
## Configuration Format
Create a `.devin/wiki.json` file in your repository root with the following structure:
```json theme={null}
{
"repo_notes": [
{
"content": "This repository contains the main UI components in the cui/ folder, which should be prioritized in documentation",
"author": "Team Lead"
}
],
"pages": [
{
"title": "CUI Components Overview",
"purpose": "Document the cui/ folder structure and main UI components",
"parent": null
},
{
"title": "Authentication System",
"purpose": "Document the authentication flow and related components",
"parent": null
},
{
"title": "Login Components",
"purpose": "Detailed documentation of login-related UI components",
"parent": "Authentication System"
}
]
}
```
## Configuration Options
### repo\_notes (Array)
Provides context and guidance to help the documentation system understand your repository better.
* **content** (string, required): The note content (max 10,000 characters)
* **author** (string, optional): Who wrote the note
### pages (Array, optional)
Specifies exactly which pages should be created in your wiki.
This field is optional. If you only include repo\_notes, the system will still generate a wiki, using your notes to guide the structure and focus without requiring you to outline every page.
When you do provide pages, they are treated as explicit instructions. Only the pages you define in the JSON will be generated, no more, no less.
* **title** (string, required): The page title (must be unique and non-empty)
* **purpose** (string, required): What this page should document
* **parent** (string, optional): Title of the parent page for hierarchical organization
* **page\_notes** (array, optional): Additional notes specific to this page
### Validation Limits
* Maximum 30 pages (80 for enterprise)
* Maximum 100 total notes (repo\_notes + all page\_notes combined)
* Maximum 10,000 characters per note
* Page titles must be unique and non-empty
## Practical Examples
### Example 1: Repo Notes to Guide Wiki Generation
If you prefer not to define specific pages, you can provide only repo\_notes to help guide the wiki generation. This allows Devin to create the documentation structure automatically while still taking into account your priorities and areas of focus. This is useful when you want better coverage and emphasis without having to explicitly outline every page yourself.
```json theme={null}
{
"repo_notes": [
{
"content": "The repository contains three main areas: the frontend/ folder with React components, the backend/ folder with API services, and the infra/ folder with deployment scripts. Documentation should emphasize how these parts interact and highlight the backend API layer as the highest priority."
}
]
}
```
### Example 2: Ensuring Specific Folders Are Documented
If your large repository has important folders that aren't being included in the wiki, explicitly specify them:
```json theme={null}
{
"repo_notes": [
{
"content": "The cui/ folder contains critical UI components that must be documented. The backend/ folder contains the main API logic. The utils/ folder has shared utilities used throughout the codebase."
}
]
}
```
### Example 3: Addressing Missing Components
If you notice certain parts of your codebase aren't being documented:
```json theme={null}
{
"repo_notes": [
{
"content": "The testing/ directory contains important test utilities and patterns that developers need to understand. The scripts/ directory has deployment and maintenance scripts that are crucial for operations."
}
]
}
```
### Example 4: Hierarchical Documentation Structure
For complex repositories, organize pages hierarchically:
```json theme={null}
{
"repo_notes": [
{
"content": "This is a full-stack application with distinct frontend, backend, and shared components that should be documented separately but with clear relationships."
}
],
"pages": [
{
"title": "Architecture Overview",
"purpose": "High-level overview of the application architecture and how components interact"
},
{
"title": "Frontend",
"purpose": "Frontend application structure and components",
"parent": "Architecture Overview"
},
{
"title": "React Components",
"purpose": "Detailed documentation of React components, their props, and usage",
"parent": "Frontend"
},
{
"title": "State Management",
"purpose": "How application state is managed, including stores and data flow",
"parent": "Frontend"
},
{
"title": "Backend",
"purpose": "Backend services, APIs, and data layer",
"parent": "Architecture Overview"
},
{
"title": "API Endpoints",
"purpose": "REST API documentation including endpoints, request/response formats",
"parent": "Backend"
}
]
}
```
## Best Practices
### 1. Use Repo Notes Strategically
* Provide context about which parts of your codebase are most important
* Mention specific folders or components that should be prioritized
* Explain relationships between different parts of your system
### 2. Organize Pages Logically
* Start with high-level overview pages
* Use parent-child relationships to create clear hierarchies
* Group related functionality together
### 3. Be Specific in Page Purposes
* Clearly state what each page should document
* Mention specific directories, files, or concepts to focus on
* Provide enough detail for the system to understand your intent
### 4. Address Known Gaps
* If you know certain parts of your codebase are being missed, explicitly include them
* Use descriptive titles that make it clear what should be covered
## Troubleshooting Common Issues
### "Only certain folders are being documented"
This is the classic large repository problem.
**Solution:** Use `.devin/wiki.json` to explicitly specify which parts of your codebase should be documented.
Start with updating only repo\_notes, and regenerate the wiki with that additional context to see if the updated wiki will include the missing folders. Only add the pages array if necessary.
### "Important components are missing from the wiki"
Add specific pages for these components and use repo\_notes to emphasize their importance.
Remember: The DeepWiki will generate only the pages included in this array, so ensure all pages are present, not just the missing page.
```json theme={null}
{
"repo_notes": [
{
"content": "The [missing-component] directory is critical to the application and must be documented thoroughly."
}
],
"pages": [
{
"title": "Critical Component Name",
"purpose": "Document the [missing-component] directory and its functionality"
}
]
}
```
## Getting Started
1. Create `.devin/wiki.json` in your repository root
2. Add repo\_notes explaining your codebase structure and priorities
3. If necessary, specify **all** pages you want created with clear titles and purposes
4. Commit the file and regenerate your wiki
The system will now create documentation based on your explicit instructions rather than fully automatic analysis, ensuring comprehensive and more accurate coverage of large repositories.
# DeepWiki MCP
Source: https://docs.devinenterprise.com/work-with-devin/deepwiki-mcp
How to use the official DeepWiki MCP server
The DeepWiki MCP server provides programmatic access to DeepWiki's public repository documentation and search capabilities (Ask Devin).
## What is MCP?
The [Model Context Protocol](https://modelcontextprotocol.io/introduction) (MCP) is an open standard that enables AI apps to securely connect to MCP-compatible data sources and tools. You can think of MCP like a USB-C port for AI applications - a standardized way to connect AI apps to different services.
## DeepWiki MCP Server
The DeepWiki MCP server is a free, remote, no-authentication-required service that provides access to public repositories.
**Base Server URL:** `https://mcp.deepwiki.com/`
### Available Tools
The DeepWiki MCP server offers three main tools:
1. **`read_wiki_structure`** - Get a list of documentation topics for a GitHub repository
2. **`read_wiki_contents`** - View documentation about a GitHub repository
3. **`ask_question`** - Ask any question about a GitHub repository and get an AI-powered, context-grounded response
### Wire Protocols
The DeepWiki MCP server supports two wire protocols:
#### Streamable HTTP - `/mcp`
* **URL:** `https://mcp.deepwiki.com/mcp`
* Works with Cloudflare, OpenAI, and Claude
* **Recommended for most integrations**
#### SSE (Server-Sent Events) - `/sse`
* **URL:** `https://mcp.deepwiki.com/sse`
* Legacy protocol, being deprecated
The `/mcp` endpoint is recommended as SSE is being deprecated.
## Setup Instructions
The field name for the server URL depends on the client: Devin Desktop uses `serverUrl`, while most other clients use the standard `url` field. Using the wrong field name causes the MCP server to be silently ignored.
### For Devin Desktop:
```json theme={null}
{
"mcpServers": {
"deepwiki": {
"serverUrl": "https://mcp.deepwiki.com/mcp"
}
}
}
```
### For most other clients (e.g. Cursor):
```json theme={null}
{
"mcpServers": {
"deepwiki": {
"url": "https://mcp.deepwiki.com/mcp"
}
}
}
```
### For Claude Code:
```bash theme={null}
claude mcp add -s user -t http deepwiki https://mcp.deepwiki.com/mcp
```
## Related Resources
* **[Devin's MCP Marketplace](/work-with-devin/mcp)**
* **[Connecting remote MCP servers to Claude](https://support.anthropic.com/en/articles/11175166-about-custom-integrations-using-remote-mcp)**
* **[OpenAI's docs for using the DeepWiki MCP server](https://platform.openai.com/docs/guides/tools-remote-mcp)**
* **[DeepWiki](/work-with-devin/deepwiki)**
* **[Ask Devin](/work-with-devin/ask-devin)**
Want DeepWiki capabilities for private repositories? Sign up for a Devin account at [Devin.ai](https://devin.ai/) and use the [Devin MCP server](/work-with-devin/devin-mcp) with your Devin API key.
# Devin CLI
Source: https://docs.devinenterprise.com/work-with-devin/devin-cli
Use Devin as a local coding agent directly from your command line, with the ability to hand off tasks to cloud Devin.
[Devin CLI](/cli) is a local coding agent that runs directly in your terminal. It works with your local files and environment, giving you fast, interactive assistance right where you code.
For full documentation — including installation, commands, configuration, and extensibility — see the **[Devin CLI docs](/cli)**.
## Handoff to cloud Devin
When a task outgrows your local machine — or you want Devin to keep working while you step away — use the `/handoff` command to seamlessly transfer work to a cloud [Devin session](/get-started/first-run).
```
/handoff fix the flaky integration tests in CI
```
Devin CLI will package up the conversation context and current git branch, then create a cloud Devin session that picks up where you left off. You can track the session's progress directly from the terminal or in the Devin web app.
If you run `/handoff` without a task description, the cloud session continues from where you left off automatically.
Install and start coding in 2 minutes
Must-know commands and keyboard shortcuts
# Hand off to cloud Devins
Source: https://docs.devinenterprise.com/work-with-devin/devin-handoff
Hand off tasks to a cloud Devin session from the Devin CLI, Claude Code, Codex, or any coding agent.
Hand a task off to a cloud [Devin session](/get-started/first-run) and keep working locally. The cloud session gets its own VM with a shell, browser, and full repo access, so it can keep going after you close your laptop.
There are two ways to hand off:
* **From the [Devin CLI](/cli)** — the built-in `/handoff` command, no setup required.
* **From any other coding agent** — Claude Code, Codex, Cursor, and more, using the open-source [Devin Handoff](https://github.com/club-cog/devin-handoff) plugin.
## When to hand off
Hand a task off when it needs more than your local machine, or when you want it to run in the background:
* **VM or server** — running a dev server, hitting endpoints, Docker builds
* **Browser** — screenshots, OAuth flows, end-to-end tests, scraping
* **CI/CD** — pipeline debugging, deployments, infrastructure changes
* **Long-running work** — migrations, batch jobs, large refactors
* **Parallel execution** — offload work to the cloud while you keep coding locally
## From the Devin CLI
The [Devin CLI](/cli) is a local coding agent that runs in your terminal. It has a built-in [`/handoff`](/work-with-devin/devin-cli#handoff-to-cloud-devin) command — nothing to install.
```
/handoff fix the flaky integration tests in CI
```
Devin CLI packages up the conversation context and current git branch, then creates a cloud Devin session that picks up where you left off. Track the session's progress from your terminal or in the [Devin web app](https://app.devin.ai).
Run `/handoff` without a task description and the cloud session continues from where you left off automatically.
## From other coding agents
[Devin Handoff](https://github.com/club-cog/devin-handoff) is an open-source plugin and skill that brings the same handoff workflow to any coding agent — Claude Code, Codex, Cursor, and more. Install it once, then just say *"hand this off to Devin"* and your agent gathers the current repo, branch, and uncommitted changes, creates a session, and hands you back a URL.
You'll need a Devin API key — generate one on the [API keys page](https://app.devin.ai/settings/api-keys) and export it as `DEVIN_API_KEY`. For install and usage instructions across every agent, follow the [repository README](https://github.com/club-cog/devin-handoff), which stays current as the plugin evolves.
### How context reaches the cloud session
A cloud session starts in a fresh VM, so the skill packages up what your local agent already knows and includes it in the session prompt:
* **Repo and branch** — detected from `git remote` and `git rev-parse`, so Devin clones the right repo and checks out the branch you're on.
* **Uncommitted changes** — the output of `git diff HEAD` (truncated to 100KB) is included, so your work-in-progress carries over. If you have local edits you don't want sent, commit or stash them first.
* **Extra context** — whatever the calling agent has learned so far: files it examined, root-cause hypotheses, partial fixes.
## Related resources
The local coding agent with the built-in `/handoff` command
Source, install guides, and the full script reference
The Sessions API that powers the handoff
Manage sessions, playbooks, and knowledge from any MCP client
# Devin MCP
Source: https://docs.devinenterprise.com/work-with-devin/devin-mcp
How to use the official Devin MCP server for private and public repositories
The Devin MCP server provides programmatic access to Devin's platform capabilities for both private and public repositories. Beyond repository documentation and search, it gives any MCP-compatible AI agent or IDE full access to session management, playbooks, knowledge, and scheduling.
Any Devin session or MCP-compatible client can create sessions, manage playbooks and knowledge, set up schedules, and more. See [Advanced Capabilities](/work-with-devin/advanced-capabilities) for details on what Devin can do.
## What is MCP?
The [Model Context Protocol](https://modelcontextprotocol.io/introduction) (MCP) is an open standard that enables AI apps to securely connect to MCP-compatible data sources and tools. You can think of MCP like a USB-C port for AI applications — a standardized way to connect AI apps to different services.
## Devin MCP Server
The Devin MCP server is an authenticated service that provides access to both public and private repositories, plus full platform management capabilities.
**Base Server URL:** `https://mcp.devin.ai/`
### Authentication Required
To use the Devin MCP server, you need a Devin API key:
1. Sign up for a Devin account at [Devin.ai](https://devin.ai/)
2. Generate an API key from your [account settings](/api-reference/authentication)
3. Include the API key in your MCP client configuration
The MCP server supports the same authentication methods as the [Devin API](/api-reference/authentication):
| Token type | Prefix | Org resolution |
| ------------------------------- | ------ | ----------------------------------------------------- |
| **Org-scoped service user key** | `cog_` | Automatic — org\_id is resolved from the service user |
| **Enterprise service user key** | `cog_` | Requires `X-Org-Id` header (see below) |
| **Personal access token** | `cog_` | Requires `X-Org-Id` header (see below) |
Legacy API keys (`apk_` / `apk_user_` prefix) are **not supported** by the Devin MCP server. Use a [service user API key](/api-reference/authentication#service-users-recommended-for-automation) instead.
#### Enterprise accounts: `X-Org-Id` header
Enterprise service user keys and PATs are scoped to the account level, not a specific organization. Since the MCP tools operate on organization-level resources (sessions, playbooks, knowledge, etc.), you must tell the server which organization to target by passing the `X-Org-Id` header:
```json theme={null}
{
"mcpServers": {
"devin": {
"serverUrl": "https://mcp.devin.ai/mcp",
"headers": {
"Authorization": "Bearer ",
"X-Org-Id": ""
}
}
}
}
```
Find your organization ID on the **Settings > Service users** page, or call the [GET /v3/self](/api-reference/v3/self/self) endpoint with your API key.
Org-scoped service user keys do not need this header — the organization is resolved automatically.
## Available Tools
### Repository Documentation
These tools let you explore and query documentation for any GitHub repository (public or private with authentication):
| Tool | Description |
| -------------------------- | ----------------------------------------------------------------------------------------------------------- |
| **`read_wiki_structure`** | Get a list of documentation topics for a GitHub repository |
| **`read_wiki_contents`** | View full documentation about a GitHub repository |
| **`ask_question`** | Ask any question about one or more repositories (up to 10) and get an AI-powered, context-grounded response |
| **`list_available_repos`** | List all repositories available to query with your Devin account |
### Session Management
Create, search, inspect, and control Devin sessions programmatically:
| Tool | Description |
| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **`devin_session_create`** | Create one or more Devin sessions. Each session can have a prompt, title, playbook, tags, and ACU limit |
| **`devin_session_search`** | Search and filter sessions by tags, playbook, origin, schedule, user, or creation/update time |
| **`devin_session_interact`** | Interact with a session — get status, send messages, sleep, terminate, archive, read messages and attachments, or manage tags |
| **`devin_session_events`** | Inspect events within a session — list summaries, fetch full event details, or search event contents by text |
| **`devin_session_gather`** | Wait for multiple sessions to reach a settled state (finished, errored, sleeping, or waiting) before returning. Useful after creating parallel sessions instead of polling in a loop |
### Playbook Management
Create and manage playbooks that standardize how Devin performs tasks:
| Tool | Description |
| --------------------------- | --------------------------------------------------------------------------------------------- |
| **`devin_playbook_manage`** | List, get, create, update, or delete playbooks. Supports automation macros (e.g. `!my_macro`) |
### Knowledge Management
Maintain your organization's knowledge base that Devin uses for context:
| Tool | Description |
| ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **`devin_knowledge_manage`** | Full CRUD for knowledge notes — list, get, create, update, delete, browse folder structure. Also manage knowledge suggestions — list, view, and dismiss pending suggestions. Supports filtering by repo, folder, and search queries |
### Schedule Management
Set up recurring or one-time scheduled Devin sessions:
| Tool | Description |
| --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **`devin_schedule_manage`** | List, get, create, update, or delete schedules. Supports cron expressions for recurring schedules, one-time scheduling, notification preferences, and agent selection |
### Integration Management
View and manage your organization's native integrations and MCP servers:
| Tool | Description |
| ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **`list_integrations`** | List all native integrations (e.g. GitHub, Jira, Slack) and MCP servers with their install status and settings URLs. Filter by installed, not installed, or all |
## Wire Protocols
The Devin MCP server supports Streamable HTTP:
* **URL:** `https://mcp.devin.ai/mcp`
* Works with HTTP-compatible clients
* **Recommended for all integrations**
The legacy SSE (`/sse`) endpoint has been deprecated. Use the `/mcp` endpoint instead.
## Key Differences from DeepWiki MCP
| Feature | DeepWiki MCP | Devin MCP |
| ----------------------- | --------------------------- | ------------------------------------------------------- |
| **Authentication** | None required | API key required |
| **Repository Access** | Public repositories only | Public and private repositories |
| **Platform Management** | Not available | Sessions, playbooks, knowledge, schedules, integrations |
| **Base URL** | `https://mcp.deepwiki.com/` | `https://mcp.devin.ai/` |
| **Cost** | Free | Requires Devin account |
## Setup Instructions
The field name for the server URL depends on the client: Devin Desktop uses `serverUrl`, while most other clients use the standard `url` field. Using the wrong field name causes the MCP server to be silently ignored.
### For Devin Desktop:
```json theme={null}
{
"mcpServers": {
"devin": {
"serverUrl": "https://mcp.devin.ai/mcp",
"headers": {
"Authorization": "Bearer "
}
}
}
}
```
### For most other clients (e.g. Cursor):
```json theme={null}
{
"mcpServers": {
"devin": {
"url": "https://mcp.devin.ai/mcp",
"headers": {
"Authorization": "Bearer "
}
}
}
}
```
### For Claude Code:
```bash theme={null}
claude mcp add -s user -t http devin https://mcp.devin.ai/mcp -H "Authorization: Bearer "
```
## Related Resources
* **[Advanced Capabilities](/work-with-devin/advanced-capabilities)** — Overview of Devin's advanced features
* **[Devin's MCP Marketplace](/work-with-devin/mcp)**
* **[Connecting remote MCP servers to Claude](https://support.anthropic.com/en/articles/11175166-about-custom-integrations-using-remote-mcp)**
* **[OpenAI's docs for using MCP servers](https://platform.openai.com/docs/guides/tools-remote-mcp)**
* **[DeepWiki MCP](/work-with-devin/deepwiki-mcp)** — For public repositories only
* **[DeepWiki](/work-with-devin/deepwiki)**
* **[Ask Devin](/work-with-devin/ask-devin)**
# Devin Review
Source: https://docs.devinenterprise.com/work-with-devin/devin-review
A new way to quickly review and understand complex PRs.
As coding agents become more prevalent, the bottleneck shifts from writing code to reviewing it.
Devin Review is a full-service code review platform within the Devin webapp that turns large, complex PRs into intuitively organized diffs and precise explanations. It supports GitHub (including GitHub Enterprise Server and Enterprise Cloud) and GitLab (including Self-Managed GitLab).
Devin Review is available for PRs on GitHub repositories
(including GitHub Enterprise Server and Enterprise Cloud)
and merge requests on GitLab repositories (including Self-Managed GitLab).
Public PRs don't require a Devin account. Private PRs
can be viewed with a Devin account or via the [CLI](#cli).
## Features
Groups changes logically, putting related edits together instead of
alphabetical order.
Detects when code has been copied or moved and displays changes cleanly,
instead of full deletes and inserts.
Checks for bugs and labels them by confidence level. Severe bugs require
immediate attention.
Detects security vulnerabilities and suggests hardening improvements,
with CWE classification and severity levels.
Leave comments, approve PRs, request changes—all within Devin Review, synced
to GitHub.
Ask questions about the PR and get answers with relevant context from the
rest of the codebase. You can also ask Devin directly from any comment,
bug, or flag in the diff view.
Merge, close, convert to draft, mark ready for review, and toggle auto-merge
directly from Devin Review without leaving the page.
Ask the chat agent to make code edits. Review the suggested changes, then
apply them as a commit to the PR branch without leaving Devin Review.
## Getting Started
* **Devin webapp** — Head to [app.devin.ai/review](https://app.devin.ai/review) to see your open PRs organized by category (assigned to you, authored by you, review requested). When Devin makes PRs, you'll see an orange "Review" button in the chat.
* **PR comment** — Comment `/devin review` on any GitHub PR in a repository your organization has connected, and Devin reviews it on the spot. See [Triggering a Review from a PR Comment](#triggering-a-review-from-a-pr-comment).
* **URL shortcut** — For any GitHub.com PR link, replace `github.com` with `devinreview.com` in the URL. For private PRs, sign in to Devin first or use the CLI.
* **GitHub Enterprise** — Paste the full PR URL into the Devin Review page at [app.devin.ai/review](https://app.devin.ai/review). All GitHub offerings (GitHub.com, Enterprise Server, Enterprise Cloud) have the same capabilities.
* **CLI** — Run `npx devin-review {pr-url}` from within a local clone. See [CLI](#cli) below for details.
## Supported Git Providers
| Capability | GitHub | GitLab | Bitbucket | Azure DevOps |
| ----------------------------- | ------ | ------- | --------- | ------------ |
| View diffs and analysis | Yes | Yes | No | No |
| Bug catcher | Yes | Yes | No | No |
| Codebase-aware chat | Yes | Yes | No | No |
| Code changes from chat | Yes | Yes | No | No |
| Comments and reviews | Yes | Yes | No | No |
| Merge / close / draft actions | Yes | Partial | No | No |
| Auto-merge | Yes | Partial | No | No |
| Auto-review | Yes | Yes | No | No |
**GitHub** includes GitHub.com, GitHub Enterprise Server, and GitHub Enterprise Cloud — all have the same capabilities. Write features (comments, reviews, merge actions, code changes from chat) require a [GitHub App](/integrations/gh) connection installed on your GitHub organization. PAT-based connections are read-only and cannot post comments, submit reviews, or perform merge actions. To set up the GitHub App, see the [GitHub integration guide](/integrations/gh).
**GitLab** includes GitLab.com and Self-Managed GitLab. Write features for Self-Managed GitLab (comments, reviews, merge actions, code changes from chat) require a GitLab App connection. To set up the GitLab App, see the [GitLab Self-Managed integration guide](/enterprise/integrations/gitlab-self-managed).
## Permissions
Devin Review access is controlled by account-level permissions configured in the role editor under **Devin Review permissions**. By default, all members and admins receive full auto-review access, and admins additionally receive **Manage Devin Review**.
Enterprise admins can use [Custom Roles](/enterprise/security-access/custom-roles#account-level-roles-enterprise-roles) to restrict access to a lower usage tier (manual-only or on-PR-creation only), remove access entirely, or grant admin capabilities. Self-enrollment for auto-review does not require **Manage Devin Review** — any user with a usage tier and a connected GitHub account can enroll themselves.
See [Account-level roles](/enterprise/security-access/custom-roles#account-level-roles-enterprise-roles) for the full list of Devin Review permission tiers and what each one grants.
**Enterprise accounts:** Only users in the primary organization with **Manage Devin Review** can manage review settings. Users in non-primary organizations can self-enroll but cannot change admin settings.
## Governance
Enterprise admins can control who uses Devin Review, what level of automation they have, and how much it costs — all from the Devin webapp.
The features in this section require a **Devin Enterprise** account. For
details on enterprise plans, [contact sales](https://cognition.com/contact).
### Cost control
Devin Review consumes [ACUs](/admin/billing/usage) (Agent Compute Units) from your enterprise's ACU pool, the same pool used by Devin sessions and other Devin products. Enterprise admins have several tools to monitor and control review costs.
#### Consumption dashboard
The enterprise consumption dashboard at [Settings > Consumption](https://app.devin.ai/settings/consumption) breaks down ACU usage by product, including a dedicated **Review** line in the daily consumption chart. Organization admins can view their org's review consumption from [Settings > Consumption Analytics](https://app.devin.ai/settings/analytics?tab=consumption).
The dashboard includes:
* **Per-user breakdown** — See how many review ACUs each user consumed in the current and previous billing cycle.
* **Per-repository breakdown** — See review ACU consumption, review count, and the number of bugs caught by repository for the current and previous billing cycle, helping identify which repos drive the most review cost and where reviews catch the most issues.
**Devin Review ACUs do not count against per-organization ACU limits.** Per-org ACU limits configured in [Settings > Organizations](https://app.devin.ai/settings/organizations) apply to Devin sessions only — Review consumption is tracked at the enterprise level and is not capped by org limits. Reviews continue to run even after an organization reaches its session ACU limit.
#### Review size indicator
Each PR in Devin Review displays a consumption pill showing the review's t-shirt size based on total ACU usage across all review jobs on that PR:
| Size | ACU range |
| ------ | --------------- |
| **XS** | ≤ 2.25 ACUs |
| **S** | 2.25 – 4.5 ACUs |
| **M** | 4.5 – 9 ACUs |
| **L** | 9 – 18 ACUs |
| **XL** | > 18 ACUs |
Hover over the size pill to see the exact ACU total, the number of review jobs run, and the cost of the currently viewed review. This helps reviewers understand the cost impact of re-running reviews or enabling auto-review on high-churn PRs.
#### Per-PR auto-review spend limit
Admins can cap how much Devin Review spends on automatic reviews of a single PR from [Settings > Review](https://app.devin.ai/settings/review) under the **Auto-review limits** section. The limit is measured in ACUs on Enterprise plans, or in dollars of on-demand spend for Individual and Teams plans. Leave the field empty for no limit (the default).
Once a PR's total review spend across all of its review jobs reaches the limit, auto-review is turned off for that PR and future auto-reviews are skipped. Reaching the limit is a soft block:
* **Manual reviews still work** — the limit only pauses automatic reviews. You can always trigger a review yourself from the PR review page.
* **Re-enable per PR** — Turning auto-review back on for the PR from the actions menu (three dots in the header) resumes auto-reviews and exempts that PR from the limit.
When a limit is configured, the consumption pill's hover card shows the limit alongside the PR's usage and indicates when the limit has been reached. If [PR description updates](#admin-configuration) are enabled, the Devin Review status row in the PR description also notes when auto-review was paused by the spend limit, with a link to re-enable it.
## PR Workflow Actions
Devin Review lets you take action on PRs directly from the review page, without switching to GitHub.
* **Merge** — Merge the PR using the repository's configured merge strategy (merge commit, squash, or rebase). The merge button reflects the PR's current mergeability status and required checks.
* **Close** — Close the PR without merging. Available from the dropdown menu next to the merge button.
* **Convert to draft** — Convert an open PR to draft status. Available from the dropdown menu when the PR is open and not already a draft.
* **Mark ready for review** — Mark a draft PR as ready for review. A "Ready for review" button appears in the merge bar for draft PRs.
* **Auto-merge** — Enable or disable GitHub auto-merge from the merge button dropdown. When enabled, the PR will merge automatically once all required checks pass. The merge bar shows the current auto-merge status, including who enabled it.
All workflow actions require a [GitHub App](/integrations/gh) connection and are disabled when viewing in read-only mode (e.g., public repos without a connected account, or PAT-based connections).
## Stacked PRs
Devin Review treats [stacked PRs](/work-with-devin/stacked-prs) as first-class. When a PR belongs to a stack, the review page shows the whole series and handles merging correctly:
* **Stack panel** — The PR header shows the stack with every member ordered bottom-to-top, down to the base branch it merges into. Each member links to its own review page, so you can read the stack layer by layer.
* **Per-layer readiness** — Each member shows a status dot reflecting its true mergeability: green when it can actually merge (accounting for CI, required reviews, and branch protection), red for failing checks or conflicts, and orange for anything else blocking the merge — including when a layer is individually ready but blocked by an unmergeable PR below it. An aggregate indicator summarizes the whole stack.
* **Focused diffs** — Each PR in a stack is diffed against the layer below it, so every review — including [auto-review](#auto-review) and the [bug catcher](#bug-catcher) — sees only that layer's change.
* **Stack merge** — Stacked PRs merge through GitHub's atomic stack merge: merging a PR also merges every open PR below it in the stack, bottom-up, in a single operation. The merge button shows exactly how many PRs the action will land, and GitHub retargets the remaining PRs onto the base branch afterwards.
Stacked PRs are available for GitHub.com repositories only. See the [Stacked PRs guide](/work-with-devin/stacked-prs) for how Devin creates and maintains stacks.
## Auto-Review
Devin can automatically review PRs without you having to manually trigger it. Configure auto-review in [Settings > Review](https://app.devin.ai/settings/review). On any PR review page, the actions menu (three dots in the header) lets you toggle auto-review for that specific PR and links to the review settings pages.
### When Does Auto-Review Run?
Auto-review triggers when:
* A PR is opened (non-draft)
* New commits are pushed to a PR
* A draft PR is marked as ready for review
Draft PRs are skipped until marked ready.
### Trigger Modes
Repositories and individual users can each be configured with a trigger mode that controls when auto-review runs:
* **Auto review** (default) — Reviews trigger on all events: PR opened, new commits pushed, and draft marked ready.
* **On PR creation** — Reviews only trigger when a PR is first opened or a draft PR is marked as ready for review. Subsequent pushes to the PR do not trigger a new review.
* **Manual** — No reviews run automatically. You trigger a review yourself from the PR review page whenever you want one. This is the base tier for personal enrollment.
Repository trigger modes are limited to **Auto review** and **On PR creation**. Personal enrollment additionally supports **Manual** for users who only want to trigger reviews on demand.
When a PR matches both an enrolled repository and an enrolled user, the most permissive trigger mode applies.
Admins can set the trigger mode per repository from [Settings > Review](https://app.devin.ai/settings/review), and each user can set their personal trigger mode from [Settings > Preferences](https://app.devin.ai/settings/preferences).
### Self-Enrollment (All Users)
Any user with a connected GitHub account can enroll themselves for auto-reviews—no admin permissions needed.
1. Go to [Settings > Preferences](https://app.devin.ai/settings/preferences)
2. Under **Devin Review**, set your **Review trigger** to **On PR creation** or **Auto-review** (leave it on **Manual** if you only want to trigger reviews yourself)
Once enrolled with **Auto-review**, Devin will automatically review any PR you author, on any repository. With **On PR creation**, Devin reviews only when the PR is first opened or marked ready for review.
You can also turn auto-review on or off for a specific PR from the actions menu (three dots in the header) on its review page, which also links to your personal review settings.
### Review Comment Language
You can choose the language Devin Review uses for its comments and analysis from [Settings > Preferences](https://app.devin.ai/settings/preferences) under the **Devin Review** section.
* **Use your display language** (default) — Review comments follow your display language setting.
* **Specific language** — Choose from English, Spanish, Portuguese, Japanese, Chinese, Korean, French, German, Russian, Arabic, Hebrew, or Indonesian.
Language instructions in your [REVIEW.md](#reviewmd) take precedence over this setting. If your `REVIEW.md` specifies a language for review comments, Devin will use that language regardless of your personal preference.
### Admin Configuration
Admins have additional options in [Settings > Review](https://app.devin.ai/settings/review):
* **Repositories** — Add repositories to auto-review ALL PRs on that repo. Use the **Add repo** button to search and select from connected repositories, and set each repository's trigger mode from the list.
* **Users** — View all enrolled users across the organization along with each user's trigger mode. Users enroll themselves through [self-enrollment](#self-enrollment-all-users); admins cannot enroll other users directly.
* **Add "Devin Review" link in PR description** — When enabled (default), Devin adds a link to the review in the PR description.
### Posting to GitHub
Admins can configure what Devin Review posts back to GitHub from [Settings > Review](https://app.devin.ai/settings/review) under the **Post as PR comments** section:
* **Post GitHub CI checks** — When enabled (default), Devin creates a commit status check on the PR for each review. This lets you see review results directly in your PR's checks list.
* **Bugs** — Post bugs (likely errors or incorrect behavior) as PR comments.
* **Security** — Post security vulnerabilities and hardening suggestions as PR comments. Only visible when [security scanning](#security) is enabled.
* **Flags (investigate)** — Post investigate flags (potential issues worth a closer look) as PR comments.
* **Flags (note)** — Post informational flags (observations that may not require action) as PR comments.
By default, bugs and "investigate" flags are posted as PR comments. Admins can toggle each finding type independently.
**Enterprise accounts:** Settings apply across all organizations in the
enterprise. Only users in the primary organization with enterprise admin
permissions can manage settings. Users in non-primary orgs can only
self-enroll.
Auto-review is not available for public repos that aren't connected to your
organization.
## Bug Catcher
The Bug Catcher automatically analyzes your PR for potential issues and displays findings in the Analysis sidebar. Findings are organized into **Bugs**, **Flags**, and **[Security](#security)**.
### Bugs
Bugs are actionable errors that should be fixed in the code. These represent issues the Bug Catcher has high confidence are actual problems.
Bugs are displayed with two severity levels:
* **Severe** — High-confidence
issues that require immediate attention
*
**Non-severe** — Lower severity issues that should still be reviewed
When you see a bug, you should investigate and fix it in your code.
### Flags
Flags are informational code annotations that may or may not require action. They come in two classes:
* **Investigate** — Flags that warrant further investigation. You should review the flagged code yourself and verify whether there is an actual bug or issue.
* **Informational** — The Bug
Catcher has either concluded correctness or is explaining how something works.
These help you understand the code changes without requiring action.
### Security
Devin Review scans for security vulnerabilities and displays them in a dedicated **Security** section of the Analysis sidebar, alongside Bugs and Flags. Security scanning is enabled by default and can be toggled from [Settings > Review](https://app.devin.ai/settings/review) under the **Security scan** section.
The scanner checks for the following vulnerability categories:
* Injection (SQL, XSS, command, template)
* Auth flaws (missing/broken access control, privilege escalation, auth bypass)
* Secrets exposure (hardcoded keys, tokens in logs, credentials in source)
* SSRF and path traversal
* Insecure deserialization, prototype pollution
* Missing input validation on untrusted data
* Weak cryptography (algorithms, key management)
* Transport/cookie security (missing HTTPS enforcement, permissive CORS, insecure cookie flags)
* Insecure defaults or misconfigurations introduced by the PR
Findings are displayed with two severity levels:
* **Critical** — High-confidence
vulnerabilities that should be fixed before merging
* **Warning** — Potential
security weaknesses worth investigating
Each finding includes a description of the issue, a recommendation for how to fix it, and where applicable a [CWE](https://cwe.mitre.org/) identifier classifying the vulnerability type.
The security scan also respects any security-related instructions in your [instruction files](#agentsmd-instruction-files) — for example, you can add security policies, sensitive areas, or threat models to your `REVIEW.md` to guide what the scanner looks for.
### Resolving Findings
You can mark bugs, flags, and security findings as resolved once you've addressed them or determined they don't require action. Resolved items are dimmed in the sidebar and sorted to the bottom of each section.
## Review Actions
### Triggering a Review from a PR Comment
You don't need to enable [auto-review](#auto-review) on a repository to get a review. Comment `/devin review` on any GitHub pull request and Devin reviews that PR, then replies on the PR with a link to the review.
This works on any repository covered by your organization's [GitHub App](/integrations/gh) installation — including repos that aren't enrolled in auto-review — and is the quickest way to try Devin Review on a one-off PR.
Requirements and behavior:
* **Comment exactly `/devin review`** at the start of the comment. The command is case-insensitive, and works in both PR conversation comments and inline review comments.
* **Write access required** — the commenter needs `write` or `admin` permission on the repository, and their GitHub account must be [linked to their Devin account](https://app.devin.ai/settings). Outside contributors can't trigger reviews.
* **Open PRs only** — comments on closed or merged PRs are ignored.
* **GitHub only** — including GitHub Enterprise Server and Enterprise Cloud. GitLab supports auto-review but not the comment trigger.
Other `/devin` comments (for example `/devin fix the failing test`) start a regular Devin session on the PR instead of a review.
### Starting a Review
When creating a new inline comment or replying to an existing thread, you can check the **Start a review** checkbox to batch your comments into a pending review instead of posting them individually. This mirrors the GitHub review workflow, letting you collect all your feedback before submitting. Once a review is in progress, subsequent comments are automatically added to it and the checkbox is hidden.
### Resolving Comments
You can resolve review threads to indicate they've been addressed. When all threads in a bot-authored review are resolved, Devin automatically minimizes that review on GitHub to keep the PR conversation clean. If a thread is later unresolved, the review is automatically unminimized.
In the diff view, you can expand or collapse individual comment threads using the caret toggle to focus on outstanding feedback.
### Code Owner Indicators
When a code owner has been requested as a reviewer, Devin Review displays a shield icon next to their name in the reviewer sidebar with a "Requested as code owner" tooltip. This makes it easy to identify which pending reviewers have code ownership over the changed files.
## Auto-Fix
Devin Review can automatically suggest and apply fixes for bugs it detects in your PRs. When Auto-Fix is enabled, Devin will propose code changes directly alongside its bug findings.
### How to Enable It
There are two ways to enable Auto-Fix:
1. **From the review sidebar** — On any Devin-authored PR, the Analysis sidebar shows an **Auto-fix** section with an **Enable auto-fix** button. Clicking it enables Auto-Fix for all Devin PRs in your organization. This requires organization admin permissions.
2. **From global Customization settings** — Go to [Settings > Customization](https://app.devin.ai/customization) > **Pull requests** > **Responding to bots**, then either:
* Set the mode to **Selected only** and add `devin-ai-integration[bot]` to the allowlist, or
* Set the mode to **All bots**.
When Devin Review finds bugs and Auto-Fix is enabled, it will generate suggested fixes that you can review and apply directly from the diff view.
### Permissions & Constraints
* Only organization admins can change this setting.
* If the bot mode is set to **All bots**, Auto-Fix shows as enabled and cannot be changed from the review sidebar. Use Customization settings to modify the bot mode.
* Devin Review's **No Issues Found** summary comments are always ignored. Only comments with actual findings trigger Auto-Fix.
If Devin Review feedback is currently ignored in your repository, you'll see a prompt in the session timeline to enable it.
## CLI
The Devin Review CLI lets you run code reviews directly from your terminal. This is especially useful for private repositories or when you want a streamlined local workflow.
### Installation & Usage
Run the CLI from within a local clone of the repository, no authentication required:
```bash theme={null}
cd path/to/repo
npx devin-review https://github.com/owner/repo/pull/123
```
You must run this command from within the repository being reviewed.
How it works:
1. **Git-based diff extraction** — The CLI uses your local git access to fetch the PR branch and compute the diff. This means you need read access to the repository on your machine.
2. **Isolated worktree checkout** — The CLI creates a [git worktree](https://git-scm.com/docs/git-worktree) in a cached directory to check out the PR branch. This keeps your working directory untouched -- no stashing, no branch switching. The worktree is automatically cleaned up after the review completes.
3. **Diff sent to Devin servers** — The computed diff and file contents are sent to Devin's servers for analysis.
### Privacy & Access Control
The CLI uses a **localhost server** to authenticate your review session:
* **Local-only access by default** — When you run `devin-review`, it starts a localhost server on your machine that serves a secure token. Only processes on your local machine can access this token, meaning **only you can view the review page** while logged out.
* **Transfer to your Devin account** — If you log in to a Devin account that has access to the GitHub organization, the review session is transferred to your account. This lets you access the review from other devices and share it with teammates.
When you run the CLI, `devin-review` can execute commands locally on your machine to gather additional context for finding bugs. This enables deeper analysis than diff-only review.
The Bug Catcher can execute a limited set of **read-only** operations scoped to the worktree directory:
* **File reading** — Read file contents within the repository
* **Search** — Grep for patterns and glob for file names
* **Bash commands** — Only read-only commands like `ls`, `cat`, `pwd`, `file`, `head`, `tail`, `wc`, `find`, `tree`, `stat`, and `du`
## Commit & Comment Attribution
* Bug findings, flags, and automated annotations always appear as the **Devin bot**.
* When a user writes a comment or review through Devin Review, it appears under the **user's** GitHub identity.
* When a user asks the chat agent to make a code change, the resulting commit is made as the **Devin bot**.
* **GitHub Suggested Changes** follow standard GitHub behavior: any reviewer (including Devin) can leave a suggested edit in a review comment. When a user clicks "Apply suggestion," the commit is authored by that user, in the same way as GitHub.
* Devin will **never** create commits or comments on behalf of a user without the user explicitly initiating the action.
## AGENTS.md / Instruction Files
Devin Review respects instruction files in your repository. If any of these files exist, they'll be used as context when analyzing your PR:
* `**/REVIEW.md`
* `**/AGENTS.md`
* `**/CLAUDE.md` (case-insensitive)
* `**/CONTRIBUTING.md` (case-insensitive)
* `.cursorrules`
* `.windsurfrules`
* `.cursor/rules`
* `*.rules`
* `*.mdc`
* `.coderabbit.yaml` / `.coderabbit.yml`
* `greptile.json`
Files inside agent-like subdirectories (`.agents/`, `.devin/`, `.cursor/`, `.github/`) are treated as belonging to the parent directory for scoping purposes. For example, `src/.agents/REVIEW.md` applies to files under `src/`.
These files can contain coding standards, project conventions, or other guidelines that help provide more relevant feedback.
### Custom Review Rules
You can configure additional files to be ingested as review context from [Settings > Review](https://app.devin.ai/settings/review) under the **Review Rules** section. This lets you add custom file glob patterns beyond the defaults listed above.
To add a custom rule:
1. Go to [Settings > Review](https://app.devin.ai/settings/review)
2. Under **Review Rules**, type a file glob pattern (e.g. `docs/**/*.md`)
3. Click **Add**
Custom rules appear in the list alongside the default `**/REVIEW.md` rule. You can remove any custom rule by clicking the trash icon next to it.
This is useful when your project has review-relevant documentation in non-standard locations, such as architecture decision records, style guides, or team-specific conventions stored in custom paths.
### REVIEW\.md
`REVIEW.md` is a dedicated instruction file for Devin Review. Place it anywhere in your repository to customize how Devin reviews PRs in your project. Devin automatically picks up `REVIEW.md` files at any directory level (`**/REVIEW.md`), so you can scope review guidelines to specific subdirectories if needed.
Use `REVIEW.md` to define review-specific guidelines such as:
* Areas of the codebase that need extra scrutiny
* Common pitfalls or anti-patterns to watch for
* Project-specific conventions that reviewers should enforce
* Files or directories that can be safely ignored during review
* Security or performance considerations unique to your project
**Example `REVIEW.md`:**
```markdown theme={null}
# Review Guidelines
## Critical Areas
- All changes to `src/auth/` must be reviewed for security implications.
- Database migration files should be checked for backward compatibility.
## Conventions
- API endpoints must include input validation and proper error handling.
- All public functions require TypeScript return types — do not use `any`.
- React components should use functional components with hooks, not class components.
## Ignore
- Auto-generated files in `src/generated/` do not need review.
- Lock files (package-lock.json, yarn.lock) can be skipped unless dependencies changed.
## Performance
- Flag any database queries inside loops.
- Watch for N+1 query patterns in API resolvers.
```
# Devin Session Tools
Source: https://docs.devinenterprise.com/work-with-devin/devin-session-tools
Learn how Devin's IDE, Browser, Shell, and Side Chat tools help you monitor, interact with, and guide your development sessions.
Devin provides three powerful tools during sessions that allow you to monitor, interact with, and take over Devin's work: the Shell, IDE, and Browser. These tools work together to give you full visibility and control over Devin's development environment. The Progress tab brings these tools together in one unified view, giving you clear visibility into Devin’s ongoing work.
## Progress Tab
You can click on any of the steps within a Devin session or click the Progress tab to view the details of that step. All shell commands, code edits, and browser activity will be logged in one unified view.
## Side Chats
Side chats let you ask questions about a session without interrupting Devin's main work. Start one from the hover menu on any message in the session, from the add-tab menu, or by typing `/btw your question` in the main chat box. Each side chat opens in a panel next to the worklog with all of the session's context up to that point.
Side chats are read-only: Devin can search and read the codebase to answer your questions, but it cannot edit files, run commands, or change the session's work. You can stop a response mid-answer, and the main session keeps running the whole time.
## Shell & Terminal
Devin's shell provides full command-line access to the development environment. You can monitor Devin's commands, view outputs, and run your own commands when needed.
### Command history features
With command history, you can easily see a list of all the commands that Devin ran, along with a preview of their outputs. Key features include:
* **Full command list**: View every command Devin has executed during the session
* **Output preview**: See the output of each command without switching contexts
* **Copy functionality**: Quickly copy commands and outputs to your clipboard
* **Time navigation**: Jump to different points in the session by clicking on commands
* **Integration with progress updates**: Shell commands are linked to Devin's progress updates for context
### View shell updates
During a session, you can click into Devin's progress updates to view specific shell commands Devin used while working through sub-tasks. The progress view shows shell updates in context with the work being performed.
### Shell command history
Shell updates show you the full command history and related outputs. You can easily copy a command and its output by clicking on the three-dots icon.
Commands that are greyed out are commands run at a future point in time in the session. You can jump to different points in time in the session by clicking on different commands in the Command History section.
### Running your own commands
When you take over Devin's machine, you have full terminal access. You can:
* Open a terminal in VSCode to run commands directly
* Toggle terminals from read-only to writable mode
* Run any commands you need to debug, test, or configure the environment
## Devin IDE
Devin works in an interactive VSCode environment loaded with your repos. You can check in on Devin's edits in real time, then touch up the changes or test Devin's code directly using the IDE tools and shortcuts you're familiar with.
### Reviewing Devin's work in real-time
You can watch Devin make edits in real-time. You're in a fully featured IDE complete with all your favorite shortcuts, so you can open files in new tabs, jump to definition, and more.
### Taking over Devin's task
Devin's IDE allows you to take over Devin's work when necessary, test and fix changes end-to-end without leaving the Devin webapp. Click to stop the session to take over and start using the IDE yourself. Many favorite commands are available in the IDE including:
* **Cmd/Ctrl+K** to generate terminal commands from natural language
* **Cmd/Ctrl+I** for rapid responses to questions or rapid file edits
* **Tab autocomplete** for code completion
All of Devin's terminals, commands, and their outputs are available in VSCode. Toggle from read-only to writable to run your own commands.
### IDE best practices
When taking over Devin's work, keep these tips in mind:
* Let Devin know about the changes you've made when you resume the session
* Make sure that Devin is paused before taking over the IDE to avoid simultaneous, conflicting changes
* Use Devin's browser to test the local build yourself, without leaving the webapp
## Interactive Browser
The Interactive Browser is located under the **Desktop** tab in the session UI. It allows you to directly view and interact with Devin's browser and desktop environment. This feature is especially helpful for browser tasks where Devin may require assistance, such as completing CAPTCHAs, completing multi-factor authentication steps, navigating complex websites, and more.
The tab was previously called "Browser" and has been renamed to "Desktop" to reflect Devin's full desktop environment capabilities.
### Browser use cases
The Interactive Browser is particularly useful for:
* **Testing local applications**: Test your application running on Devin's machine directly in the browser
* **Visual verification**: Verify that UI changes look correct in the browser
* **Screenshots and recordings**: Devin can capture screenshots and videos of the browser and submit them back to you as proof of testing or to show results
* **Authentication flows**: Complete login steps, MFA challenges, or OAuth flows that Devin cannot handle automatically
* **CAPTCHA solving**: Manually solve CAPTCHAs when Devin encounters them
* **Complex navigation**: Help Devin navigate through complex web interfaces or multi-step forms
### Cookie persistence
When you interact with the browser during a session, cookies and session data persist throughout the session. This means you can log into services once and Devin will maintain that authenticated state for the remainder of the session.
## Integration & Workflow
The IDE, Browser, and Shell tools work together seamlessly to provide a complete development experience.
Devin can perform diverse batches of actions concurrently, such as viewing the browser while running a shell command while reading multiple code files. This parallel execution improves speed and efficiency.
### Typical workflow
A typical workflow using these tools might look like:
1. **Start a session** and let Devin begin working
2. **Monitor progress** using progress updates
3. **Check shell commands** to understand what Devin is executing
4. **Review quick code changes** in the IDE using the diff view
5. **Functional testing** prototypes (for frontend development)
6. **Take over if needed** by stopping Devin and using the IDE directly
7. **Resume Devin** after making your changes and informing Devin what you did
## Best Practices
### When to use each tool
| Tool | Best for |
| --------------------------------- | ----------------------------------------------------- |
| **IDE** | Reviewing code changes, making quick edits, debugging |
| **Desktop** (Interactive Browser) | Frontend prototyping, visual testing, authentication |
| **Shell** | Monitoring commands, running tests, debugging issues |
### Tips for effective collaboration
* **Intervene early**: If you see Devin going in the wrong direction, stop and redirect early
* **Leverage command history**: Use shell command history to understand what Devin has tried and what worked
* **Communicate changes**: If resuming the session, always tell Devin about any changes you made when taking over
# MCP (Model Context Protocol) Marketplace
Source: https://docs.devinenterprise.com/work-with-devin/mcp
MCP is an open protocol that enables Devin to use hundreds of external tools and data sources. Devin supports 3 transport methods (stdio, SSE, and HTTP).
## Why use MCP?
With MCP, Devin can help you:
* dig through Sentry, Datadog and Vercel logs
* [use Devin as a data analyst](https://devin.ai/ai-data-analyst-1) in Slack with database MCPs
* dig into SonarQube, CircleCI, and Jam issues
* bulk create Linear tickets, Notion docs, Google Docs (through Zapier) and more
* pull in context from and interact with Airtable, Stripe, and Hubspot
* a lot more!
## Get started with MCPs
Navigate to [Settings > Connections > MCP servers](https://app.devin.ai/settings/connections?tab=mcps) to browse and enable MCPs.
Check out our step-by-step guide!
Explore practical examples of Devin with MCPs like Datadog, Sentry, Linear, Figma, and more.
## Configuration tips
For MCPs that authenticate with OAuth, Devin will prompt you to visit a URL to connect your account. How the connection is shared depends on the server's **Access** setting:
* **Organization**: all members share a single authenticated connection. **We strongly recommend connecting a service account**, not your personal account, since every member's sessions will use it.
* **Personal**: each organization member authenticates individually with their own account, so connecting your personal account is fine. Note that other users can still interact with your sessions, so this should not be treated as a security boundary.
Don't see the MCP you're looking for? Organization admins can add any MCP server using the **Add a custom MCP** button. If you don't have admin permissions, use **Suggest MCP Integration** to request one.
Having trouble? Contact us via our [support page](https://app.devin.ai/settings/support) or via [support@cognition.ai](mailto:support@cognition.ai).
## Setting up a custom MCP server
If the MCP you need isn't in the marketplace, organization admins can add any MCP server using the **Add a custom MCP** button. Devin supports three transport types for custom servers:
Adding custom MCP servers requires the **Manage MCP Servers** permission. If you don't see the **Add a custom MCP** button, contact your organization admin or use the **Suggest MCP Integration** option to request a new server.
| Transport | Best for | Required fields |
| --------- | ---------------------------------------------------- | ---------------------------- |
| **STDIO** | Local CLI-based servers (e.g., `npx`, `uvx`, Docker) | Command, args, env variables |
| **SSE** | Remote servers using Server-Sent Events | Server URL, headers |
| **HTTP** | Remote servers using Streamable HTTP | Server URL, headers |
### Step-by-step: Adding a custom MCP server
1. Navigate to [Settings > Connections > MCP servers](https://app.devin.ai/settings/connections?tab=mcps).
2. Click **Add a custom MCP** at the top of the page.
3. Fill in the server details:
* **Server Name**: A descriptive name for the server (e.g., "Internal API Gateway").
* **Icon** (optional): An emoji or URL to use as the server's icon.
* **Short Description**: A brief summary of what the server does.
4. Select the **transport type** (STDIO, SSE, or HTTP).
5. Fill in the transport-specific configuration fields (see [Configuration format](#configuration-format) below).
6. Click **Save** to create the server.
7. Click **Test listing tools** to verify the connection. Devin will spin up an isolated test environment, connect to your server, and attempt to discover its available tools.
The **Test listing tools** button is disabled until you save your configuration. If validation fails, check the error message displayed — it will indicate whether the issue is with connectivity, authentication, or a timeout.
### Configuration format
The examples below show JSON representations of each transport's configuration fields. In practice, you fill these in through the web form — you do not need to write or paste JSON. The JSON format is shown here for clarity and as a reference for API-based or programmatic setups.
#### STDIO transport
Use STDIO for servers that run as local processes. You provide the command to launch the server, along with any arguments and environment variables.
**Fields:**
* **Command** (required): The executable to run (e.g., `npx`, `uvx`, `docker`).
* **Arguments**: Command-line arguments passed to the server.
* **Environment Variables**: Key-value pairs set in the server's process environment. Use these to pass API keys, tokens, or configuration values.
**Example — a custom STDIO server using `npx`:**
```json theme={null}
{
"transport": "STDIO",
"command": "npx",
"args": ["-y", "@example/my-mcp-server"],
"env_variables": {
"API_KEY": "your-api-key",
"API_BASE_URL": "https://internal-api.example.com"
}
}
```
**Example — a custom STDIO server using Docker:**
```json theme={null}
{
"transport": "STDIO",
"command": "docker",
"args": ["run", "-i", "--rm", "-e", "DB_CONNECTION_STRING", "my-org/my-mcp-server:latest"],
"env_variables": {
"DB_CONNECTION_STRING": "postgresql://user:pass@host:5432/mydb"
}
}
```
#### SSE and HTTP transports
Use SSE or HTTP for remote servers accessible over the network. HTTP (Streamable HTTP) is recommended for new integrations; SSE is supported for legacy servers.
**Fields:**
* **Server URL** (required): The endpoint URL of the MCP server.
* **Authentication method**: Choose between `None`, `Auth Header`, or `OAuth`.
* For **Auth Header**: Provide the header key (defaults to `Authorization`) and the header value (e.g., `Bearer your-token`).
* For **OAuth**: Devin will prompt you to complete an OAuth flow during your first session. If your provider requires pre-registered OAuth applications (no dynamic client registration), supply your own client ID and secret under **OAuth credentials**, and add Devin's callback URL `https://api.devin.ai/mcp/oauth/callback` to the redirect URI allowlist in your OAuth application's settings.
* **Access** (OAuth only): Choose who uses the authenticated connection.
* **Organization**: All members share a single connection. Connect a service account rather than a personal account.
* **Personal**: Each organization member authenticates individually with their own account.
**Example — a remote HTTP server with bearer token auth:**
```json theme={null}
{
"transport": "HTTP",
"url": "https://mcp.internal-service.example.com/mcp",
"auth_method": "auth_header",
"headers": {
"Authorization": "Bearer your-api-token"
}
}
```
**Example — a remote SSE server with no auth:**
```json theme={null}
{
"transport": "SSE",
"url": "https://mcp.example.com/sse"
}
```
When choosing between SSE and HTTP, prefer **HTTP** (Streamable HTTP). SSE is a legacy protocol and is being deprecated across the MCP ecosystem.
## Common patterns
### Connecting to an internal API
Expose your internal API as an MCP server so Devin can query it directly. Use the STDIO transport with a wrapper that translates MCP tool calls into API requests.
```json theme={null}
{
"transport": "STDIO",
"command": "npx",
"args": ["-y", "@example/api-mcp-bridge"],
"env_variables": {
"API_BASE_URL": "https://api.internal.example.com",
"API_TOKEN": "your-internal-api-token"
}
}
```
Alternatively, if your internal API is reachable over the network, use the HTTP transport:
```json theme={null}
{
"transport": "HTTP",
"url": "https://api.internal.example.com/mcp",
"headers": {
"Authorization": "Bearer your-internal-api-token"
}
}
```
### Connecting to a database
Use a database MCP server to give Devin read or write access to your data. Many community-maintained servers exist for common databases.
```json theme={null}
{
"transport": "STDIO",
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-postgres", "postgresql://user:password@host:5432/database"]
}
```
For production databases, use a **read-only** connection string or a database user with restricted permissions. Devin executes queries based on user instructions, so scoping access appropriately is important.
### Connecting to a custom tool or script
Wrap any CLI tool or script as an MCP server. For example, a Python-based server using `uvx`:
```json theme={null}
{
"transport": "STDIO",
"command": "uvx",
"args": ["my-custom-mcp-server"],
"env_variables": {
"CONFIG_PATH": "/path/to/config.json"
}
}
```
Or a Docker-based server for isolated execution:
```json theme={null}
{
"transport": "STDIO",
"command": "docker",
"args": ["run", "-i", "--rm", "my-org/custom-mcp-server:latest"]
}
```
### Using environment variables for secrets
Pass sensitive values through environment variables rather than hardcoding them in arguments. Devin's [Secrets](/product-guides/secrets) feature can manage these values — store your API keys or tokens as secrets, then reference them in your MCP server configuration.
## Troubleshooting custom MCP servers
### "Test listing tools" fails
| Symptom | Likely cause | Fix |
| ------------------------------------------------------- | -------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
| "Verify server URL and network connectivity" | The server URL is unreachable | Check that the URL is correct and accessible from the internet (or from Devin's network if using VPN) |
| "Check authentication credentials and permissions" | Invalid or missing auth credentials | Verify your API key, token, or OAuth configuration |
| "Server took too long to respond - check server status" | The server didn't respond within the timeout | Ensure the server is running and responsive; check for firewall rules blocking the connection |
| "MCP server validation failed" (generic) | Command not found, missing dependencies, or server crash | For STDIO servers, verify the command exists and runs locally; check that all required env variables are set |
### Server connects but tools aren't available
* Verify the server correctly implements the MCP protocol's `tools/list` method.
* For STDIO servers, ensure the process writes valid JSON-RPC messages to stdout and reads from stdin — logging or debug output to stdout will break the protocol.
* Check that environment variables are set correctly. Missing values (e.g., a blank API key) can cause the server to start but fail to register tools.
### OAuth authentication issues
* When prompted to authenticate, complete the OAuth flow in the browser window that opens. Devin will wait for the callback.
* If authentication fails, check that the OAuth redirect URI is configured correctly on the provider side. When using your own OAuth client credentials, the provider must allow Devin's callback URL `https://api.devin.ai/mcp/oauth/callback` as a redirect URI — many providers reject the OAuth flow if this URL isn't allowlisted.
* Only users with the **Manage MCP Servers** permission can authenticate OAuth-based MCP servers. If you see a permissions error, contact your org admin.
For OAuth-based MCPs with **Organization** access, **use a service account** rather than your personal account — all members' sessions will use the same authenticated connection. With **Personal** access, each member authenticates with their own account, so a personal account is fine.
### General debugging tips
* **Check the server locally first.** Before adding a custom server to Devin, verify it works by running the command or hitting the URL from your own machine.
* **Review Devin's session logs.** If a server fails during a session, Devin will log the error. Look for MCP-related messages in the session output.
* **Simplify and iterate.** Start with the minimal configuration (e.g., no auth, default settings) and add complexity once the basic connection works.
* **Verify environment variables.** A common issue is missing or misnamed env variables. Double-check that every required variable is set in the configuration.
If you're building your own MCP server, the [Model Context Protocol specification](https://modelcontextprotocol.io/introduction) has detailed documentation on the protocol, transport types, and tool definitions.
***
## Marketplace MCPs
Below are configuration details for specific MCPs available in the marketplace.
### Vercel, Atlassian, Notion, Sentry, Neon, Asana, Jam and many more
Many MCPs in our marketplace can be enabled without configuration with 1 click!
Just click "Enable". You'll be prompted to connect a service account during your Devin session, or when you click "Test listing tools".
Available MCPs include:
* AlloyDB
* Asana
* Atlassian
* BigQuery
* Cloud SQL (MySQL)
* Cloud SQL (PostgreSQL)
* Cloud SQL (SQL Server)
* Cloudflare
* Cortex
* Dataplex
* Figma
* Fireflies
* Firestore
* Jam
* Linear
* Looker
* Metabase
* MySQL
* Neon
* Notion
* PostgreSQL
* Prisma
* Sentry
* Spanner
* SQL Server
* Vercel
* More below!
**Linear**: If you have the [Linear integration](/integrations/linear) connected, Devin already has native Linear tools and you do not need to configure the Linear MCP separately.
### Datadog
This is the official Datadog remote MCP server. When you enable it from the marketplace, you'll be prompted to authenticate with your Datadog account via OAuth.
You'll also need to select your Datadog site/region (e.g. US1, US3, US5, EU, AP1, AP2, US1-FED) when enabling the MCP.
[Documentation](https://docs.datadoghq.com/bits_ai/mcp_server/)
### Slack
This is the official Slack remote MCP server. When you enable it from the marketplace, you'll be prompted to authenticate with your Slack account via OAuth.
Note that it uses user-level OAuth: if connected with organization-wide access, all org members share the same user identity, so we recommend using personal access.
[Documentation](https://docs.slack.dev/ai/slack-mcp-server)
### Supabase
You'll need to provide a personal access token, which you can find and create at [https://supabase.com/dashboard/account/tokens](https://supabase.com/dashboard/account/tokens)
[Documentation](https://mcpservers.org/servers/supabase-community/supabase-mcp)
### Figma
This is the official Figma remote MCP server. When you enable the MCP from the marketplace, you'll be prompted to authenticate with your Figma account via OAuth.
When using this MCP, make sure to send Devin a link to your Figma file.
[Documentation](https://developers.figma.com/docs/figma-mcp-server/remote-server-installation/)
### Stripe
You'll need to provide an authorization header which follows the format `Bearer `, where `` is your Stripe API key. More info at: [https://docs.stripe.com/mcp#bearer-token](https://docs.stripe.com/mcp#bearer-token)
[Documentation](https://docs.stripe.com/mcp)
### Zapier
You'll need to provide an authorization header which follows the format `Bearer `.
You'll need to extract your Bearer token from the Server URL provided at [https://mcp.zapier.com/mcp/servers](https://mcp.zapier.com/mcp/servers) > Connect
Your Server URL will look like: [https://mcp.zapier.com/api/mcp/s/\*\*\*\*\*/mcp](https://mcp.zapier.com/api/mcp/s/*****/mcp)
Extract the starred section (\*\*\*\*\*) and use it in the authorization header you provide: `Bearer *****`
[Documentation](https://zapier.com/mcp)
### Airtable
You'll need to provide an Airtable API key. You can find your API keys at: [https://airtable.com/create/tokens](https://airtable.com/create/tokens)
[Documentation](https://www.npmjs.com/package/airtable-mcp-server)
### Docker Hub
Credentials required:
* Docker Hub username: This can be obtained from My Hub
* Personal Access Token: Go to Account settings > Personal access tokens and create a token
[Documentation](https://hub.docker.com/r/mcp/dockerhub)
### SonarQube
To get the required credentials:
* Sonarqube token: Go to my Account > Security and generate your API token
* Sonarqube org: This is your username, example shown in the below image
* Sonarqube URL:
* For self hosted: format is [http://localhost:9000](http://localhost:9000/) OR [https://sonarqube.mycompany.com](https://sonarqube.mycompany.com/)
* For SonarCloud: use [https://sonarcloud.io](https://sonarcloud.io/)
[Documentation](https://github.com/SonarSource/sonarqube-mcp-server)
### Netlify
You’ll need to provide a Personal Access Token, which you can view and create at [https://app.netlify.com/user/applications#personal-access-tokens](https://app.netlify.com/user/applications#personal-access-tokens). Make sure to copy the PAT as soon as it is created. You won't be able to see it again!
[Documentation](https://docs.netlify.com/welcome/build-with-ai/netlify-mcp-server/)
### Pulumi
A Pulumi access token can be obtained from the Access tokens section in the sidebar of the Pulumi dashboard.
[Documentation](https://www.pulumi.com/docs/iac/using-pulumi/mcp-server/)
### Parallel
You'll need to provide an API key, which you can generate at [https://platform.parallel.ai/](https://platform.parallel.ai/)
[Documentation](https://docs.parallel.ai/features/remote-mcp)
### Heroku
You’ll need to provide an API Key, which you can find at [https://dashboard.heroku.com/account](https://dashboard.heroku.com/account)
[Documentation](https://www.heroku.com/blog/introducing-official-heroku-mcp-server/)
### CircleCI
You'll need to provide 2 environment variables:
* `CIRCLECI_TOKEN` - CircleCI API Token, which can be created at [https://app.circleci.com/settings/user/tokens](https://app.circleci.com/settings/user/tokens). Make sure to copy the API token as soon as it is created. You won't be able to see it again!
* `CIRCLECI_BASE_URL` \[Optional] - This is optional and is required for on-prem customers only. The default value is `"https://circleci.com"`
[Documentation](https://hub.docker.com/r/mcp/circleci)
### Cortex
You'll need to provide a Cortex personal access token to enable this MCP:
1. Log in to your Cortex instance.
2. From the left-hand menu, go to *Settings → My access tokens*.
3. Click *Create new token*.
4. Enter a name for the token and description.
5. Click *Create token* and copy the token.
When using this MCP, make sure Devin is configured with the correct Cortex API URL (defaults to `https://api.getcortexapp.com`).
[Documentation](https://docs.cortex.io/get-started/mcp)
### Square
You'll need to provide an authorization header which follows the format `Bearer `, where `` is your Square access token. More info at: [https://developer.squareup.com/docs/build-basics/access-tokens](https://developer.squareup.com/docs/build-basics/access-tokens)
[Documentation](https://developer.squareup.com/docs/mcp)
### Hubspot
You'll need to provide an access token as an environment variable. To get your access token:
1. Create a private app in HubSpot:
2. Go to Settings > Integrations > Private Apps
3. Click "Create private app"
4. Name your app and set required scopes
5. Click "Create app"
6. Copy the generated access token from the "Auth" tab
[Documentation](https://www.npmjs.com/package/@hubspot/mcp-server)
### Redis
Required credentials:
* Redis host
* Redis port
* Redis username
* Redis password
[Documentation](https://redis.io/docs/latest/integrate/redis-mcp/client-conf/)
### Google Maps
You'll need to (1) provide an API key (2) enable the individual APIs you'd like Devin to have access to.
To get your API key, navigate to [https://console.cloud.google.com/apis/credentials](https://console.cloud.google.com/apis/credentials) and open the sidebar > APIs and services > Credentials.
To enable an individual API, search for the API and click enable.
[Documentation](https://www.npmjs.com/package/@modelcontextprotocol/server-google-maps)
### Playwright
No environment variables needed for this! Simply enable the integration.
[Documentation](https://hub.docker.com/r/mcp/playwright)
### Firecrawl
You’ll need to provide an API Key (`FIRECRAWL_API_KEY`), which you can view and create at [https://www.firecrawl.dev/app/api-keys](https://www.firecrawl.dev/app/api-keys).
[Documentation](https://hub.docker.com/r/mcp/firecrawl#use-this-mcp-server)
### ElasticSearch
You’ll need to provide 2 environment variables:
* `ES_URL` - ElasticSearch URL or endpoint, which can be found on the /overview page in Elasticsearch.
* `ES_API_KEY` - ElasticSearch API key, which can be created on the `/indices/index_details//data` page in Elasticsearch.
`ES_SSL_SKIP_VERIFY` is an optional environment variable. When set to `true` , it skips SSL/TLS certificate verification when connecting to Elasticsearch.
[Documentation](https://hub.docker.com/r/mcp/elasticsearch)
### Postgres
The only credential needed is the Postgres connection string.
[Documentation](https://www.npmjs.com/package/@modelcontextprotocol/server-postgres?activeTab=readme)
### Plaid
The only credential required is an OAuth bearer access token that can be obtained by running the following code:
```jsx theme={null}
curl -X POST https://production.plaid.com/oauth/token \
-H 'Content-Type: application/json' \
-d '{
"client_id": "YOUR_PLAID_CLIENT_ID",
"client_secret": "YOUR_PRODUCTION_SECRET",
"grant_type": "client_credentials",
"scope": "mcp:dashboard"
}'
```
To obtain the client ID and client production secret, go to [https://dashboard.plaid.com/developers/keys](https://dashboard.plaid.com/developers/keys)
[Documentation](https://plaid.com/docs/resources/mcp/)
### Replicate
The only required credential is the API token which can be found at [https://replicate.com/account/api-tokens](https://replicate.com/account/api-tokens)
[Documentation](https://replicate.com/docs/reference/mcp)
### Grafana
You'll need to provide 2 environment variables:
* Grafana URL
* Grafana service account token: To obtain the token, in the sidebar, go to Administration > Users and access > Service accounts > Add service account (if you don’t already have one added) > Add service account token
### Pinecone
NOTE: The Pinecone MCP supports only indexes with integrated embedding. Indexes for vectors you create with external embedding models are not yet supported as of 7/16/25.
The only credential required is the Pinecone API key, which can be obtained via the API keys page in the Pinecone dashboard as seen below:
### Snyk
1. First, configure the MCP server. Documentation is available [here](https://docs.snyk.io/integrations/developer-guardrails-for-agentic-workflows/quickstart-guides-for-mcp/devin-guide). Note: Make sure to add a env variable at the bottom (not listed in documentation guide).
2. Install the Snyk CLI on Devin's machine. Documentation is available [here](https://docs.snyk.io/developer-tools/snyk-cli/install-or-update-the-snyk-cli)
```jsx theme={null}
brew tap snyk/tap
brew install snyk-cli
snyk --disable-trust
```
Note: some Snyk tests require trust to operate - install on machine after homebrew is installed. Documentation is available [here](https://docs.snyk.io/integrations/developer-guardrails-for-agentic-workflows/troubleshooting-for-the-snyk-mcp-server#folder-trust).
**Tip**:
If configured correctly - the full list of Snyk scans should run on the first pass. However, depending on Framework, some scans require an “unmanaged: true” flag (ex: C++) to be passed. Currently you can set this in knowledge or during your Devin session - here’s an example:
**Tip**: We've written an [example playbook](https://app.devin.ai/settings/playbooks/163db5ecab7e47e6a82c71bf8d338678) to help you get started.
[Documentation](https://docs.snyk.io/integrations/developer-guardrails-for-agentic-workflows/quickstart-guides-for-mcp/devin-guide)
# Security Swarm
Source: https://docs.devinenterprise.com/work-with-devin/security-swarm
Find, triage, and remediate security vulnerabilities across your repositories
Security Swarm is Devin's security scanning and remediation product. It builds a threat model tailored to your code, investigates and validates potential vulnerabilities, and helps you fix findings through pull requests. It can identify vulnerabilities like remote code execution (RCE), SQL injection, path traversal, server-side request forgery (SSRF), authorization bypasses, memory-safety bugs, denial-of-service vulnerabilities, and more. It can even identify chained exploits spanning multiple files.
Security Swarm is a custom orchestration of Devins we are calling [Agentic MapReduce](https://devin.ai/blog/agentic-map-reduce). It divides your repo among parallel Devins, providing broad coverage and deep investigation while bounding cost, making it cost-effective to scan large codebases. We also [benchmarked Security Swarm](https://devin.ai/blog/security-swarm-eval) against a ground-truth set of published vulnerabilities from the GitHub Advisory Database.
To run a scan:
* Your organization must have access to the repository you want to scan.
* You need to be authorized to use Devin sessions.
* You need the **Use code scans** permission.
* To configure an Auto Scan schedule, you also need **Manage code scans** and permission to manage automations.
If you do not see **Security** in the sidebar or cannot start a scan, ask an administrator to review your role. See [Access and permissions](#access-and-permissions) for details.
## Run your first scan
1. Open **Security** in the left sidebar and click **Start scan**.
2. Under **Single repo**, choose a repository to scan.
3. Make sure **Interactive mode** is enabled.
4. Click **Run Scan**.
5. When the proposed [threat model](#interactive-mode) is ready, review it and either click **Looks good, start scanning** or provide feedback.
6. As findings appear, review the evidence and [act on the findings](#act-on-a-finding) that need attention.
For repeatable scans, create a profile that captures your scope, threat model, severity criteria, validation steps, and remediation constraints.
## Review and act on findings
Open a scan to see its findings. The page displays a list of findings on the left, grouped by severity, and the selected finding's details on the right.
The status tabs show a live count:
* **Open** — needs attention.
* **Reviewed** — has been reviewed and no longer requires action.
* **Dismissed** — was determined as a false positive or duplicate.
While a scan is running, the page updates automatically as findings arrive.
**Reviewed** is a workflow status, not confirmation that a fix was merged. A finding can be marked Reviewed manually or when a later scan determines that it is no longer present.
### What's in a finding
A finding includes:
* **Severity, status, exploitability, confidence, and category**.
* The affected **file path and code snippets**.
* A **description** of the issue and a **remediation recommendation**.
* A **sandbox validation result**, supporting evidence, and validation artifacts.
* Associated **pull requests** and their open, merged, or closed state.
* **Code owners** and notes, when available.
Treat a risky code pattern as a lead, not proof of a vulnerability. Check that the finding traces a reachable path from attacker-controlled input, accounts for validation and authorization controls, and explains a concrete security impact.
### Act on a finding
Starts a Devin session to remediate the issue and open a pull request. The session and resulting pull request are tracked on the finding.
Sends context to a feedback session that refines the scan profile for future scans. For example, explain that a reported data flow is protected by an internal gateway so future scans can account for that control.
Overrides the finding's severity, with optional context for Devin. For example, lower the severity when exploitation requires privileged internal access, and include that constraint as context.
Marks the finding as Open, Reviewed, or Dismissed. Keep a finding Open while it needs action, mark it Reviewed after triage, or dismiss it when it is a false positive or duplicate.
## Scan profiles
A scan profile controls the scan's scope and provides guidance for each stage of the scan. Every scan can use one profile. To evaluate a repository against multiple attacker personas or threat categories, run separate scans with different profiles.
A specific threat model is one of the most effective ways to keep coverage consistent across scans. Define the attacker, sensitive assets, trust boundaries, important entry points, and explicit exclusions.
Manage profiles from the **Profiles** tab on the Security page.
### Create a profile
You can create a profile in two ways:
* **Generate with Devin** — describe the application, threats, scope, exclusions, and severity standards in natural language. Devin drafts the profile for you.
* **Create manually** — fill in each profile input yourself.
Generating with Devin is a useful starting point, but review every generated field before using the profile. Leaving an optional guidance field blank applies Security Swarm's built-in behavior for that stage.
### Basic information
* **Profile name** — name the application surface or threat category, rather than the team running the scan. Example: `Multi-tenant API authorization`.
* **Description** — summarize the profile's scope and security objective. Example: `Find authentication, authorization, and tenant-isolation vulnerabilities in the public API.`
The examples below combine into a single profile for a multi-tenant API. Adapt the boundaries, commands, and severity standards to your application.
### Threat model
Describe the attacker, sensitive assets, trust boundaries, important entry points, and anything explicitly out of scope. This guidance shapes the rules Devin generates before investigation begins.
```text theme={null}
Assume an unauthenticated internet attacker or an authenticated user in one tenant.
Focus on public HTTP handlers, OAuth callbacks, API tokens, administrative actions,
and accesses to tenant-owned data. Treat internal development scripts and local-only
tools as out of scope. Prioritize authentication bypasses, cross-tenant access, token
leakage, injection, and SSRF.
```
### Investigation guidance
Define how Devin should investigate a potential issue and what evidence it should collect. Ask it to account for existing mitigations and to distinguish reachable vulnerabilities from theoretical concerns.
```text theme={null}
Trace untrusted input from the route through middleware and service layers to the
sensitive operation. Check authentication, authorization, tenant scoping, validation,
and escaping at every boundary. Identify the exact reachable path and cite the relevant
files and lines. Do not report a theoretical issue when an effective mitigation blocks
the path.
```
### Triage guidance
Define how Devin should deduplicate and prioritize findings. Include your severity criteria so results match your organization's standards.
```text theme={null}
Group findings that share the same root cause. Treat unauthenticated remote code
execution and cross-tenant write access as critical. Treat cross-tenant read access and
credential disclosure as high. Treat single-user availability issues as medium unless
they can affect shared infrastructure. Label defense-in-depth recommendations as low.
```
### Sandbox validation
Enable sandbox validation when Devin can safely build and exercise the application. Explain how to start the application, create test data, authenticate, and demonstrate the expected security boundary.
```text theme={null}
Use the repository's documented development setup. Start the API and create two
non-production tenants with one test user in each. Attempt the suspected request as a
user from the other tenant, then verify both the HTTP response and persisted data.
Do not call production services or modify production data.
```
An unsuccessful validation does not always disprove a finding. Review the validation result and artifacts to determine whether an effective mitigation blocked the exploit or the configured environment prevented Devin from completing the test.
Sandbox validation starts a separate Devin session for each finding. See [Configure sandbox validation](#configure-sandbox-validation) for environment guidance.
### Report
Enable reports when you need a summary artifact after the scan. Specify the intended audience and the information the report should emphasize.
```text theme={null}
Write an executive summary for security and engineering leads. List confirmed critical
and high findings first, followed by unvalidated findings. Include affected components,
validation status, pull request status, and a prioritized remediation plan.
```
### Remediation guidance
Specify constraints that Devin should follow when you assign a finding for remediation. Include testing expectations, compatibility requirements, and practices to avoid.
```text theme={null}
Prefer the smallest safe change and preserve existing public API behavior. Add a
regression test that fails before the fix and passes afterward. Run the affected package's
lint and test commands. Avoid major dependency upgrades unless the vulnerability cannot
be fixed safely without one.
```
### Advanced inputs
Open **Advanced** to control file scope and investigation batches:
* **Include globs** — restrict the scan to matching files. For example, `apps/api/**` and `packages/auth/**`.
* **Exclude globs** — remove irrelevant files from the selected scope. For example, `**/generated/**`, `**/vendor/**`, and `**/fixtures/**`.
* **Batch size** — control how many files with signals are grouped into each investigation batch. Leave this at its default unless you are deliberately tuning scan behavior. The accepted range is 1–500; the default is 5.
Overly broad exclusions can hide vulnerable code or remove context needed to understand a data flow. Exclude only files you are confident are irrelevant to the profile.
### Organization and enterprise profiles
New profiles are organization-scoped. Enterprise admins can later change a profile's visibility to **Enterprise**, making it available across the enterprise.
Enterprise profiles can only be edited or archived by enterprise admins. Other users with access to Security can view and use them but cannot modify them.
### Interactive mode
With **Interactive mode** enabled, Devin builds a proposed threat model and pauses before investigation. The scan page displays the proposed rules and lets you:
* **Looks good, start scanning** — accept the threat model and begin investigation.
* **Provide feedback on the threat model** — describe what to add, remove, or emphasize, then review the revised model.
Use interactive mode for the first scan of a repository and whenever its risk surface or profile changes significantly. Once the profile captures the approved guidance, routine scans can run without the pause.
### Configure sandbox validation
Sandbox validation runs only when the selected profile has sandbox validation enabled and contains validation guidance. Give Devin enough information to build, run, seed, and authenticate the application in its sandbox.
If the repository has [declarative configuration](/onboard-devin/environment/blueprints), Devin can reuse its build and installation setup. Otherwise, add the required setup commands to the profile's validation guidance.
Do not put production credentials or secret values directly in profile guidance. Use non-production test accounts and credentials already provided through your organization's environment configuration.
## Scale scanning
### Scan multiple repositories
Use the **All repos** tab in the New Scan dialog to queue scans across an organization:
1. Optionally enter a **Repository name filter**.
2. Optionally select a scan profile.
3. Keep **Skip already-scanned repos** enabled to exclude repositories already scanned with the selected profile.
4. Click **Preview**.
5. Review the matching repositories, deselect any you do not want to scan, and confirm.
The preview is a dry run. Changing the filter, profile, or skip setting invalidates the preview so you cannot confirm a stale list.
### Auto Scan
Auto Scan periodically scans commits added since the last completed scan. You can configure it:
* While starting a single-repository scan by selecting a daily, weekly, monthly, or custom schedule.
* From an existing scan by adding, editing, disabling, or immediately running its schedule.
Schedule times are shown in your local timezone.
Auto Scan is only available when [automations](/product-guides/automations) are enabled for your organization. Configuring it requires both **Manage code scans** and permission to manage automations.Auto Scans are incremental: each run only investigates the commits added since the last completed scan. Clicking **Start scan** instead defaults to a full scan of the repository scope.
### Scan new commits
Click **Scan new commits** on a completed scan to investigate commits added since its last scanned commit. Auto Scan uses the same incremental behavior, making subsequent scans less expensive than repeatedly scanning the full repository scope.
## Manage and monitor scans
Depending on the scan and its profile, the scan header can include:
* **Reports** — download reports generated for the scan.
* **Usage** — view ACUs consumed, session count, scan duration, and pull request statistics.
* **Session** — open the main Devin session that performed the scan.
* **Export as CSV** — export the scan's findings.
* **Archive** or **Unarchive** — hide the scan from or restore it to the default list.
* **Scan new commits** — start an incremental scan.
Scans run as Devin sessions and consume [ACUs](/admin/billing/usage).
### Security dashboard
After the organization completes its first scan, the Security page displays an organization-wide dashboard for the last 7, 30, or 90 days:
* **Pull request statistics** — created, merged, open, and closed pull requests, plus merge rate.
* **Findings over time** — findings grouped by severity across the selected period.
## Access and permissions
Security access is controlled through code scan permissions in the role editor:
| Permission | What it unlocks | Default roles |
| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | ---------------- |
| **View code scans** | View scans, profiles, findings, and associated scan sessions. | Admin |
| **Use code scans** | Start scans, create organization profiles, submit finding feedback, adjust findings, change finding statuses, and assign findings to Devin. | Admin |
| **Manage code scans** | Archive or unarchive scans and configure Auto Scan schedules. | Admin |
| **Manage account code scans** | Promote organization profiles to enterprise scope and edit or archive enterprise profiles. | Enterprise admin |
Starting scans, submitting feedback, and assigning findings to Devin also require permission to use Devin sessions. Auto Scan additionally requires permission to manage automations.
By default, members do not receive code scan permissions. Owners have every permission, and administrators can grant permissions to members through [custom roles](/enterprise/security-access/custom-roles).
## Compare Security Swarm with another scanner
For a useful comparison, give both scanners the same scope, threat model, severity criteria, and validation expectations. Differences in configuration can otherwise obscure differences in underlying capability.
Use profiles to encode the comparison criteria, interactive mode to confirm the generated threat model, and sandbox validation to apply the same standard of evidence to reported findings.
## FAQ
Security Swarm investigates potential vulnerabilities in the context of your repository rather than reporting risky patterns in isolation. Devin traces relevant data flows, checks for validation and authorization controls, and evaluates whether the issue has a concrete security impact.
Each finding includes a confidence level and supporting evidence. Review that evidence before acting, especially when a finding has not been validated in a sandbox.
Check the affected code, entry point, data flow, existing mitigations, stated impact, confidence, and exploitability. When sandbox validation is enabled, also review the validation result and its supporting artifacts.
If the evidence overlooks a control or claims an unsupported impact, use [Feedback](#act-on-a-finding) to provide the missing context for future scans.
Sandbox validation attempts to reproduce a finding by building and exercising the application in an isolated environment. A successful validation provides stronger evidence of exploitability, while an unsuccessful validation can identify assumptions or environment limitations that require further review.
Sandbox validation is optional and requires enough [validation guidance](#configure-sandbox-validation) for Devin to build, run, seed, and authenticate the application safely.
Security Swarm analyzes parts of the repository in parallel and combines the results into a repository-wide view. This allows it to identify relationships between components, such as one endpoint exposing an identifier required to exploit another endpoint.
Any resulting chained finding should still identify the relevant code paths and explain how the individual conditions combine into a concrete impact.
Security Swarm uses agentic analysis, so separate scans may not produce identical findings or wording. A focused scope, explicit threat model, clear severity criteria, and specific investigation guidance help keep coverage consistent.
Capture those requirements in a reusable [scan profile](#scan-profiles), use [interactive mode](#interactive-mode) to review the proposed threat model, and provide feedback when a result misses important context.
No security scanner can guarantee complete coverage. Results depend on the selected scope, profile guidance, available repository context, and whether findings can be validated in the configured environment.
Run separate scans for distinct attacker models or threat categories, keep profiles current as the application changes, and use Security Swarm alongside your existing security review and testing practices.
# Slash Commands
Source: https://docs.devinenterprise.com/work-with-devin/slash-commands
Use custom slash commands to quickly insert your organization's predefined text prompt templates and streamline your workflow with Devin
## Overview
Slash commands are shortcuts that expand into predefined text prompts when used in Devin's chat interface. They help you quickly start common workflows without typing out full instructions each time.
Slash commands are defined by your organization. If your organization hasn't created any custom commands yet, the slash command menu will be empty.
## How Slash Commands Work
When you start typing `/` in Devin's chat input, a menu appears showing your organization's available slash commands. You can:
1. Continue typing to filter the list of commands
2. Use arrow keys to navigate through options
3. Click on a command or press Enter to select it
Once selected, the slash command appears as a chip in the input field. An example for a `/deploy` command will look like the below:
/deploy ×
Clicking on the chip will expand it into the full prompt template. You can then customize the template with your specific requirements before sending it to Devin.
## Custom Slash Commands
Organizations can create custom slash commands tailored to their team's unique workflows. For example, you might create:
* A `/deploy` command with your team's deployment checklist
* A `/security-review` command with your organization's security review guidelines
* A `/onboard` command to help new team members understand your codebase
### Managing Custom Commands
Organization administrators can manage slash commands through [Settings > Customization](https://app.devin.ai/customization). This interface allows you to:
* View all of your organization's commands
* Create new custom commands with specific prompt templates
* Edit existing custom command templates
* Delete custom commands
Creating, editing, and deleting slash commands requires organization admin permissions (`ManageOrgSettings`). All organization members can use custom commands.
# Stacked PRs
Source: https://docs.devinenterprise.com/work-with-devin/stacked-prs
How Devin splits large changes into ordered, reviewable stacks of pull requests
When a task is too large to review comfortably as a single PR, Devin can split it into a **stack**: an ordered series of pull requests that make up one piece of work and land together, bottom-up. Each PR in the stack is a normal, focused PR that builds on the one below it — reviewers read one small, self-contained change at a time instead of a single monolithic diff.
Devin's stacks are built on GitHub's native stacked pull requests, so a stack is a first-class GitHub object — not a convention held together by branch naming.
Stacked PRs are supported for **GitHub.com repositories only**. GitHub
Enterprise Server, GitLab, and other providers do not have a stacked PR API.
## How a Stack Works
A stack is a patch series:
* PRs are ordered bottom-to-top. The bottom PR targets your trunk branch (e.g. `main`); every other PR's base branch is the head branch of the PR below it.
* Because each PR is diffed against the layer below it, every PR shows only its own change — nothing bleeds in from the layers above or below.
* The stack lands bottom-up. Merging a PR in the stack also merges every open PR below it, atomically, in a single operation. As lower PRs merge, GitHub automatically retargets the remaining PRs onto the trunk branch.
## When Devin Creates a Stack
Devin stacks deliberately, not opportunistically. It creates a stack only when it has intentionally decomposed one piece of work into an ordered series of PRs designed to land together — for example, a schema change, then the service layer that uses it, then the UI on top. PRs that merely happen to be based on another PR's branch are not grouped into a stack.
When Devin plans a stack, it:
1. **Announces the stack** by name before creating any PRs, so you can see the series taking shape in your session.
2. **Creates each PR** as a normal, focused PR — with its own description and its own CI — each one targeting the head branch of the PR below it.
3. **Groups the PRs into a stack** on GitHub once they exist.
Every layer is held to the same standard as any standalone PR Devin ships: a minimal, focused diff and a high-signal description written for a reviewer who hasn't seen the code.
## Keeping the Stack Coherent
A stack isn't frozen once it's created. Devin stays attached to every PR in the stack for the life of the session:
* **Conflict resolution** — If any layer develops merge conflicts with the branch below it (for example, after review feedback lands on a lower layer or the trunk moves underneath the stack), Devin is notified automatically and resolves the conflicts silently. It only asks you when a conflict reflects a substantive decision that needs your input.
* **CI across the stack** — Devin watches CI for every layer and fixes failures as they appear, tracking the readiness of the whole series rather than babysitting PRs one at a time.
* **Automatic retargeting** — As the bottom of the stack merges, GitHub retargets the remaining PRs onto trunk. No manual rebase bookkeeping is required.
## Working with Stacks
You can direct Devin's stacking behavior in a session:
* Ask Devin to split a large change into a stack, or to keep the work as a single PR.
* Ask Devin to add follow-up PRs to the top of an existing stack.
* Ask Devin to check the status of a stack — it reports each layer's state, CI, review decision, and mergeability.
* Ask Devin to **unstack** — the stack is dissolved and its unmerged PRs become independent PRs again, with their branches left as-is. Already-merged layers stay merged.
In the session view, PRs that belong to a stack show their stack membership, and announced stacks appear before their PRs exist so you can follow along as Devin builds the series.
## Reviewing and Merging Stacks
[Devin Review](/work-with-devin/devin-review#stacked-prs) treats stacks as first-class: the whole series is visible at a glance with per-layer readiness, and merging happens through the atomic bottom-up stack merge. See the [Stacked PRs section of the Devin Review docs](/work-with-devin/devin-review#stacked-prs) for details.
## Limitations
* **GitHub.com only** — stacks are not available on GitHub Enterprise Server, GitLab, Bitbucket, or Azure DevOps.
* **Stack size** — a stack contains between 2 and 100 PRs.
* **Merging** — stacked PRs cannot be merged through GitHub's regular merge flow; they merge through the stack merge, which lands the selected PR and every open PR below it together.
# Testing & Video Recordings
Source: https://docs.devinenterprise.com/work-with-devin/testing-and-recordings
How Devin tests your changes end-to-end and sends you video recordings as proof
Devin can test your application end-to-end after creating a PR — running the app locally, interacting with it through the browser, and recording a video of the entire process. The recording is sent directly to you as an attachment so you can verify the changes work without pulling the branch yourself.
## How It Works
After Devin creates a PR, it can enter **testing mode** — a structured workflow where Devin:
1. **Sets up the environment** — installs dependencies, starts services, logs into required accounts
2. **Plans the test** — reads the diff and codebase to create a minimal, focused test plan
3. **Records a video** — starts a screen recording, executes the test plan in the desktop, and annotates key moments
4. **Sends you the result** — stops the recording, processes the video, and sends it to you as a message attachment
The goal is a short recording that a code reviewer watches and immediately thinks "yep, it works" — then merges the PR.
## Triggering a Test
After creating a PR, Devin will offer to test the app for you. Click **Test the app** to have Devin start the testing workflow.
A setting to automatically run testing after PR creation — without needing to click the button — is coming soon.
You can also ask Devin to test at any point during a session — for example, "test the changes you just made and send me a recording" or "verify the login page works and send me a video."
## The Testing Workflow
When Devin enters testing mode, it follows a structured three-phase process:
### Phase 1: Setup
Before any testing begins, Devin prepares the environment:
* **Reads the PR and codebase** to understand what needs testing
* **Checks for relevant skills** in the repo (under `.agents/skills/`) and follows them if found
* **Logs into required services** and resolves access issues
* **Checks available environments** (staging, dev, local) and verifies connectivity
* **Requests missing secrets** from you if needed — Devin will ask for credentials up front and save them for future sessions
Completing [environment configuration](/onboard-devin/environment) ahead of time makes testing much faster — Devin can skip installing dependencies, configuring services, and logging in at the start of each session.When Devin asks for credentials during testing, it saves them as [secrets](/product-guides/secrets) for future sessions so you only need to provide them once.
### Phase 2: Test planning
Once setup is complete, Devin writes a short test plan:
* Identifies the **single most important end-to-end flow** that proves the feature works
* Writes concrete, unambiguous steps (e.g., "click the button labeled Save at the top right" — not "find the save option")
* Grounds the plan in actual code — traces through the frontend to find the exact UI path to the feature
* Only adds additional test flows if there's a genuinely critical edge case
Devin sends you the plan as a short message before executing, so you can course-correct if needed.
### Phase 3: Recording and execution
After CI is green and any review comments are addressed, Devin executes the test:
1. **Starts recording** — captures the full screen
2. **Annotates key moments** — adds text labels at important points (e.g., "Testing login flow", "Feature confirmed working") that appear in the final video
3. **Executes the test plan** — interacts with the app through the browser, following each step
4. **Stops recording** — the video is automatically processed with annotations and speed adjustments around key moments
5. **Sends the video** — attaches the recording to a message so you can watch it directly
## Video Recording Details
Devin's screen recordings have several features that make them useful for review:
* **Annotations** — Text labels appear at key moments in the video, marking what Devin is testing. The video slows down around annotated points so you can see the details.
* **Auto-zoom** — The video automatically zooms into where Devin clicks and interacts, smoothly panning to follow the cursor and easing back out during idle moments.
* **Automatic processing** — Raw recordings are processed to highlight important actions and compress idle time
* **Sent as attachments** — Videos are attached to messages in your session, viewable directly in the Devin webapp or Slack
Recordings are designed to be short and focused — a **quick sanity check** with one primary end-to-end flow that proves the feature works. If you need more exhaustive coverage, use your existing test suites and CI rather than visual recording.
## Skill Suggestions
After testing your app, Devin writes down what it tried and what worked — setup steps, environment configuration, how to start the app — and proposes creating or updating a [Skill](/product-guides/skills) via PR. You can merge the PR as-is or tweak it to refine the instructions. Over time, this means Devin gets better at testing your project — each session's learnings build on the last.
You can also prompt Devin to do this at any time (e.g., "create a skill for how to test this app"). See the [Skills guide](/product-guides/skills) for full details on creating and managing skills.
Here's an example of a testing skill:
```markdown theme={null}
---
name: test-before-pr
description: Run the local dev server and verify pages before opening any PR that touches frontend code.
---
## Setup
1. Install dependencies: `npm install`
2. Start the database: `docker-compose up -d postgres`
3. Run migrations: `npx prisma migrate dev`
4. Start the dev server: `npm run dev`
5. Wait for "Ready on http://localhost:3000"
## Verify
1. Read the git diff to identify which pages changed
2. Open each affected page in the browser
3. Check for: console errors, layout issues, broken links
4. Screenshot each page at desktop (1280px) and mobile (375px) widths
## Before Opening the PR
1. Run `npm run lint` and fix any issues
2. Run `npm test` and confirm all tests pass
3. Include screenshots in the PR description
```
When writing or refining skills, be specific about what to verify:
* "Test the checkout flow: add an item to cart, go to checkout, fill in the form, and verify the order confirmation page shows the correct total"
* "Verify the dark mode toggle works on the settings page — text should be readable and no elements should disappear"
* "Test that the CSV export downloads a file with the correct headers"
* "Test everything"
* "Make sure the app works"
* "Check that nothing is broken"
## Troubleshooting
### Devin didn't offer to test
Testing mode is available on sessions where Devin creates a PR with code changes. If Devin didn't offer, you can always ask directly: "Can you test these changes and record a video?"
### Recording failed
If the recording fails to process, Devin will let you know. Common causes include the app crashing during testing or the video processing timing out. Devin can retry — just ask "Try recording again." Recording files are stored on Devin's machine, and Devin can send them to you at any time if you ask.
### Devin can't access the app
If Devin can't reach your app during testing (e.g., login walls, VPN requirements), it will ask you for help. Provide credentials using [secrets](/product-guides/secrets), use the [Interactive Browser](/work-with-devin/devin-session-tools#interactive-browser) to complete authentication steps manually, or complete [environment configuration](/onboard-devin/environment) to pre-configure access so Devin doesn't run into these issues.
# Changelog (Stable)
Source: https://docs.devinenterprise.com/cli/changelog/stable
Release notes for the Devin CLI stable channel: new features, improvements, and fixes in each stable release of the command-line interface.
### Changed
* `/share` now displays the share URL returned by the Devin server, so the link always matches where the server hosts the share; the CLI only builds the URL itself when talking to older servers.
### Fixed
* MCP servers whose protected-resource metadata lists `resource` as an array, such as self-hosted GitLab servers at `/api/v4/mcp`, now complete OAuth discovery instead of failing with an authorization-server issuer mismatch.
### Added
* `devin auth status` now shows the primary organization for enterprise accounts.
* Nested `AGENTS.md` files, lowercase `agents.md` files, and rules in supported dot-directories are now discovered and remain scoped to the directory where they apply.
* Completed `ask_user_question` prompts now appear as `/steps` entries that you can revert to or fork from. Reverting to a question asks it again.
* Press Esc twice within three seconds to interrupt a running turn; Ctrl+C still interrupts on the first press.
### Removed
* We have removed the shell integration feature. It was in preview and we have decided not to make it generally available. Use `devin shell remove` to clean up old integration blocks.
### Changed
* Slash-command completion descriptions now appear for every result in a consistent aligned column.
* `/add-dir` now checks workspace trust before attaching an untrusted directory, makes attached directories writable in the OS sandbox, and revokes that access when they are removed. Skills from attached directories also appear immediately in slash-command completion.
* Plugin installation now uses personal plugins by default, syncing to Devin Cloud and other devices; use `--local` for a device-only install.
* All `devin plugins` commands now require login, and plugin MCP servers discovered after a workspace root is attached or first touched now register correctly.
* Permission denials now identify the layer responsible.
* Plan mode now uses the normal permission system, and "always allow" choices appear only when they can take effect.
* ACP session persistence and resume now restore titles, modes, and usage totals consistently. `/continue` resolves the most recent session, `/fork` defaults to the latest step, and ACP revert can cancel an active turn before rewinding.
* `/fast` now selects SWE-1.7 Lightning when available, falling back to SWE-1.6 Fast or other fast models.
* Quota-exhaustion messages now link to usage settings for on-demand usage and auto-reload.
### Fixed
* Ensured `ask_user_question` requests now use standard ACP elicitation so third-party clients like Zed can answer them.
* Large-file reads through ACP are bounded and paginated instead of repeatedly rereading overflow files. Late terminal flushes now preserve complete output and cannot reopen completed command cards.
* Model refusals now show a warning instead of silently ending a turn, and image prompts continue to inference after captioning completes.
* Resuming, continuing, or reverting a session no longer duplicates workspace context, and skill invocations can be repeated after a session restart.
* Non-UTF-8 command output is reported with the real output and exit code.
* Linux sandbox startup no longer hangs while expanding filesystem globs; unsupported glob rules are ignored and logged, while trailing `/**` continues to cover a directory tree.
* Notebook edits now change only the target cell and preserve unrelated metadata, outputs, attachments, ids, and fields.
* Uninstalling a plugin also removes and stops its MCP servers, and plugin registries are now flushed safely before replacement so crashes cannot erase them.
* Shell commands blocked on a `sudo` password prompt now fail fast with an explanation instead of hanging.
* Smart mode and other flag-gated features now refresh immediately when authentication or team context changes.
### Fixed
* The `edit`, `write`, `apply_patch`, and `notebook_edit` tools now refuse to write through a symlink, so an approved edit can no longer be redirected to an unexpected location.
### Added
* New `smart` permission mode: workspace edits auto-approve like Accept Edits, and a fast model decides whether other actions (shell commands, fetches, out-of-workspace writes) are safe to auto-run, falling back to the normal prompt otherwise. Auto-approval is limited to routine development work (building, testing, linting) — package installs, downloads that execute code, mutating `git`, `rm`, `sudo`, `kubectl delete`, cloud CLIs, and anything destructive always prompt, as do sensitive paths (dotenv, key material, Git config, agent configuration). Switch with `/smart`, `/mode smart`, Shift+Tab, or `--permission-mode smart`. Available in all builds, off unless the server-side rollout flag is enabled for your client.
* Plugins can now contribute rules, hooks, MCP servers, and custom subagents, not just skills. Plugin `AGENTS.md`/`AGENT.md`/`.windsurfrules` load as always-on rules, `hooks.json` loads alongside project hooks, MCP servers declared via a root `.mcp.json` or an inline manifest `mcpServers` map run for the session, and `agents//AGENT.md` files surface as `:` subagent profiles. `devin plugins info` and the install trust prompt list all of them before you confirm, and `devin rules list` / `devin mcp list` include them.
* New plugin sources and manifest options: the `git-subdir` source kind installs a plugin living in a subdirectory of a shared repo (`devin plugins install acme/vendor-plugins#plugins/stripe`), a `skills` manifest field controls where skills load from (or disables them with `[]`), and a Claude-compatible `.claude-plugin/plugin.json` manifest is used when no `.devin-plugin/plugin.json` is present.
* MCP prompts support: prompts offered by connected MCP servers are available as `/mcp____` slash commands, with arguments mapped positionally onto the prompt's declared arguments.
* Editable command approvals: the shell-command permission prompt now offers "Edit command" to tweak the proposed command inline before approving, and "Describe change to command" to have a fast model rewrite it in plain language (out-of-band — nothing enters the conversation) for review. ACP clients get the same affordances.
* Command permission prompts now offer a global "Yes, always allow `` commands in all projects" option saved to the user-level `config.json`, alongside the existing per-project option. Web-fetch prompts gained an equivalent "always allow all web fetches" option.
* Configurable keybindings via a `keymap` section in `config.json`, keyed by context then action (e.g. `{ "keymap": { "global": { "clear_screen": "ctrl-shift-k" } } }`). `/shortcuts` now lists every binding across all contexts, shows each action's `context.action` identifier, and lets you rebind interactively. `Ctrl+C` cannot be unbound.
* Copilot agent skills are discovered automatically from `.github/skills/` and `~/.copilot/skills/`, toggled with the `copilot` key under `read_config_from`.
* New `subagents_enabled` setting in `config.json` (on by default) turns the `run_subagent` / `read_subagent` tools off; changes apply live to the running session.
* In plan mode, a megaplan keyword (`megaplan`, `ultraplan`, `masterplan`) triggers extra planning guidance: the agent plans more extensively and always asks at least one clarifying question before writing the plan.
* Old log files are gzip-compressed on startup — logs from finished processes untouched for 48 hours become `.log.gz` (still searchable with `zgrep`/`rg -z`).
* Administrators can configure the CLI's outbound HTTP proxy through the MDM-distributed enterprise policy file (`system.json`); it takes precedence over the user config, and the updater honors it too.
* `devin acp --model ` (or `DEVIN_MODEL`) sets the default model for every session the ACP server creates, matched the same way `/model` matches it. `devin acp --cloud` (insiders) relays the ACP connection to Devin cloud instead of running the local agent.
* `/btw`, `/loop`, `/mcp`, `/context`, `/add-dir`, `/undo-add-dir`, and `/workspace` are now advertised as agent-side ACP slash commands, so any ACP client (Devin Desktop, JetBrains, or Zed) can invoke them and their progress streams back as session updates. `/remove-dir` and `/workspaces` were added as second names for `/undo-add-dir` and `/workspace`.
### Changed
* MCP servers now live in dedicated config files — `~/.config/devin/mcp_config.json` (`%APPDATA%\devin\mcp_config.json` on Windows), `.devin/mcp_config.json`, and `.devin/mcp_config.local.json` — instead of the `mcpServers` key of `config.json`. Existing `mcpServers` entries in `config.json` are migrated automatically on startup. See [MCP Configuration](/cli/extensibility/mcp/configuration).
* Shell commands run by the agent now inherit your login shell's environment (`.bashrc`/`.zshrc`/`.zprofile`/fish config), so nvm, pyenv, rbenv, direnv, and custom PATH entries just work. Snapshotted once per session; macOS/Linux only.
* Plan mode now allows read-only MCP tools (those annotated `readOnlyHint: true`) plus listing MCP servers, tools, and resources, so the agent can gather context while planning.
* Relative plugin references (`./path`) in manifests and repo plugin configs now resolve against the entity that declares them rather than the process working directory — including `forbiddenPlugins` deny entries, which previously matched nothing. Manifests with unresolvable relative references now fail to parse instead of carrying a silently dead entry.
* Organization sandbox enforcement now applies to running sessions: team settings are refreshed at each prompt, and turning on required sandboxing mid-session refuses further prompts with a message asking you to restart.
* `/session-stats` renders every usage dimension the server reports — credits, ACUs, agent messages, turn continuations, token usage — using the server's own labels and grouping, the `Model` row names the model that actually served the billed turns, and totals persist across resume.
* Automatic context compaction is no longer surfaced in the scrollback or the ACP conversation view; an explicit `/compact` still confirms in the transcript.
### Fixed
* Interrupting the agent now pauses running subagents instead of leaving them working in the background: they park with their state intact and resume on your next message. Subagent activity also survives a session reload, and a subagent's approval prompt now shows the command and names the requesting subagent.
* Sending a queued message immediately (Enter on an empty input while Devin is working) actually interrupts the current turn instead of leaving the message queued until the turn finished.
* Exiting plan mode now injects an explicit mode-change announcement, so the agent reliably starts acting in the new mode instead of continuing to follow plan-mode restrictions from earlier in the conversation.
* Permission rules with recursive globs (e.g. `deny: ["Read(/etc/**)"]`) now also cover the base directory itself.
* On Windows, `Deny` rules now block a forbidden command hidden behind a safe leading command in a `&&`, `||`, or `&` chain (e.g. `Get-ChildItem && git push`); the PowerShell parser previously collapsed these into a single scope.
* When running sandboxed through an ACP client, commands reaching a network host outside the sandbox allow list now surface a permission prompt instead of being silently blocked.
* `apply_patch` no longer rewrites a whole Windows (CRLF) file's line endings to LF, so a one-line edit no longer produces a whole-file diff.
* `@` file mentions pick up files created, moved, or deleted while the CLI is running instead of showing a stale snapshot from startup.
* Attached images tell the model where the file lives on disk.
* Reverting removes the empty directories Devin created to hold a new file (only ones it created, and only while empty), and `/revert` no longer ends the session with an "already open in another process" lock error.
* The context window usage indicator appears immediately after resuming an old session, and revert steps are available as soon as a session is reopened.
* The ACP server stays responsive while opening, listing, saving, or updating sessions — persistence runs on a dedicated database thread with a reused connection instead of blocking the async runtime.
* ACP resource links and inline `` links show the file's basename on Windows and build well-formed, percent-encoded `file://` URIs (`file:///C:/Users/you/file.txt`) instead of malformed backslash paths.
* Skipping some questions in an `ask_user_question` will no longer block progress.
* Claude-format hooks that block by exiting with code 2 now take their block reason from stderr, matching Claude Code's convention.
* The `exec` tool rejects empty commands with an error instead of silently reporting success, preventing repeated empty-command loops.
* The "Update vX available!" banner will never advertise a version older than the one you're running.
### Outposts
* `devin worker start` no longer requires a pre-provisioned outposts token: with no `--token` / `DEVIN_OUTPOSTS_TOKEN` it creates an outpost with your CLI login and reuses the saved worker token on later runs.
* `devin worker start` downloads the correct `devin-remote` binary on Windows x64 and passes the Windows system environment through, fixing the immediate `os error 10106` crash on every Windows outpost session. It also accepts an outpost name as well as an id, and fails fast on an OS mismatch instead of repeatedly claiming and releasing queued sessions.
### Added
* MCP servers can now override the RFC 8707 OAuth `resource` parameter via a new `oauthResource` field in the MCP server config (or `--oauth-resource` on `devin mcp add` / `devin mcp login`) — needed for identity providers like Microsoft Entra that reject requests containing `resource`.
* Command hooks now receive the agent's session id (`session_id` for Claude-format hooks, `trajectory_id` for Windsurf-format hooks) and a per-turn id (`prompt_id` / `execution_id`) in their stdin payload.
### Changed
* Command permission prompts now scope known program runners to the wrapped program: `uv run ruff check` offers to always allow `uv run ruff` rather than the much broader `uv run`. Also applies to `poetry run`, `pdm run`, `pipenv run`, `rye run`, `hatch run`, `pnpm exec`, `pnpm dlx`, `npm exec`, `yarn dlx`, and `bun run`.
* Sessions now start faster, especially when several reconnect at once.
* The `devin migrate` command (`devin migrate hooks`, `devin migrate workflows`) is now available for migrating from legacy Cascade.
* When the same skill name is loaded from more than one location, each copy now surfaces with a location prefix (`/agents:foo`, `/claude:foo`) instead of appearing as indistinguishable duplicates.
### Fixed
* Hooks are now discovered in ancestor directories up to the repository root, matching how skills and rules are loaded.
* Improved support for deleting and renaming files with GPT-5.6 models.
* Image-heavy sessions no longer invalidate the provider prompt cache on every request once the trailing-image cap is reached; older images are evicted in batches, reducing token costs and latency in long sessions.
* The CLI no longer leaks a terminal/PTY per tool call: one-shot foreground commands free their shell session as soon as the command finishes, and deliberately retained shells (explicit `shell_id`, `tty`, or backgrounded commands) are capped at 16 with least-recently-used eviction.
* Reusing a shell id for a non-interactive command now works instead of failing with "This shell may not be functional"; a busy shell serializes the next command.
* Hooks are now deduplicated by source file, so a hook no longer runs multiple times when the same directory is re-added, workspace directories overlap, or a hook file is reached through a symlink.
* Telemetry: rejected, blocked, or permission-denied tool calls are now recorded with their actual failure reason instead of being mislabelled "turn complete".
### Fixed
* Fixes issues with diff viewing in autonomous mode.
### Added
* Added an `/mcp` slash command with a live MCP server status panel.
* ACU usage is now shown in the `/usage` command.
* Enterprise login policies are now enforced in the CLI.
* Added a `sandbox.excluded` allow/ask/deny config (user and team settings) to run specific commands outside the sandbox; excluded commands also skip the sandbox proxy environment.
### Changed
* Edits produced in autonomous mode now produce reviewable diffs.
* Skill `permissions:` frontmatter now applies to auto-approvals.
### Fixed
* Fixed command approval parsing for PowerShell `$variable` assignment prefixes.
### Added
* Subagents can now be configured with a default model.
* Added an `attribution` option to the Devin Local [config file](/cli/reference/configuration/config-file); set it to `false` to suppress Devin mentions in commit messages.
### Changed
* The MCP registry cache is now warmed during startup, so MCP servers are ready sooner.
### Fixed
* On Windows, `bash` now resolves to Git Bash instead of the WSL launcher stub.
* Injected context is no longer included in auto-generated session titles.
* Fixed full-width wrapping of CLI question replies.
### Fixed
* Made MCP registry parsing more tolerant of old and inconsistent schemas.
### Fixed
* Fixed a bug with loading skill files that use alternative fields.
### Plugins
Install bundles of skills from a GitHub repo, a git URL, or a local folder, and share them across projects. A plugin is any source containing a `.devin-plugin/plugin.json` manifest and a `skills/` directory; its skills become available as `/:`. A plugin can require other plugins (installed automatically), endorse optional ones, and forbid others — so a plugin can act as a curated, governed collection. Plugins are in beta and opt-in for enterprises, so behavior and configuration may change in future releases. See the [plugins overview](/cli/extensibility/plugins/overview) for details.
### Enterprise controls
Expanded controls for admins to govern what Devin Local can do and which tools it can reach.
* Teams can define terminal command allow/deny lists, enforced through CLI permission scopes with exact-command matching and `*` wildcards.
* Org-level control to disable Devin CLI plugins: when set, the CLI refuses to install or update plugins and skips the skills from any installed plugins.
* The "Disable CLI access" team setting is now enforced for Devin Local (the CLI hosted in Windsurf), including the bundled agent registry and the allowed-MCP-server allowlist.
### Added
* `devin plugins install ` installs a plugin (and its required plugins) from a GitHub `owner/repo`, a git URL, or a local path.
* `devin plugins list` shows installed plugins with their version and whether they are currently blocked by policy.
* `devin plugins info ` shows the skills a plugin provides and its required, optional, and forbidden lists.
* `devin plugins update [plugin]` re-fetches a plugin (or all plugins) at the latest version; local plugins are linked to their source folder so edits are live without re-installing.
* `devin plugins remove ` uninstalls a plugin, leaving any auto-installed required plugins in place.
* `forbiddenPlugins` entries accept glob patterns (e.g. `acme/*`, `*/secrets`, `https://gitlab.com/acme/*`) in addition to exact identities and the lone `*` lockdown.
### Changed
* Improved authentication in third-party ACP clients, including JetBrains and Zed: both browser and manual sign-in now use the Devin auth flow, so the manual `/login` fallback works where it previously failed.
### Fixed
* Signing in to Devin now honors the `proxy` settings in `config.json` (`mode`, `url`, `no_proxy`). Previously the login token exchange always connected directly (apart from `HTTP_PROXY`/`HTTPS_PROXY` env vars), ignoring a configured `manual` proxy URL, `off` mode, and config-level `no_proxy`.
### Fixed
* Custom HTTP headers are now forwarded through the MCP OAuth discovery and authorization flows, so MCP servers behind a gateway that requires extra headers (e.g. an authorization header) can complete OAuth sign-in.
* Built-in MCP OAuth strategies (such as Figma's) are now matched by issuer rather than gateway hostname, so they resolve correctly when the server is reached through a gateway or proxy.
### Fixed
* IDE editor context (active file, cursor position, open tabs) now includes explicit relevance guidance, so the agent no longer treats passive code browsing as a request to act on the focused file.
* IDE editor context (active file, cursor position, open tabs) is now injected once alongside each user message instead of being repeated before every model response, so the agent no longer narrates whether the open IDE files are related to the request.
### Fixed
* Starting Devin CLI and exiting without sending a message no longer leaves an empty "Untitled" session in `devin list`; sessions are saved once you send your first message.
### Added
* Gemini 3.5 Flash model support.
* New `/cloud-attach ` command to attach to an existing cloud Devin session with full TUI rendering (tool calls, messages, plans, file edits). The existing `/handoff` behavior is unchanged.
* New `/cloud-sessions [--all]` command to list recent cloud Devin sessions and their attachable session IDs.
* Custom subagent profiles can opt in to nested subagent spawning via the `max-nesting` frontmatter field, overriding the default depth limit.
* Supported editor integrations, including Windsurf, now show the agent which file you have open, your cursor position, and other open editor tabs as part of its context.
* `--export` flag for exporting conversation history in ATIF format.
* New `/fast` slash command to quickly switch to SWE-1.6 Fast, with pricing comparison against the current model.
* Figma MCP servers can now authenticate with `devin mcp add figma --url https://mcp.figma.com/v1` without additional configuration.
* When prompted for an MCP tool permission, two additional server-level options are now offered: approve all tools on the server for the current session, or permanently. This lets you grant broader access without re-approving each tool individually.
* Prompt navigation and collapsible command sections in terminals with shell integration. VS Code, Windsurf, Ghostty, iTerm2, kitty, WezTerm, and Windows Terminal users can now jump between prompts with keyboard shortcuts (e.g. Ctrl+Shift+Up/Down in VS Code), see prompt markers in the scrollbar, and collapse agent output sections (iTerm2). Prompt marks also survive session restore.
* Revert preview now shows line diff stats (`+N -M`) and a "View diff" button for all action types (restore, delete, recreate).
* `show_hints` config option to suppress "Did you know" tips between turns (default: on)
### Changed
* Long conversations are compacted earlier in the background so the agent spends less time pausing when context is nearly full.
* ATIF exports now include richer per-step transcript details, including telemetry and timing metrics.
* Shell commands that continue running in the background after a timeout now report how long Devin waited before returning.
* The built-in Explore subagent can now use web search to research topics outside the codebase, in addition to its read-only codebase tools. It still cannot fetch arbitrary URLs or edit files.
* Homebrew installations are now externally-managed. The `/update` command will direct users to upgrade via `brew upgrade devin` instead of attempting self-update.
* HTTP MCP servers now try Streamable HTTP first and automatically fall back to legacy SSE when the server responds with an HTTP 4xx error, per the [MCP spec](https://spec.modelcontextprotocol.io/specification/2025-03-26/basic/transports/#backwards-compatibility).
* MCP OAuth callback pages now show Devin-branded success and failure screens instead of plain text.
* Renamed the product from "Devin for Terminal" to "Devin CLI" in user-facing UI, the REPL welcome and startup banner, slash command descriptions (`/bug`), bug report output, cloud handoff messages, version self-manage messages, tips, and public documentation. The binary name, config paths, and install URLs are unchanged.
* Revert preview now shows descriptive warnings for irreversible actions instead of empty placeholders.
* Read-only shell commands (e.g. `ls`, `cat`, `pwd`) no longer trigger irreversible action warnings during revert.
* Shell integration startup is faster, reducing noticeable delay when opening a shell.
* Trimmed the first-run welcome message for Devin CLI.
* Windows: default non-interactive shell is now PowerShell instead of Git Bash. Git for Windows is no longer required to run Devin CLI on Windows.
### Fixed
* Image attachments in Windsurf now show the correct warning when the selected Devin CLI model does not support images.
* Responses silently truncated when the model hits its max output token limit now show a warning and exit non-zero in pipe mode instead of returning partial output as if complete.
* Persist the reduced trailing-image cap across turns after HTTP 413; prevents the cap from resetting to 20 each turn and triggering repeated 413 cycles
* Re-encode bmp/tiff/ico images to PNG at the message-forest chokepoint instead of forwarding them to Anthropic with an unsupported `mime_type`, which surfaced as `messages.N.content.0.image.source.base64.media_type: Input should be 'image/jpeg', 'image/png', 'image/gif' or 'image/webp'` 400 errors.
* Drop oversize (>5 MB) images whose bytes can't be fully decoded instead of passing them through verbatim, which surfaced as `image exceeds 5 MB maximum` 400 errors.
* Typing into a multiple-choice question's "Other (type your own)" field no longer drops `e`/space or treats `j`/`k`/digits as shortcuts; all characters now insert into the answer.
* Plan mode is now available when your organization requires sandbox mode. Previously `/plan` and `/mode plan` were rejected with "Plan mode is not available", even though plan mode is read-only.
* Pre-user-prompt hooks that exit with code 2 now correctly block the prompt instead of being silently ignored.
* Reverting a step no longer reports a spurious "file was modified externally" conflict for files where the agent's edit was rejected in the IDE.
* Reverting or editing a cancelled prompt (stopped before any output streamed) no longer fails with "could not resolve step."
* Sandbox mode no longer leaves empty ghost dotfiles (`.bashrc`, `.gitconfig`, `.mcp.json`, etc.) in the project directory after commands finish.
* The in-session `skill` tool now finds skills behind symlinked directories under `.windsurf/skills/`, `.agents/skills/`, and `.claude/skills/`, matching `devin skills list`.
* `/handoff` now collects untracked files from the entire repository, not just the current subdirectory
* `/handoff` now includes untracked files in the git diff sent to cloud Devin, not just tracked changes
* "Always Allow" permission grants in Windsurf now persist across sessions. Previously, selecting "Always Allow" in the ACP permission dialog only granted the scope for the current session.
### Web search
Search the web directly from your Devin CLI sessions. The agent can
look up documentation, find solutions, and pull in relevant information
from the internet without leaving the terminal.
### Added
* Built-in OAuth device flow for GitHub MCP server. `devin mcp add github --url https://api.githubcopilot.com/mcp/` now authenticates via device flow (enter a code at github.com/login/device) without needing `--oauth-client-id`.
* `/copy` command to copy the last agent response to the system clipboard. Works over SSH connections and on Linux desktops.
* Numbered options in select prompts can now be picked directly with the `1`-`9` keys instead of arrowing + Enter. The shortcut is shown as a digit prefix on each option in non-search prompts.
* `web_search` tool for searching the web during agent sessions.
### Fixed
* Cancelling a session now also stops running subagents instead of letting them continue in the background
* Shell commands that redirect output to `/dev/null` (e.g. `2>/dev/null`, `>/dev/null`, `&>/dev/null`) no longer prompt for write permission to `/dev/null`.
* Edit tool previews now show correct file line numbers instead of always starting from 1.
* Output token limit raised from 16k to match each model's actual capacity (128k for Opus, 64k for Sonnet), preventing premature response truncation.
* Option+Backspace now correctly deletes words in select menus (user question "Other" field and search) on BS-mode terminals, instead of inserting 'h'.
* Slash command output now has consistent visual separation from the prompt, matching how agent responses are displayed.
### Added
* `skill search` can find model-invocable skills recursively under a project path and filter them by keywords.
### Changed
* Default model is now SWE 1.6 Fast instead of Adaptive.
### Fixed
* `apply_patch` diffs now appear incrementally as the patch is being written, not just after it completes. Both new-file and modify-existing-file patches show diffs progressively.
* Command hints now show the binary name used to launch Devin CLI when run through a renamed binary, symlink, or alias.
* Fixed process hang when MCP OAuth dynamic client registration fails. The local callback server was not properly shut down on error, causing the process to block indefinitely waiting for a browser redirect that would never arrive.
* `/steps`, `/revert`, and `/fork` now show and work with steps from before compaction. Previously, compacting a session made all earlier steps invisible and unrevertible.
* Text now correctly appears before tool calls in scrollback when both are produced in the same streaming turn.
### Fixed
* `/usage` command now shows quota % remaining and overage balance for quota-billing users instead of "no credits consumed."
***
bumps:
chisel: minor
config-importers: minor
-----------------------
Added MCP config import support for OpenCode, VS Code, and Zed editors.
Added Cursor global MCP config loading (`~/.cursor/mcp.json`).
New providers can be toggled via `read_config_from` in user config.
### Added
* File edits from `apply_patch` now display as inline diffs in Windsurf, matching the diff preview already shown for the `edit` tool.
* `/login-status` command to show login debugging info (email, plan, team).
* New `post_compaction` hook event that fires after context compaction, with the compaction summary available on stdin.
### Changed
* Permission prompts now use clearer wording for always-allow command choices and can offer switching to Bypass when allowed by org policy.
* Background shell commands now render as a single exec card with a spinner instead of showing separate "Command Read" / "Killing shell" cards for each `get_output` and `kill_shell` poll.
* Ctrl+L now clears the screen properly, like bash and other shells. Visible content is scrolled into the terminal's scrollback buffer so you can still scroll up to see it. Full redraw (re-render all content from scratch) moved to Ctrl+Shift+L.
* Startup banner no longer shows the user's email address.
* Resuming a session from a different directory now prompts you to choose between the session's original directory, switching permanently to your current directory, or using your current directory just this time.
* Improved streaming view for model output.
* Updated the startup braille logo to match the design on devin.ai/terminal.
### Fixed
* Resuming a Windsurf session with `devin -r` now shows the conversation history instead of a blank screen.
* MCP OAuth discovery now works with POST-only servers and servers whose `.well-known` paths are behind SSO.
* Resuming a session now correctly restores the selected mode (Plan, Ask, Code) instead of silently reverting to Code.
* Skill discovery no longer picks up duplicate skills from nested configuration directories inside skill folders, reducing token usage at session start.
* Shell integration setup (`devin shell setup`) is now available for enterprise accounts.
### Fixed
* Opt+backspace no longer inserts 'h' on terminals that send BS for backspace.
### Interactive step picker for `/revert`
`/revert` with no arguments now opens an interactive searchable picker showing all conversation steps. Select a step to revert to it. Double-tap Esc while the agent is idle to open the same picker.
### Added
* MCP servers configured with `"transport": "sse"` (legacy SSE protocol) are now fully supported. Previously, these servers were rejected with an error; they now connect via the legacy SSE protocol (GET for event stream, POST for messages). Stored OAuth tokens are injected automatically, and 401 responses trigger the interactive OAuth flow.
* Terminal notification (bell + desktop notification) on successful authentication, making it easier to return to the terminal after logging in via the browser.
* `/btw ` asks the agent a quick side question using the current conversation context. The answer streams into a box below the agent's output without adding the question to the main conversation, so you can check in without disrupting what the agent is working on.
* `devin cloud drs` subcommands for managing environment blueprints, sandbox sessions, and builds directly from the CLI.
* First-startup welcome box with tips for getting started in Devin for Terminal.
* Git provider connection prompt during `devin setup`: detects locally logged-in `gh` CLI accounts and offers to connect them to Devin, or open the browser to set up a GitHub App or other provider.
* Typing `&` on an empty prompt enters handoff mode, a shortcut for `/handoff` that mirrors the `!` bash-mode pattern.
* Context-aware placeholder text in the input field guides users based on agent state: prompts to ask Devin for help when idle, suggests guiding Devin while it works, and indicates how to send queued messages.
* Support disabling individual MCP tools per server via `disabledTools` in the MCP config. Disabled tools are hidden from the agent and rejected at call time.
* `devin mcp enable` and `devin mcp disable` subcommands to toggle MCP servers on/off without removing them. Supports `--scope` (user, local, project). Disabled servers show with a `(disabled)` label in `devin mcp list` and a status line in `devin mcp get`.
* Support for MCP servers that require a pre-registered OAuth client (e.g. GitHub). Pass `--oauth-client-id` (and optionally `--oauth-client-secret`) to `devin mcp add` and `devin mcp login`, or set `oauthClientId` / `oauthClientSecret` in your MCP config.
* Organization selection is now part of the setup wizard. Users with multiple Devin organizations are prompted to choose one during onboarding; single-org users are auto-selected.
* `/org` command for selecting a Devin organization from the terminal.
* Option to hand off a plan to a cloud Devin session when exiting plan mode, available for users signed in with a Devin account.
* `Ctrl+R` fuzzy search for inserting previous prompts into the input box.
* Proxy configuration section in `config.json` for controlling how the CLI routes outbound HTTP traffic. Set `proxy.mode` to `"system"` (default), `"manual"`, or `"off"`, provide a `proxy.url` for manual mode, and use `proxy.no_proxy` to bypass specific hosts.
* Add `terminal-light` and `terminal-dark` theme names for 16-color terminal themes. `16color` and `terminal-colors` remain supported for backwards compatibility with `terminal-dark`.
* `/theme` accepts an optional theme name, such as `/theme dark` or `/theme light`.
* When opening the CLI inside a repo that has a Devin wiki, the wiki is now downloaded in the background and made available to the agent on subsequent sessions, so it can answer project questions using an explore subagent.
### Changed
* Browser authentication pages redesigned to show a connection status between your computer and Devin, matching the devin.ai website style.
* Login and API-key authentication labels now use Devin or generic API-key wording instead of legacy Windsurf-only wording.
* Code mode now auto-approves file edits in workspace directories. The separate "Accept Edits" mode has been folded into Code; both display as "Code" in the mode picker, with the auto-approval variant used when the org policy allows it.
* The default model is now Adaptive, which automatically routes each turn to the best model for the task. You can still pick a specific model with `/model` or by setting `agent.model` in your config.
* Declarative Repo Setup (DRS) is now a builtin agent skill instead of a `/drs` slash command. The agent automatically invokes it when you ask about environment setup. The `devin cloud drs` subcommands continue to work as before.
* Shell command previews use clearer titles and show commands with a prompt prefix in the preview body.
* Cloud handoffs now send gathered terminal context in an expandable section.
* `/handoff` now stops when the selected organization has no connected git provider and asks the user to run `devin setup` before retrying.
* New Devin CLI sessions use memorable word-pair IDs.
* Model picker now shows labeled pricing (e.g. "$5 / MTok In · $25 / MTok Out") on the highlighted model instead of unlabeled dollar amounts.
* Slash commands now show confirmation messages when switching models, themes, or modes via the interactive picker.
* Cleaned up slash command output: removed unnecessary colors, improved spacing, and simplified progress messages.
* Improved how freeform "Other" answers are handled in agent questions. Typed responses that don't match a predefined option are now recognized as custom answers automatically.
* `/resume` now opens the interactive session picker when run without a session ID.
* Rule files use tighter injection limits and switch to path-only guidance when triggered rules exceed the available context budget.
* Selection prompts now use a neutral highlighted row with clearer contrast and show item descriptions consistently.
* Normalized tool preview verb tenses: streaming previews now use present progressive ("Editing file.rs") and completed previews use past tense ("Edited file.rs").
* Status messages (warnings, errors, tips) now render through the Alert component with proper icons and theme-aware colors.
* Added meaningful titles to error messages: "Something went wrong", "Quota exhausted", "Turn limit reached", "Couldn't open browser".
* Standardized "cancelled" spelling to "canceled" (one L) in all user-facing strings.
* "Connection lost, retrying..." replaces "Inference failed mid-stream, retrying...".
* Muted text is now easier to read in both dark and light themes.
* Multiple-choice questions now use the same selection UI as other CLI prompts, including typed custom answers.
### Fixed
* File writes from `apply_patch` now appear in the agent timeline / worklog alongside writes from the `write` and `edit` tools.
* Long sessions exit more quickly when shutting down.
* Code blocks no longer lose their last character when text fills the terminal width.
* Input responsiveness while the agent is actively streaming events.
* Numbered lists in rendered markdown now show numeric markers (`1.`, `2.`, `3.`) instead of bullet points.
* OpenAI reasoning models no longer fail when a request configures temperature.
* Prompt history opens while Devin is running, including when completions are visible.
* Todo list no longer disappears after the agent finishes updating it.
* `/upgrade` opens Devin plans instead of Windsurf pricing.
* Opening a session database that was written by a newer CLI now shows a clear "please run `devin update`" message instead of a raw "migration is missing from the filesystem" error.
* `/handoff` now sets the repo via the session config option and tags the session as "Terminal".
* Model picker search no longer replaces family grouping with individual variants.
* The "Update vX available!" banner is no longer shown when background auto-update is going to install the new version on its own. It now only appears when the user has to take action (e.g. externally managed installs, or when auto-update has been disabled).
* File and code snippet references now render as readable paths instead of raw XML tags.
### Background auto-updates
On macOS and Linux, new releases are now downloaded and activated while Devin for Terminal runs, so the next invocation picks up the latest version automatically. Quitting mid-update is safe and cannot leave the installation in a broken state. Opt out by setting `"auto_update": false` in `config.json`.
### Interactive config editor
`/config` opens an interactive in-terminal config editor with tree navigation, search, and type-aware value editing.
### `/handoff` to cloud Devin
The `/handoff` slash command is now generally available. Hand off a task to a remote Devin session with live status updates showing what the agent is currently working on.
### Searchable model picker
The model picker now has a searchable interface: type to filter models, navigate with arrow keys, and see pricing info at a glance.
### Added
* Support for adaptive and model-router selections, which now resolve to concrete models automatically during inference.
* Detailed login info in `devin auth status`: login method, user name and email, user ID, team ID, plan and tier, and cached team settings.
* Added a tray panel listing running background shells. Press the down arrow from the input to open it, navigate with up/down, and press `x` to kill the selected shell.
* Support for an enterprise-configured default model. Admins can set a team-wide default model for new sessions via the Windsurf or Devin enterprise admin dashboards.
* Added keyboard selection in the cloud agents tray: use the arrow keys to pick a cloud agent and press Enter to open its session in the default browser. The session URL is still shown below each entry as a fallback when a browser can't be launched.
* Enforcement of the organization's "Auto run terminal commands" setting. Enterprise admins can now restrict which permission modes are available to CLI users — for example, preventing selection of Bypass mode when the org policy is set to "Auto" or below.
* Added a way to flush queued messages to the agent immediately by pressing Enter on an empty input box while the agent is busy, so they're picked up as soon as the current tool call finishes (without interrupting it).
* `/handoff` now attaches the local git diff to the Devin session, giving it visibility into uncommitted changes.
* Interactive organization picker for `/handoff` when no org is configured, replacing the previous error that required manual config editing.
* `legacy_terminal` config option for VT100 terminal compatibility, disabling keyboard enhancement probing, OSC sequences, and theme auto-detection.
* `disable_osc` config option to independently control OSC sequence emission (terminal titles and hyperlinks).
* `skip_workspace_trust` config option to bypass workspace trust prompts.
* Per-model token pricing in the model selector, showing input and output cost per million tokens.
* NEW, PROMO, and BETA badges in the model picker for models flagged by the server.
* Relative cost tier (Free / \$ / \$\$ / \$\$\$) as a fallback description when per-token pricing is unavailable.
* Added `/rename-session` slash command to rename the current session.
* Added `/revert ` command to undo file changes back to a specific conversation step
* Added `/steps` command to list conversation steps for use with `/fork` and `/revert`
* Added optional `[step]` argument to `/fork` to branch from an earlier conversation point
* Shift+Insert now pastes from the clipboard, matching the standard X11/Linux paste shortcut.
### Changed
* `/bug` now clarifies that the report is sent to the Devin for Terminal developers.
* Improved model selector with compact single-height items, a visible search input border, and streamlined pricing display for the selected model.
* Unknown slash commands now show "did you mean?" suggestions based on similar command names.
* Styled `/handoff` status lines with the standard animated spinner and muted text, replacing the static half-circle symbol and blue accent color.
* `/handoff` can now be used without arguments. It summarizes the current conversation and hands off to a remote Devin session to continue the task.
* Error message when switching to an unavailable permission mode now explains that sandbox mode restricts available modes and whether the restriction is enforced by the organization.
* Model name below the input box now uses the default text color instead of blue.
* Login experience streamlined: the spinner now offers "Press Enter to paste a token manually instead" and the manual-token path prints a single concise line instead of a multi-step wall of text.
* "Logging in with Windsurf. If the browser didn't open..." preamble removed from the login spinner.
* Plan mode approval prompt now shows plan-specific options: "Yes, implement plan and accept edits", "Yes, implement plan and bypass permissions", and "No, plan needs changes".
* "16-color" theme renamed to "Terminal colors" to clarify that it inherits your terminal emulator's color scheme.
* Session resume picker (`devin -r`, `devin list`) now has a searchable type-to-filter interface, matching the model selector experience.
* Updated the tray panel to always show both Cloud agents and Subagents tabs, with an empty-state hint describing the other feature when a list has no entries.
* Subagents and cloud agents tray panels now sort in reverse chronological order so the most recently launched agent appears at the top.
* Always-on rule files (such as `AGENTS.md`) injected into context are now capped at 32 KiB each. Oversized rules are truncated with a hint pointing at the source path so the agent can read the full file on demand.
### Fixed
* Errors from upstream servers (quota exhaustion, 5xx responses, connection drops, etc.) now show up as legible warnings in the REPL with a retry hint instead of raw `Error: …` text, and reach ACP clients with a typed cause so they can render them with the right severity.
* Honored user `deny` / `allow` / `ask` permission rules (including `Read(...)` and `Write(...)`) in Devin for Terminal running inside Windsurf, matching standalone CLI behavior.
* Unnecessary compaction is no longer triggered on every turn when using the adaptive model.
* Logo now appears above conversation history when resuming a session, matching the layout of a fresh session.
* `/add-dir` on Windows no longer mangles paths containing backslashes. Both `D:\Source\Project` and `..\Project` forms now work correctly.
* Startup banner text alignment is now correct on continuation lines at narrow terminal widths.
* Day-of-week is now correct when asking for the current date.
* Compound shell commands are now blocked when they include a command you've denied in your CLI permissions.
* Fixed selected/highlighted UI elements (like active question tabs, selected image attachments, and selected subagents) rendering with the same text color as un-highlighted text, making them hard to distinguish.
* MCP servers configured with `"transport": "sse"` now fail with a clear error explaining that legacy SSE is unsupported, instead of silently connecting over the wrong transport.
* Unnecessary permission prompts for shell commands no longer appear in autonomous mode with sandboxing enabled.
* Clarified in the docs and `devin skills paths` output that on Windows, global skills live in `%APPDATA%\devin\skills\` instead of `~/.config/devin/skills/`.
* Cursor positioning now uses VT100-compatible sequences (CR + CUF) instead of CHA, which is not supported by all terminals.
* Tips and spinner symbols now respect the ASCII mode setting.
* Fixed the browser login page to only say "Authentication Successful" once sign-in actually completes, and show a failure page when it doesn't.
* Unrecognized slash commands now show an error instead of being sent to the model.
* Clear install-instructions error when `socat` is missing on Linux, instead of failing silently.
* File edits in the same turn no longer occasionally overwrite each other.
### Read-only tools allowed by default
Read-only tool calls (file reads, grep, glob, thinking) are now always allowed and no longer surface a permission prompt. User-, project-, and organization-configured deny rules still take precedence, so you can still restrict reads to sensitive paths.
### `.devin/hooks.v1.json` support
Define pre- and post-command hooks in a standalone `.devin/hooks.v1.json` file using the same format as Claude Code hooks.
### `devin mcp add` overhaul
`devin mcp add` now matches Claude Code's syntax: positional URL argument (e.g. `devin mcp add notion https://mcp.notion.com/mcp`), inferred transport from `--url` (HTTP) or trailing args (stdio), default scope changed from `user` to `local` (writes to `.devin/config.local.json`, gitignored), and new short flags (`-t`, `-s`, `-e`, `-H`).
### Agent mode and permission mode separation
Agent profiles (normal, plan, ask) and permission modes (normal, accept edits, bypass, autonomous) are now two independent controls. Profiles are switched via `/plan`, `/ask`, `/normal` slash commands. `/plan ` switches to plan mode and immediately sends the prompt in one step. Permission modes are cycled with Shift+Tab or `/mode`.
### Live streaming tool previews
Tool calls now appear immediately as arguments stream in, showing structured titles and content (diffs for edits, code blocks for writes, commands for exec) instead of waiting for the full request.
### Terminal notifications
The CLI now sends terminal notifications when the agent finishes, needs input, or requests tool approval. Triggers dock badge and notification banners in supported terminal emulators. Controlled by the `notify` config option: `"never"`, `"smart"` (default, only when unfocused), or `"always"`.
### Added
* Added structured form-based input support when connected to ACP clients that advertise elicitation capability.
* Added inference tool name metadata to ACP tool call events so ACP clients can make per-tool presentation decisions (for example, hiding the arguments panel for internal tools).
* Enabled the `devin acp` subcommand on stable and next, so any released build of Devin for Terminal can be launched as an Agent Client Protocol server by ACP-aware editors.
* Added `/ask`, `/compact`, `/context`, and `/undo-add-dir` slash commands for ACP clients (e.g. JetBrains).
* Expanded `/help` output in ACP sessions to list all built-in commands and discovered skills.
* Show subagent activity and lifecycle events in the Windsurf UI.
* Made the "Mode:" and "Model:" labels in the footer clickable to open their selector menus
* Added mouse support to selector menus: click to select, scroll wheel to navigate, hover to highlight
* Autocomplete for `/continue` and `/rm-session` commands showing recent sessions with ID prefix, time ago, and title.
* `--force` flag on `devin update` and `/update` to force re-install even when already on the latest version.
* Added interactive OAuth support for MCP servers — when an MCP server requires authentication, the browser opens automatically and a status message appears in the REPL.
* `/new` as an alias for `/clear` to start a fresh conversation.
* Active permission level in the top border of the input box.
* Thumbs up/down feedback for agent responses via `Alt+↑`/`Alt+↓` and `/feedback`.
* `respect_gitignore` config option to control whether the agent respects `.gitignore` when accessing files via tools (default: off). Separate from `include_gitignored_files`, which only affects `@` tab completion.
* `/resume` as an alias for `/ls` (list recent sessions).
* Subagent prompt in the expanded view (Ctrl+O) when a subagent completes.
* Live streaming of subagent actions while waiting on a foreground subagent or a `read_subagent` call.
* `/session-stats` command to display cumulative session statistics (tool calls, files changed, commands run, tokens, model, request ID).
### Changed
* Changed workspace directory updates via ACP to use replacement semantics, enabling directory removal through the config option.
* Made `/ask ` a one-shot command matching REPL behavior: temporarily switches to Ask mode, submits the question, then restores the previous mode.
* Made session troubleshooting easier in Windsurf by showing diagnostic logs directly in the output panel.
* Presented related agent questions in a single paginated form instead of one at a time.
* Improved the plan mode exit approval with a dedicated review UI showing the plan summary and contextual button labels.
* Improved Windsurf hook scripts to receive richer tool information on stdin, including edit details, MCP tool results, and assistant responses
* `devin mcp add` no longer requires `--transport` or `--command` for the common stdio case — transport is inferred from `--url` (HTTP) or trailing args (stdio), and the first trailing arg is used as the command when `--command` is omitted
* `/mode` now opens an interactive dropdown selector (like `/model`) instead of printing a static list. Use arrow keys to navigate, Enter to confirm, Esc to cancel.
* `-p`/`--print` now accepts an optional inline prompt, so `devin -p "fix the bug"` works without needing the `--` separator. The old `devin -p -- fix the bug` syntax continues to work.
* Shortened the "always allow" label for command permission prompts to "Always allow `` commands in ``", where `` is just the last path element of the workspace directory, so it no longer overflows narrow terminals or ACP client UIs when the workspace path is long.
* `/mode` now opens an interactive dropdown selector (like `/model`) instead of printing a static list. Use arrow keys to navigate, Enter to confirm, Esc to cancel.
* Plan mode exit approval now has a dedicated review UI showing the plan summary and contextual button labels.
* Removed the brand colors from the startup logo so it uses the terminal's default foreground color.
* Truncation notices now include a "(ctrl+o to expand)" hint.
* Consolidated the mode and permission pickers into a single unified mode selector in Windsurf. The available modes are now Code, Ask, Plan, Accept Edits, and Bypass Permissions.
* Each Devin CLI channel now reads Windsurf config (MCP servers, skills) from its matching channel-specific directory under `~/.codeium/`
### Fixed
* Fixed ACP sessions to require host-provided credentials instead of silently falling back to local CLI credentials, ensuring usage is properly attributed to the correct account.
* Preserved streamed shell command output in ACP chat UIs so it stays visible after the command completes, with the exit code shown alongside instead of replacing the output.
* Session mode selector now updates immediately after choosing "switch to accept edits" from a permission prompt.
* Skipping a tool call in Windsurf no longer stops the agent — the LLM now sees the rejection and can try an alternative approach
* Tool failure messages now show the error reason in Windsurf instead of just "Failed" with no explanation.
* Fixed `/add-dir` and `/undo-add-dir` failing to handle directory paths containing spaces. Slash command arguments are now parsed with shell-style quoting (e.g. `/add-dir "my dir"` or `/add-dir my\ dir`), and tab completions automatically escape spaces in directory names.
* Fixed excessive line spacing in the ASCII mode startup banner.
* Long-running shell commands like dev servers now start reliably without blocking subsequent work.
* Fixed bypass mode not auto-approving MCP `read_resource`, computer use, recording, and browser tools due to incorrect permission scopes.
* Fixed autonomous mode silently auto-approving privacy-sensitive tools (computer use, recording, browser) that operate outside the OS sandbox.
* Fixed browser screenshot path authorization mismatch when the screenshots directory was relative.
* Fixed wide character (CJK/emoji) display corruption when deleting characters adjacent to them.
* Fixed "always allow" for command permissions silently failing to persist when running outside a git repository.
* Improved text visibility when the terminal background doesn't match the selected color theme.
* Fixed alphabetic sorting in directory completion menus so that shorter directory names sort before longer ones that share the same prefix (e.g., `devin/` now correctly appears before `devin-docs/`).
* Shell command output is no longer lost after long terminal sessions with extensive scrollback.
* Fixed injected lint diagnostics appearing as fake user messages when reopening a saved session.
* Fixed an issue where the agent would not automatically review and fix lint errors detected after code edits.
* Improved lint error presentation with more detailed information including severity level, source, and precise location.
* Added a safety cap on lint-fix injection count to prevent infinite loops when a lint cannot be resolved.
* Separated new and persistent lint errors with distinct instruction text so the agent understands which lints it has seen before.
* ANSI color escape codes are no longer written to log files or piped stdout/stderr. Colored output is only emitted to real terminals and respects the `NO_COLOR` environment variable.
* Mode is now properly restored on session resume.
* Session resume no longer drops early conversation messages after multiple compaction rounds.
* Permission mode no longer resets unexpectedly mid-session.
* Sandbox sessions no longer revert from autonomous to normal mode when exiting plan mode.
* Code diffs and other rich tool call content no longer disappear from edit/write tool calls after reloading a session in the replay UI.
* `shell run` no longer leaves the terminal in a bad state after exit.
* Fixed silent crashes when a corporate proxy or firewall resets a network connection mid-session.
* Ctrl+C now exits quickly even when the network connection is slow or stalled.
* Session and always-allow choices in permission prompts now work correctly for terminal commands that also write files.
* Thinking output now always renders before content when a model skips the `ThinkingComplete` event
* Malformed tool-call error messages now point to the specific field and expected value type.
* Windows no longer shows double authentication prompts during initial setup.
* Windows installer now places files in the correct directory so PATH resolves properly.
* Windows config file location is now clearly documented as `%APPDATA%\devin\config.json` instead of `~/.config/devin/config.json`.
* Grep now searches hidden files like `.env` and `.github/`, matching the behavior of `rg --hidden`. The `.git/` directory remains excluded.
* Large images (over 5 MB) no longer fail to send.
* Local shell commands no longer continue running in the background after a session is interrupted or cancelled.
* Preserved rich mention rendering (e.g. `@README.md` chips) when resuming a session, instead of showing raw markdown text.
### Removed
* Removed the in-REPL overage status indicator banner
* "Thought for Xs" duration display no longer appears in the REPL scrollback.
### Removed
* In-REPL overage status indicator banner is no longer shown.
### Added
* Warning when your account is in overage so you know requests are being billed to your team's prepaid balance.
* `/usage` command to show Windsurf credits and ACUs consumed during the current session.
### Fixed
* The installer now accepts existing `~/.local/bin/devin` symlinks pointing to the legacy `~/.local/share/cognition/cli/...` path and refreshes them correctly after the cognition-to-devin migration.
### Fixed
* Wide character (CJK/emoji) display corruption no longer occurs when deleting characters adjacent to them.
### Added
* Show subagent activity and lifecycle events in the Windsurf UI.
* "Mode:" and "Model:" labels in the footer are now clickable to open their selector menus.
* Mouse support in selector menus: click to select, scroll wheel to navigate, hover to highlight.
* Autocomplete for `/continue` and `/rm-session` commands showing recent sessions with ID prefix, time ago, and title.
* Added `--force` flag to `devin update` and `/update` to force re-install even when already on the latest version.
* Added support for reading hooks from `.devin/hooks.v1.json`, a standalone hooks file using the same format as Claude Code hooks
* Show subagent prompt in the expanded view (Ctrl+O) when a subagent completes.
* Stream subagent actions in the live display while waiting on a foreground subagent or a `read_subagent` call.
* New `notify` config option that controls terminal notifications when the agent finishes, needs input, or requests tool approval. Set to `"never"`, `"smart"` (default), or `"always"`. In `smart` mode, notifications are only sent when the terminal window is unfocused. Triggers dock badge and notification banners in supported terminal emulators.
### Changed
* `devin mcp add` no longer requires `--transport` or `--command` for the common stdio case — transport is inferred from `--url` (HTTP) or trailing args (stdio), and the first trailing arg is used as the command when `--command` is omitted
* `/mode` now opens an interactive dropdown selector (like `/model`) instead of printing a static list. Use arrow keys to navigate, Enter to confirm, Esc to cancel.
* `-p`/`--print` now accepts an optional inline prompt, so `devin -p "fix the bug"` works without needing the `--` separator. The old `devin -p -- fix the bug` syntax continues to work.
* Added "(ctrl+o to expand)" hint to truncation notices so users know how to view full output.
### Fixed
* Skipping a tool call in Windsurf no longer stops the agent — the LLM now sees the rejection and can try an alternative approach
* Tool failure messages now show the error reason in Windsurf instead of just "Failed" with no explanation.
* `/add-dir` and `/undo-add-dir` now handle directory paths containing spaces. Slash command arguments are parsed with shell-style quoting (e.g. `/add-dir "my dir"` or `/add-dir my\ dir`), and tab completions automatically escape spaces in directory names.
* "Always allow" for command permissions now persists correctly even when running outside a git repository.
* Text visibility improved when the terminal background doesn't match the selected color theme.
* Alphabetic sorting in directory completion menus now correctly places shorter names before longer ones with the same prefix (e.g. `devin/` before `devin-docs/`).
* Mode is now properly restored on session resume.
* Silent crashes no longer occur when a corporate proxy or firewall resets a network connection mid-session.
* Thinking output now always renders before content when a model skips the `ThinkingComplete` event.
* Fixed double authentication prompts on Windows during initial setup.
* Fixed Windows installer placing files in the wrong directory, causing PATH to point to the wrong location
* Fixed large images (over 5 MB) failing to send.
### Added
* Add `16color` and `nocolor` theme modes. `16color` quantizes output to the 16 ANSI color palette (respects terminal color scheme). `nocolor` disables all color output for VT100 and other monochrome terminals.
* Support multi-root workspaces with additional directories beyond the session working directory.
* Add `/workspace` and `/add-dir` slash commands for listing and adding workspace directories at runtime.
* Add `workspace-dirs` config option for setting workspace directories programmatically.
* Add Ask mode (`/ask`) for read-only question answering without code changes
* Add `/bug` slash command for submitting bug reports from the stdio server
* Display a persistent warning banner when running in Windows Conhost, recommending Windows Terminal or Git Bash for a better experience.
* `Ctrl+Left` and `Ctrl+Right` now jump between words, matching standard Linux and Windows terminal behavior. `Ctrl+Backspace` and `Ctrl+Delete` delete words backward and forward respectively.
* Add custom subagent profiles: define specialized subagents with their own system prompts, tools, and models via `AGENT.md` files in your project's `agents/` directory (experimental)
* Add `subagent` and `agent` frontmatter fields for skills, allowing skills to run as independent subagents instead of inline (experimental)
* Add `include_gitignored_files` config option to include gitignored files in @ tab completion results (default: off)
* `/undo-add-dir` command to remove directories from the workspace.
* `/rm-session` command to delete sessions.
* Added `request_scope` tool for requesting read/write access to directories when running in sandbox mode
* Added sandbox mode system prompt that informs the agent about sandbox restrictions and how to request additional access
* The `--sandbox` flag and `devin sandbox setup` command are now available on all build channels (previously insiders-only)
* Add `unicode_mode` config option (`auto`/`unicode`/`ascii`) for terminals that don't support Unicode glyphs
* Add `devin version` subcommand as an alias for `devin --version`
### Changed
* Include the active interface mode in bug report details
* Migrate all config, data, and cache directories from `~/.config/cognition/`, `~/.local/share/cognition/`, and `~/.cache/cognition/` to `devin/`. A backward-compatibility symlink is created at each old path so older sessions continue working.
* Rename the project-level config directory from `.cognition/` to `.devin/`. Existing `.cognition/` directories are still read (with a deprecation warning) for backward compatibility.
### Fixed
* Hooks defined in `.claude/settings.json` are now loaded by the CLI (both project-level and global `~/.claude/settings.json`)
* Cmd+V now triggers clipboard paste in terminals that report it as a key event (e.g. when pasting non-text data like images)
* Fixed panic when piping CLI output to commands that close early (e.g. `devin -p "..." | head`).
* Fix partial agent output (thinking and content) being silently dropped when the agent stops with an error during streaming
* Fixed image uploads failing when the file extension doesn't match the actual image format (e.g. a JPEG saved as `.png`). The MIME type is now detected from the image content rather than trusting the caller-supplied value.
* Fix `devin mcp login` failing against servers (e.g. Glean) that only allow `/auth/callback` as the OAuth redirect path
* Fix CLI freeze when pasting very long single-line text (e.g. JSON blobs, base64 strings) by collapsing pastes that exceed 5,000 characters
* Skills now display their true source path (e.g. `.agents/skills/`) instead of always showing `.devin/skills/`
* Fixed pasting text (Ctrl+V / bracketed paste) into slash command prompts like `/bug`
* Respect the `disabled: true` flag in MCP server configurations, so servers marked as disabled in Windsurf, Claude, or Devin config files are no longer loaded
### Fixed
* Load skills and agents from `~/.config/devin/` and `.devin/` directories as documented, in addition to the legacy `~/.config/cognition/` and `.cognition/` paths.
### Added
* Add automatic generation of descriptive session titles.
* Add `CHISEL_LOG_STDERR` env var to direct log output to stderr
* Add PAC (Proxy Auto-Configuration) support on Windows and macOS. The CLI now respects system-level PAC settings and WPAD auto-detection, routing traffic through the correct proxy without requiring manual environment variable configuration.
* Add `!` syntax to run shell commands directly from the REPL. Output streams in real-time and is automatically added to the conversation context for your next message. Typing `!` enters bash mode with a dedicated prompt and title indicator. Use Ctrl+C to cancel a running command.
* Display Devin logo alongside product info on CLI startup.
### Changed
* The `/bug` command now automatically includes terminal environment info (`TERM_PROGRAM`, `TERM_PROGRAM_VERSION`, `TERM`) in bug reports.
* Change permission prompt default selection from "Yes, always allow" back to "Yes" (approve once)
### Fixed
* Fix "Always Allow" permission not persisting across tool calls when running inside Windsurf
* Fix enterprise team-enforced permission rules not being applied when running inside Windsurf
* Fixed `Co-Authored-By` commit trailer to use the correct GitHub App bot email instead of `noreply@cognition.ai`
* Fix permission suggestions including file paths as part of the command prefix
(e.g. `allow cat foo/bar/baz.txt` now correctly shows `allow cat`).
* Fix repeated "Context compacted" notifications when inference fails mid-stream and retries
* Fixed off-by-one error in edit tool's reported start/end line numbers when the edit is not at the beginning of the file
* Fix "always allow fetches to" permission not being recognized after restart
* `mcp_list_tools` now includes the `input_schema` for each tool, so the agent can discover parameter requirements without needing to trigger a tool call error first.
* Fix `devin mcp login` failing on servers that use RFC 8414 OAuth discovery instead of RFC 9728 (e.g. Atlassian)
* Fix pasting text that starts with `#` (e.g. markdown headings) being silently dropped.
* Fix spinner disappearing after a sub-agent completes while the main session is still running
* Fixed layout shift in the startup banner where text jumped when account info loaded
* Fixed stray `<` character appearing at the start of terminal output on headless environments where `TERM=dumb`
* Fixed missing whitespace in thoughts.
* Allow long question headers in `ask_user_question` instead of rejecting them; headers over 16 characters are now truncated with an ellipsis (…) for display
* Fix missing DLL errors on Windows ARM by statically linking the C runtime
### Removed
* Removed the "Loading configuration from..." startup notice. Configuration import from Cursor, Windsurf, and Claude Code still works — the notice is simply no longer displayed.
### Added
* Add `show_path` config option to display the current working directory in the input border
# Commands & Flags
Source: https://docs.devinenterprise.com/cli/reference/commands
Complete reference for command arguments, subcommands, and interactive slash commands
## Usage
```bash theme={null}
devin [OPTIONS] [prompt]
```
Pass an optional prompt to start a session with an initial message, or launch interactively with no arguments.
You can also read these from your terminal with `man devin`.
***
## Global Flags
| Flag | Short | Env var | Description |
| ----------------------------------------- | ----- | ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--model ` | | `DEVIN_MODEL` | Set the AI model for this session |
| `--permission-mode ` | | `DEVIN_PERMISSION_MODE` | Permission mode: `normal` (alias `auto`, the default), `accept-edits`, `smart`, `dangerous` (aliases `yolo`, `bypass`), or `autonomous` (requires `--sandbox`). See [Permissions](/cli/reference/permissions). |
| `--sandbox` | | `DEVIN_SANDBOX` | \[Research Preview] Sandbox exec-tool processes (macOS seatbelt / Linux bwrap+seccomp). See [Sandbox](/cli/sandbox). |
| `--continue` | `-c` | | Resume the most recent session in the current directory |
| `--resume ` | `-r` | | Resume a specific session by ID |
| `--print [PROMPT]` | `-p` | | Print response and exit (non-interactive mode). Optionally accepts an inline prompt. |
| `--prompt-file ` | | | Load the initial prompt from a file |
| `--config ` | | | Configuration file path |
| `--export [PATH]` | | | Export conversation to a file after each turn (ATIF format). Uses a default path if none is provided. |
| `--respect-workspace-trust [true\|false]` | | | Whether to respect workspace trust settings. Defaults to `true`. |
Non-interactive `--print` mode cannot show the workspace trust prompt, so it fails in an untrusted directory. Pass `--respect-workspace-trust false` to skip the check in scripts and CI.
**Examples:**
```bash theme={null}
devin -- add a login page
devin --model opus -- refactor the auth module
devin --permission-mode accept-edits -- fix the failing tests
devin --sandbox -- run the migration script
devin -c # Resume last session
devin -r abc12345 # Resume specific session
devin -p "list all TODO comments" # Print response and exit
devin -p -- list all TODO comments # Same, using -- separator (still works)
devin --export -- fix the tests # Export conversation to default path
devin --export out.json -- fix tests # Export to a specific file
```
***
## Subcommands
### devin auth
Authentication related commands.
| Command | Description |
| ------------------- | ------------------------------------- |
| `devin auth login` | Log in to your account |
| `devin auth logout` | Log out and remove stored credentials |
| `devin auth status` | Check authentication status |
**Options for `devin auth login`:**
* `--force-manual-token-flow` — Skip browser-based auth and manually paste a token (useful for remote/SSH sessions)
### devin mcp
Connect and log in to Model Context Protocol servers.
| Command | Description |
| -------------------------- | ------------------------------------------------- |
| `devin mcp add ` | Add a new MCP server |
| `devin mcp list` | List all configured MCP servers |
| `devin mcp get ` | Show details for a specific MCP server |
| `devin mcp remove ` | Remove a configured MCP server |
| `devin mcp login ` | Authenticate with an MCP server via OAuth |
| `devin mcp logout ` | Remove stored OAuth credentials for an MCP server |
| `devin mcp enable ` | Enable a disabled MCP server |
| `devin mcp disable ` | Disable an MCP server without removing it |
**Options for `devin mcp add`:**
* `-t, --transport ` — Transport type (optional; inferred from URL → http, trailing args → stdio)
* `-s, --scope ` — Configuration scope (default: `local`)
* `--url ` — URL for HTTP transport (can also be passed as a positional argument after the name)
* `--command ` — Command for stdio transport (optional when trailing args are provided)
* `-e, --env ` — Environment variables (repeatable)
* `-H, --header ` — HTTP headers (repeatable)
* `--scopes ` — OAuth scopes to request (comma-separated)
* `--oauth-resource ` — Override the RFC 8707 `resource` parameter sent in OAuth requests (default: the MCP server URL; pass an empty string to omit it for providers that reject it)
* `` — Positional URL argument for HTTP (alternative to `--url`)
* `-- [ARGS...]` — Command and arguments for stdio (first arg is the command when `--command` is omitted)
HTTP servers try Streamable HTTP first and fall back to legacy SSE on 4xx errors (per the [MCP spec](https://spec.modelcontextprotocol.io/specification/2025-03-26/basic/transports/#backwards-compatibility)). You can also set `"transport": "sse"` explicitly. See [MCP Configuration → Troubleshooting](/cli/extensibility/mcp/configuration#troubleshooting).
**Examples:**
```bash theme={null}
# stdio server
devin mcp add my-server -- npx @company/mcp-server --port 3000
# HTTP server (positional URL)
devin mcp add notion https://mcp.notion.com/mcp
devin mcp add --transport http datadog-mcp https://mcp.datadoghq.com/api/unstable/mcp-server/mcp
# HTTP server (--url flag, also works)
devin mcp add notion --url https://mcp.notion.com/mcp
# With environment variables and scope
devin mcp add -e GITHUB_TOKEN=ghp_xxx github -- npx -y @modelcontextprotocol/server-github
devin mcp add -s project sentry https://mcp.sentry.dev/mcp
```
**Options for `devin mcp remove`:**
* `-s, --scope ` — Configuration scope (default: `local`)
**Options for `devin mcp login`:**
* `--scopes ` — OAuth scopes to request (comma-separated)
* `--oauth-resource ` — Override the RFC 8707 `resource` parameter sent in OAuth requests (default: the MCP server URL; pass an empty string to omit it for providers that reject it)
**Options for `devin mcp enable`:**
* `-s, --scope ` — Configuration scope (default: `local`)
**Options for `devin mcp disable`:**
* `-s, --scope ` — Configuration scope (default: `local`)
See [MCP Configuration](/cli/extensibility/mcp/configuration) for details.
### devin models
List the models available to your account.
| Command | Description |
| --------------------------------- | ------------------------------------------------ |
| `devin models list` | List available models, organized by model family |
| `devin models list --format json` | Output the model list as JSON (for scripts) |
See [Models](/cli/models) for details.
### devin rules
Manage agent rules (always-on context blobs).
| Command | Description |
| ------------------------- | -------------------------------- |
| `devin rules list` | List all available rules |
| `devin rules show ` | Show details for a specific rule |
| `devin rules paths` | Show rule directory locations |
**Options for `devin rules list`:**
* `--provider ` — Filter by rule provider
See [Rules](/cli/extensibility/rules) for details.
### devin skills
Manage agent skills (slash commands and agent-triggered context blobs).
| Command | Description |
| -------------------------- | --------------------------------- |
| `devin skills list` | List all available skills |
| `devin skills show ` | Show details for a specific skill |
| `devin skills paths` | Show skill directory locations |
**Options for `devin skills list`:**
* `--trigger ` — Filter by trigger type
See [Skills](/cli/extensibility/skills/overview) for details.
### devin plugins
Manage plugins — bundles that ship skills, rules, hooks, MCP servers, and subagents together.
| Command | Description |
| -------------------------------- | ----------------------------------------------------------------------------------------------------------- |
| `devin plugins install ` | Install a plugin and its required plugins |
| `devin plugins list` | List installed plugins with their version and blocked status |
| `devin plugins info ` | Show a plugin's skills, hooks, rules, and its required/optional/forbidden lists |
| `devin plugins update [name]` | Re-fetch and re-install a plugin at the latest HEAD. Omit the name to update every plugin. |
| `devin plugins remove ` | Remove an installed plugin |
| `devin plugins prune` | Drop requirements from repos that no longer exist on disk, then garbage-collect unreferenced plugin content |
A source is a GitHub `owner/repo`, a git URL, or a local path. Append `#path/to/plugin` when the plugin lives below a repository's root.
**Options:**
* `-y, --yes` (`install`) — Skip the interactive trust prompt
* `--force` (`remove`) — Remove even when another plugin or a governance config still requires it
```bash theme={null}
devin plugins install acme/review-tools
devin plugins install acme/vendor-plugins#plugins/stripe
devin plugins info review-tools
```
See [Plugins](/cli/extensibility/plugins/overview) for details.
### devin migrate
Migrate configuration from other tools into Devin's own formats.
| Command | Description |
| ------------------------- | --------------------------------------------------------------------------------------- |
| `devin migrate hooks` | Migrate Windsurf hooks (`.windsurf/hooks.json`) to Devin hooks (`.devin/hooks.v1.json`) |
| `devin migrate workflows` | Migrate workflow files into skills and remove the originals |
**Options for `devin migrate workflows`:**
* `--scope ` — Which workflows to migrate (default: `all`)
Migration is a one-time copy. Configuration that Devin CLI reads in place — rules, skills, and MCP servers from Cursor, Windsurf, Claude Code, Copilot, and others — needs no migration; see [Configuration Import](/cli/reference/configuration/read-config-from).
### devin list
List sessions in the current directory. Alias: `devin ls`
| Command | Description |
| -------------------------- | ------------------------------------ |
| `devin list` | Interactive session picker (default) |
| `devin list --format json` | Output sessions as JSON |
| `devin list --format csv` | Output sessions as CSV |
### devin cloud
Manage Devin Cloud resources from the terminal. Commands use the credentials stored by `devin auth login` — there is no extra environment wiring.
#### devin cloud drs
Manage [Declarative Repo Setup](/onboard-devin/environment/blueprints): environment blueprints, sandbox sessions for testing repo setup, and snapshot builds.
| Command | Description |
| ------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------- |
| `devin cloud drs whoami` | Print the current configuration (org, API endpoint, auth status) |
| `devin cloud drs sandbox-create --repo ` | Create a sandbox Devin session attached to a repository for testing repo setup |
| `devin cloud drs run --devin-id --command ` | Run a shell command inside a sandbox session and block until it finishes |
| `devin cloud drs blueprint-list` | List all environment blueprints for the organization |
| `devin cloud drs blueprint-create` | Create a blueprint, optionally scoped to a repository |
| `devin cloud drs blueprint-write --blueprint-id --from-file ` | Replace a blueprint's contents with a YAML file |
| `devin cloud drs build` | Trigger an environment build and wait for it to finish |
| `devin cloud drs build-start` | Trigger a build and return immediately with the build job ID |
| `devin cloud drs build-wait --build-job-id ` | Wait for a previously started build to finish |
| `devin cloud drs build-logs --build-job-id ` | Stream a build job's logs as NDJSON — useful for diagnosing `partial` or `failed` builds |
| `devin cloud drs secret-create --key --value ` | Create an organization-level secret |
**Options for `devin cloud drs sandbox-create`:**
* `--repo ` — Repository to attach the sandbox to (required)
* `--prompt ` — Initial prompt for the sandbox session
* `--secret ` — Per-session secret (repeatable)
**Options for `devin cloud drs run`:**
* `--devin-id ` — Devin session ID (e.g. `devin-abc123…`) (required)
* `--command ` — Shell command to execute (required)
* `--timeout ` — Server-side timeout (default: `600`)
**Options for `devin cloud drs blueprint-create`:**
* `--repo ` — Repository to scope the blueprint to; omit for an org-wide blueprint
* `--from-file ` — YAML file with the initial blueprint contents
```bash theme={null}
devin cloud drs whoami
devin cloud drs blueprint-create --repo acme/api --from-file environment.yaml
devin cloud drs sandbox-create --repo acme/api --secret NPM_TOKEN=abc123
devin cloud drs run --devin-id devin-abc123 --command "npm test"
devin cloud drs build
```
See [Blueprint reference](/onboard-devin/environment/blueprint-reference) for the `environment.yaml` format these commands read and write.
### devin version
Print the current version and exit.
```bash theme={null}
devin version
```
This is equivalent to `devin --version`.
### devin acp
Run Devin as an [Agent Client Protocol (ACP)](https://agentclientprotocol.com/) server over stdio. This subcommand is intended to be invoked by an ACP-aware editor or IDE (such as Windsurf or Zed) as a subprocess — it speaks JSON-RPC over stdin/stdout and is not meant to be run interactively.
```bash theme={null}
devin acp
```
The ACP server reads credentials from `WINDSURF_API_KEY` if set, otherwise from the credentials stored by `devin auth login`. It can also accept credentials at runtime via the ACP `authenticate` request.
**Options:**
| Flag | Env var | Description |
| --------------------- | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--agent-type ` | | The type of agent to run. Omit to run the default agent. |
| `--model ` | `DEVIN_MODEL` | Default model for every new ACP session, overriding the enterprise-configured default. Accepts the same fuzzy names as `/model` (family slug, alias, or partial name), e.g. `--model opus`. |
```bash theme={null}
devin acp --model opus
```
#### Slash commands in ACP hosts
The ACP server advertises its full slash-command set over the protocol, so the commands show up in the host's own command palette with descriptions, argument hints, and categories:
| Category | Commands |
| -------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| Account | `/login [api-key]`, `/logout`, `/status` (the ACP name for the CLI's `/login-status`) |
| Session | `/ask [question]`, `/plan [prompt]`, `/compact`, `/context`, `/fast`, `/loop `, `/btw `, `/session-stats` (alias `/stats`), `/help` |
| System | `/workspace` (alias `/workspaces`), `/add-dir `, `/remove-dir `, `/mcp`, `/bug ` |
Some commands are gated by the host and your account:
* `/login` and `/logout` are hidden when the host manages authentication itself.
* The workspace-directory commands (`/workspace`, `/add-dir`, `/remove-dir`) only appear when the host asks the agent to own the workspace roots. Hosts that manage their own roots never see them.
### devin update
Check for updates and optionally install them.
```bash theme={null}
devin update
```
Use `--force` to re-install even if already on the latest version:
```bash theme={null}
devin update --force
```
### devin sandbox
\[Research Preview] Manage OS-level process sandboxing for the exec tool. Pass the global `--sandbox` flag to run a session with the sandbox enforced.
#### devin sandbox setup
Print the sandbox prerequisites for the current platform.
Requirements to run with `--sandbox`:
* **Linux**: requires bubblewrap (`bwrap`) and `socat`. A sandbox session fails to start with install instructions if either is missing — including in a fresh WSL distribution.
* **macOS**: works out of the box via Seatbelt; no extra packages needed.
* **Windows**: native Windows cannot run the sandbox. [Install WSL 2](https://learn.microsoft.com/windows/wsl/install) and run Devin inside your WSL distribution.
```bash theme={null}
devin sandbox setup
```
### devin setup
Interactive setup wizard for authentication and MCP configuration.
```bash theme={null}
devin setup
devin setup --force-manual-token-flow # For remote/SSH sessions
```
### devin doctor
Diagnose air-gapped configuration and model endpoint connectivity.
```bash theme={null}
devin doctor
devin doctor --json # Machine-readable output
```
`devin doctor` is only present in air-gapped builds of the CLI.
### devin worker
Runs the CLI as an [Outposts](/cloud/outposts/overview) worker. It is hidden from `devin --help` and documented separately — see the [Outposts reference](/cloud/outposts/reference).
### devin uninstall
Uninstall Devin CLI and optionally remove all data.
| Option | Description |
| --------- | ----------------------------------------------------------------- |
| `--clean` | Remove all data including configuration, history, and custom data |
| `--force` | Skip confirmation prompt |
***
## Slash Commands
These commands are available inside an interactive session. Type them at the prompt.
### Mode & Model
| Command | Description |
| --------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `/mode [normal\|accept-edits\|smart\|plan\|bypass]` | Show or switch the current mode (`autonomous` is available in sandbox sessions) |
| `/normal` | Switch to Normal mode (default) |
| `/accept-edits` | Switch to Accept Edits mode (auto-approve file edits in workspace) |
| `/smart` | Switch to Smart mode (auto-approve actions a fast model judges safe). Rolling out gradually — it may not be available on your account yet. |
| `/plan` | Switch to Plan mode (read-only planning) |
| `/ask ` | Ask a question without making code changes (oneshot) |
| `/bypass` | Switch to Bypass mode (auto-approve all actions) |
| `/autonomous` | Switch to Autonomous mode (sandbox-enforced; requires `--sandbox`) |
| `/model [name]` | Show or change the current model |
| `/fast` | Switch to SWE-1.6 Fast |
| `/theme [dark\|light\|terminal-dark\|terminal-light\|no-color]` | Switch between themes (dark, light, terminal dark, terminal light, no color) |
`/bypass` has aliases `/yolo` and `/dangerous`. All three do the same thing.
### Session Management
| Command | Description |
| ----------------------------- | ------------------------------------------------------------------------------------------------- |
| `/clear` | Clear conversation history and start a new session. Alias: `/new` |
| `/continue [session-id]` | Resume a previous session |
| `/fork [step]` | Fork the current session to a new session. Optionally fork from a specific step (see `/steps`). |
| `/steps` | List conversation steps (use with `/fork` and `/revert`) |
| `/revert ` | Revert file changes from a specific step onwards and rewind the conversation to before that step |
| `/resume [session-id]` | Open the interactive session picker, or resume a specific session by ID |
| `/ls [--all]` | List recent sessions (current directory only by default). Alias: `/list-sessions` |
| `/title ` | Rename the current session |
| `/rename-session ` | Rename the current session |
| `/rm-session ` | Irreversibly delete a session and all its data |
| `/export` | Show export info. Use the `--export` CLI flag to enable conversation export. |
| `/exit` | Exit the application (alias: `/quit`). You can also type `exit` or `quit` without the `/` prefix. |
### Workspace
| Command | Description |
| ---------------------- | -------------------------------------------------------------- |
| `/workspace` | List workspace directories (alias: `/workspaces`) |
| `/add-dir ` | Add an additional workspace directory |
| `/undo-add-dir ` | Remove a workspace directory |
| `/remove-dir ` | Remove a workspace directory (second name for `/undo-add-dir`) |
### Automation
| Command | Description |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `/loop ` | Run a prompt then auto-review the diff in a loop |
| `/btw ` | Ask a quick side question. Runs a sidechain using the current conversation context and prints the answer in a box, without adding the question to the main conversation. |
### Extensibility
| Command | Description |
| -------- | ------------------------------------------------------------------- |
| `/hooks` | List all loaded hooks with their IDs, event types, and source paths |
| `/mcp` | List configured MCP servers and their status |
### Utilities
| Command | Description |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `/help` | Show available slash commands |
| `/shortcuts` | Browse keyboard shortcuts in an interactive, searchable list grouped by category. Press `Enter` on a row to [rebind it](/cli/reference/keyboard-shortcuts#customizing-keybindings), and see each action's `context.action` identifier |
| `/config` | Open the interactive config editor |
| `/bug [description]` | Report a bug to the Devin CLI developers |
| `/update [--force]` | Check for and install updates. Pass `--force` to re-install even when already on the latest version. |
| `/upgrade` | Upgrade your subscription plan |
| `/login` | Authenticate with your account |
| `/logout` | Clear stored credentials and exit |
| `/login-status` | Show login and authentication status (advertised to ACP hosts as `/status`) |
| `/org` | Select your Devin organization |
| `/copy` | Copy the last response to the clipboard |
| `/feedback ` | Rate the last response |
| `/mouse` | Toggle mouse event capture (click/hover/scroll in menus) |
| `/context` | Show context window usage |
| `/usage` | Show estimated credit/ACU usage for the session, including usage from previous openings of a resumed session |
| `/session-stats` | Show session statistics (alias: `/stats`) |
| `/compact` | Force conversation compaction |
#### Session statistics
`/session-stats` (alias `/stats`) is the full view of what a session has consumed, where `/usage` is the thin credit/ACU summary. It renders every usage dimension the server reports — credits, ACUs, agent messages, turn continuations, and token usage — using the server's own labels and grouping, so new dimensions show up without a CLI update. The `Model` row names the model that actually served the billed turns, which can differ from the model you selected. Totals persist across resume, so a resumed session reports its cumulative usage rather than starting over.
### Cloud Sessions (insiders only)
| Command | Description |
| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `/cloud-sessions [--all]` | Open an interactive picker of your recent cloud Devin sessions. Use arrow keys to navigate, type to filter, Enter to select, Esc to cancel. Pass `--all` for org-wide sessions. |
***
## Modes
Modes control the agent's autonomy level by combining a permission mode with an agent profile.
Full autonomy for complex coding tasks. The agent can read, write, and execute commands with normal permission checks.
* **Permission mode:** Normal
* **Profile:** Normal
* **Use for:** Multi-file refactoring, feature implementation, bug fixes
Planning only — the agent proposes changes without making them. Read-only tool access ensures no code is modified.
* **Permission mode:** Normal
* **Profile:** Plan (read-only tools)
* **Use for:** Architecture design, understanding codebases, planning before implementation
Workspace edits are auto-approved like Accept Edits, and a fast model decides whether other actions are safe to auto-run, falling back to the normal prompt otherwise.
* **Permission mode:** Smart
* **Profile:** Normal
* **Use for:** Routine development work (building, testing, linting) with fewer interruptions
Smart mode is rolling out gradually and may not be available on your account yet. See [Permissions](/cli/reference/permissions).
All permission prompts are auto-approved. The agent executes freely without asking for confirmation.
* **Permission mode:** Dangerous
* **Profile:** Normal
* **Use for:** Trusted tasks where interruptions slow you down
Use Bypass mode only for tasks you fully trust. All tool calls (including destructive commands) are auto-approved.
Everything except file writes is auto-approved and the OS sandbox enforces the boundary instead of prompts.
* **Permission mode:** Autonomous (requires `--sandbox`)
* **Profile:** Normal
* **Use for:** Long unattended runs inside a [sandboxed](/cli/sandbox) session
Cycle between modes with `/mode`, or switch directly with `/normal`, `/accept-edits`, `/smart`, `/plan`, `/bypass`, or `/autonomous`. Use `/ask ` as a oneshot command to ask questions without switching modes.
***
## Profiles
Profiles determine the agent's available tools and behavior. Profiles are automatically set when you switch modes.
| Profile | Description | Tool Access |
| -------- | ----------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- |
| `normal` | Full coding assistant (used by Normal, Accept Edits, Smart, Bypass, and Autonomous modes) | All tools |
| `plan` | Structured planning workflow (used by Plan mode) | Read-only tools (grep, glob, read, todo, ask\_user\_question, exit\_plan\_mode) |
| `ask` | Question answering (used by the `/ask` command) | Read-only tools (grep, glob, read, todo, ask\_user\_question) |
# Configuration File
Source: https://docs.devinenterprise.com/cli/reference/configuration/config-file
Complete reference for the Devin CLI config file format
Devin CLI uses JSON files (with comment support) for configuration. This page documents all available options.
***
## File Locations
| File | Purpose |
| --------------------------------------------------- | ------------------------------------------------------------ |
| `~/.config/devin/config.json` | User-wide settings |
| `.devin/config.json` | Project settings (committed) |
| `.devin/config.local.json` | Project local overrides (gitignored) |
| `~/.config/devin/mcp_config.json` | User-wide MCP servers |
| `.devin/mcp_config.json` | Project MCP servers (committed) |
| `.devin/mcp_config.local.json` | Project local MCP servers (gitignored) |
| [System policy file](/cli/enterprise/system-config) | Machine-wide, administrator-managed settings (`system.json`) |
On Windows, the user config paths are `%APPDATA%\devin\config.json` and `%APPDATA%\devin\mcp_config.json` (e.g. `C:\Users\\AppData\Roaming\devin\config.json`), not `~\.config\devin\`.
MCP servers moved to the dedicated `mcp_config.json` files in v3000.3 (the Local 3.6 release). Older versions store them in the `mcpServers` key of the main config files instead; newer versions migrate any `mcpServers` entries found there automatically on startup. See [mcpServers](#mcpservers).
***
## Full Config Reference
```json theme={null}
// ~/.config/devin/config.json
{
// Agent behavior
"agent": {
"model": "swe-1-6-fast", // Default model
"show_history_on_continue": true // Show messages when resuming
},
// Theme
"theme_mode": null, // "light", "dark", "terminal-dark", "terminal-light", "nocolor", or null (auto)
// Permissions
"permissions": {
"allow": [],
"deny": [],
"ask": []
},
// Display
"show_path": false, // Show CWD in input border
"unicode_mode": "auto", // "auto", "unicode", or "ascii"
"show_hints": true, // Show tips between turns
// File completion
"include_gitignored_files": false, // Include gitignored files in @ completions
// File access
"respect_gitignore": false, // Block tool access to gitignored paths
// Commit & PR attribution
"attribution": true, // Add "Generated with Devin" / Co-Authored-By to commits & PRs
// Subagents
"subagents_enabled": true, // Allow the agent to spawn subagents
// Keybinding overrides, keyed by context then action
"keymap": {
"global": { "clear_screen": "ctrl-shift-k" }
},
// Updates
"auto_update": true, // Install new versions in the background
// Keybinding overrides (context -> action -> key spec(s))
"keymap": {},
// Notifications
"notify": "smart", // "never" | "smart" | "always" — terminal notifications
// Proxy settings for CLI HTTP traffic
"proxy": {
"mode": "system", // "system" | "manual" | "off"
"url": null, // Proxy URL (required for manual mode)
"no_proxy": null // Comma-separated bypass list
},
// Sandbox network filtering
"sandbox": {
"allowed_domains": [], // Domain allowlist (empty = no filtering)
"denied_domains": [], // Domain denylist (takes precedence)
"network_mode": "full" // "full" or "limited" (GET/HEAD/OPTIONS only)
},
// Import settings from other tools
"read_config_from": {
"cursor": true,
"windsurf": true,
"claude": true
}
}
```
```json theme={null}
// .devin/config.json
{
// Permissions
"permissions": {
"allow": [],
"deny": [],
"ask": []
},
// Import settings from other tools
"read_config_from": {
"cursor": true,
"windsurf": true,
"claude": true
}
}
```
***
## Options Reference
Options marked with **User only** can only be set in the user config (`~/.config/devin/config.json`; `%APPDATA%\devin\config.json` on Windows). Only `permissions`, `read_config_from`, and `hooks` are available in project configs. `mcpServers` can also be set at both levels, but lives in the dedicated `mcp_config.json` files (see [mcpServers](#mcpservers)).
### agent (user only)
| Option | Type | Default | Description |
| -------------------------- | ------- | ---------------- | ---------------------------------------------- |
| `model` | string | `"swe-1-6-fast"` | Default AI model |
| `show_history_on_continue` | boolean | `true` | Show previous messages when resuming a session |
### theme\_mode (user only)
| Value | Behavior |
| ------------------ | ------------------------------------------------------------------------ |
| `null` | Auto-detect (asks on first run) |
| `"light"` | Light theme |
| `"dark"` | Dark theme |
| `"terminal-dark"` | Dark theme quantized to 16 ANSI colors (respects terminal color scheme) |
| `"terminal-light"` | Light theme quantized to 16 ANSI colors (respects terminal color scheme) |
| `"nocolor"` | No color output (monochrome, useful for VT100 terminals) |
### permissions
See [Permissions](/cli/reference/permissions) for full documentation.
```json theme={null}
{
"permissions": {
"allow": ["Read(**)", "Exec(git)"],
"deny": ["Exec(sudo)"],
"ask": ["Write(**/.env*)"]
}
}
```
### mcpServers
Map of server name to server configuration. Supports both local command (stdio) and remote HTTP servers. See [MCP Configuration](/cli/extensibility/mcp/configuration).
Since v3000.3 (the Local 3.6 release), MCP servers live in dedicated files: `~/.config/devin/mcp_config.json` (`%APPDATA%\devin\mcp_config.json` on Windows), `.devin/mcp_config.json`, and `.devin/mcp_config.local.json`. In older versions, the `mcpServers` key lives directly in the main config files; newer versions migrate it to the dedicated files automatically on startup.
```json theme={null}
// mcp_config.json
{
"mcpServers": {
"server-name": {
"command": "executable",
"args": ["arg1", "arg2"],
"env": { "KEY": "value" }
},
"remote-server": {
"url": "https://mcp.example.com/mcp",
"transport": "http"
}
}
}
```
### show\_path (user only)
Show the current working directory path in the input border. When enabled, the top border of the input box displays your prettified CWD (e.g. `~/projects/my-app`).
| Value | Behavior |
| ------- | ----------------------------- |
| `false` | Hidden (default) |
| `true` | Show CWD path in input border |
### unicode\_mode (user only)
Controls whether the terminal UI uses Unicode symbols or ASCII-safe fallbacks. Set to `"ascii"` if your terminal or font does not render Unicode glyphs correctly (e.g. the ⏺ symbol appearing as a box).
| Value | Behavior |
| ----------- | ------------------------------------------------- |
| `"auto"` | Detect Unicode support from environment (default) |
| `"unicode"` | Always use Unicode symbols |
| `"ascii"` | Always use ASCII-safe characters |
### show\_hints (user only)
Show occasional tips between turns (e.g. "Did you know: Use /model to switch between available models"). Useful for discovering CLI features; set to `false` to suppress them once you're familiar.
| Value | Behavior |
| ------- | -------------------------------- |
| `true` | Show tips occasionally (default) |
| `false` | Never show tips |
### include\_gitignored\_files (user only)
Include gitignored files in `@` tab completion results. When enabled, files matching `.gitignore` patterns will appear in `@` mention completions. This is useful if you store documentation or other files in gitignored directories that you want to reference.
| Value | Behavior |
| ------- | --------------------------------------------------- |
| `false` | Exclude gitignored files from completions (default) |
| `true` | Include gitignored files in `@` completions |
### respect\_gitignore (user only)
Control whether the agent respects `.gitignore` when reading or writing files via tools. When enabled, tool calls that access gitignored paths are blocked. This is separate from `include_gitignored_files`, which only affects `@` tab completion.
| Value | Behavior |
| ------- | --------------------------------------------------------------- |
| `false` | Agent can access all files regardless of `.gitignore` (default) |
| `true` | Block tool access to gitignored paths |
### attribution (user only)
Control whether the agent adds Devin attribution to the commits and pull requests it creates. When enabled, commit and PR bodies include a `Generated with [Devin]` line and a `Co-Authored-By: Devin` trailer. Set to `false` to omit both so no Devin attribution is added.
| Value | Behavior |
| ------- | ----------------------------------------------------------------------------------------------- |
| `true` | Add the `Generated with [Devin]` line and `Co-Authored-By` trailer to commits and PRs (default) |
| `false` | Omit all Devin attribution from commits and PRs |
### subagents\_enabled (user only)
Control whether the agent can delegate work to [subagents](/cli/subagents). When disabled, the `run_subagent` and `read_subagent` tools are removed, so the agent does all the work itself. Changing this setting applies live — a running session picks it up without restarting.
| Value | Behavior |
| ------- | --------------------------------------- |
| `true` | The agent can spawn subagents (default) |
| `false` | Subagents are disabled for this user |
Organization policy takes precedence: if an admin has disabled subagents for your org (via the **Default subagent model** setting), subagents stay off regardless of this setting.
### keymap (user only)
Override the CLI's built-in [keyboard shortcuts](/cli/reference/keyboard-shortcuts). The section is a table of contexts (`global`, `editor`, `input`, `list`, …), each mapping action names to the key(s) that trigger them. Actions you don't list keep their built-in defaults.
```json theme={null}
{
"keymap": {
"global": {
"clear_screen": "ctrl-shift-k",
"history_search": ["ctrl-r", "f3"]
},
"editor": {
"beginning_of_line": "home"
}
}
}
```
| Value | Meaning |
| ------------------ | --------------------------------------------------- |
| `"ctrl-shift-k"` | A single key spec bound to the action |
| `["ctrl-r", "f3"]` | Several key specs, any of which triggers the action |
| `[]` | Unbind the action |
A key spec is a `-`-separated list of modifiers (`ctrl`, `alt`, `shift`) followed by one key name (a character, or a named key like `enter`, `esc`, `tab`, `home`, `page-up`, `f5`). Modifier order does not matter and matching is case-insensitive, except that a single uppercase character binds the shifted key (`"K"` is the same as `"shift-k"`).
Run `/shortcuts` to see every action with its `context.action` identifier — the same identifiers used here — and rebind interactively. Bindings you set there are saved back to this section.
`global.cancel` (`Ctrl+C`) cannot be unbound, so you can always interrupt a running agent. Invalid entries, unknown contexts or actions, and overrides that would collide with another shortcut in the same context are reported at startup and fall back to the built-in default.
### auto\_update (user only)
Control background auto-update on macOS and Linux. When enabled, new releases are downloaded and activated while Devin CLI runs, so the next invocation of `devin` picks up the latest version automatically. The currently running session is unaffected — a swap of the `current` symlink only takes effect on the next launch.
The update is designed to be safe against interruption: every filesystem step is staged to a temp path and promoted with an atomic rename, and concurrent updaters are serialized with a file lock. Quitting mid-update cannot leave the installation in a broken state — you'll just come back up on the old version.
Only applies to self-managed installations (`curl | bash` on macOS/Linux). Installations bundled with another product (e.g. Windsurf) ignore this setting and update through their parent application.
| Value | Behavior |
| ------- | ------------------------------------------------------------- |
| `true` | Download and install new versions in the background (default) |
| `false` | Only check for new versions; install manually via `/update` |
### keymap (user only)
Override keyboard shortcuts. Overrides are keyed by context, then action — the `context.action` identifier shown for each shortcut in `/shortcuts` (e.g. `editor.insert_newline`):
```json theme={null}
{
"keymap": {
"global": {
"clear_screen": "ctrl-shift-k",
"history_search": ["ctrl-r", "f5"],
"feedback_up": []
},
"editor": {
"insert_newline": ["shift-enter", "alt-enter", "ctrl-j"]
}
}
}
```
| Value | Behavior |
| ----------------- | ------------------------------------------------ |
| `""` | Bind the action to a single key |
| `["", ...]` | Bind the action to several keys (all trigger it) |
| `[]` | Unbind the action |
Overrides fully replace the built-in defaults for that action; unlisted actions keep their defaults. `Ctrl+C` (cancel) cannot be unbound. Invalid entries (unknown names, bad key specs, wrong-typed values, or overrides that conflict with another binding in the same context) are reported as warnings at startup and skipped — the rest of the config still applies.
A key spec is zero or more `-`-separated modifiers followed by one key name (e.g. `ctrl-shift-p`, `alt-enter`, `f5`, `K`). Modifiers: `ctrl`/`control`/`c`, `alt`/`meta`/`option`/`opt`/`m`, `shift`/`s`. Named keys: `enter`, `esc`, `tab`, `backspace`, `delete`, `insert`, `up`, `down`, `left`, `right`, `home`, `end`, `page-up`, `page-down`, `space`, `f1`–`f24`. Any other single character binds that character key (case-sensitive: `K` binds Shift+K); use `-` for the minus key (`ctrl--`).
You can also rebind interactively: in `/shortcuts`, press `Enter` on a shortcut row, then press the new key — the change is saved to this `keymap` section. See [Customizing Keybindings](/cli/reference/keyboard-shortcuts#customizing-keybindings).
### notify
Control terminal notifications when the agent finishes or needs user input. The CLI writes a BEL character (triggers terminal bell / visual bell), an OSC 9 escape sequence (triggers a system notification in iTerm2 and compatible terminals), and an OSC 777 sequence (desktop notification in rxvt-unicode and other terminals). Terminals that do not recognize these sequences safely ignore them.
| Value | Behavior |
| ---------- | -------------------------------------------------------------------------------------- |
| `"never"` | No notifications |
| `"smart"` | Notify only when the terminal window is unfocused (uses OSC focus reporting) (default) |
| `"always"` | Notify on every qualifying event regardless of focus |
### read\_config\_from
Control importing from other AI tool configurations:
| Option | Type | Default | Description |
| ---------- | ------------ | ------- | ------------------------------ |
| `cursor` | boolean/null | `true` | Import from `.cursor/rules/` |
| `windsurf` | boolean/null | `true` | Import from `.windsurf/rules/` |
| `claude` | boolean/null | `true` | Import from `.claude/` |
Set to `false` to disable a specific import. `null` is treated as `true`.
### proxy (user only)
Configure how the CLI routes its own outbound HTTP/HTTPS traffic (API calls, updates, MCP servers, etc.). This does not affect sandbox child-process networking (see `sandbox` below).
The `mode` field selects the proxy strategy:
| Mode | Behavior |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| `"system"` (default) | Respect environment variables (`HTTP_PROXY`, `HTTPS_PROXY`, `ALL_PROXY`) and platform-native PAC (Proxy Auto-Configuration) on macOS and Windows |
| `"manual"` | Route all CLI traffic through the explicit `url` |
| `"off"` | Connect directly — no proxy |
| Option | Type | Default | Description |
| ---------- | ----------- | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `mode` | string | `"system"` | Proxy strategy: `"system"`, `"manual"`, or `"off"` |
| `url` | string/null | `null` | Proxy URL. Required when `mode` is `"manual"`. Supports `http://`, `https://`, and `socks5://` schemes |
| `no_proxy` | string/null | `null` | Comma-separated list of hosts/domains that bypass the proxy. Uses the same syntax as the `NO_PROXY` environment variable (e.g. `"localhost,127.0.0.1,.corp.example.com"`). Applies in any mode |
**Example — corporate proxy:**
```json theme={null}
{
"proxy": {
"mode": "manual",
"url": "http://proxy.corp.example.com:8080",
"no_proxy": "localhost,127.0.0.1,.internal.corp"
}
}
```
**Example — disable proxy:**
```json theme={null}
{
"proxy": {
"mode": "off"
}
}
```
Administrators can set the same `proxy` block in the machine-wide [system configuration file](/cli/enterprise/system-config). The enterprise setting takes precedence, and configuring a proxy in both files is an error — remove the `proxy` section from your user config if your organization manages it.
### sandbox (user only)
Sandbox network filtering is currently unstable. If you need this feature, please reach out to your account representative for stability timelines.
Configure domain-level network filtering for the sandbox. When `--sandbox` is active and domain filtering is configured, a managed network proxy starts on loopback and the sandbox restricts all child traffic to route through it.
For a complete overview of how the sandbox works — including enterprise enforcement and how enterprise and user settings interact — see the [Sandbox documentation](/cli/sandbox).
The `--sandbox` flag enforces writable paths and `deny` rules at the OS level. Writable roots are derived from granted `Write(...)` scopes plus workspace directories; everything else is readable except paths hidden by `Read(...)` deny rules. `Write(...)` scopes granted mid-session dynamically expand the sandbox for subsequent commands.
If `--sandbox` is passed but sandbox resolution fails (e.g., sandboxing tools are unavailable on the current platform), the CLI will refuse to start rather than running unsandboxed. This fail-closed behavior ensures the security intent of `--sandbox` is never silently bypassed.
| Option | Type | Default | Description |
| ----------------- | --------- | -------- | ------------------------------------------------------------------------------------------------------------- |
| `allowed_domains` | string\[] | `[]` | Domain patterns allowed through the proxy. When non-empty, only matching domains are allowed (allowlist mode) |
| `denied_domains` | string\[] | `[]` | Domain patterns always blocked. Deny rules take precedence over allow rules |
| `network_mode` | string | `"full"` | `"full"` allows all HTTP methods; `"limited"` allows only GET/HEAD/OPTIONS |
**Domain pattern syntax:**
| Pattern | Matches |
| ---------------- | ----------------------------- |
| `example.com` | Exact match only |
| `*.example.com` | Any subdomain (not the apex) |
| `**.example.com` | Apex domain and any subdomain |
**Example:**
```json theme={null}
{
"sandbox": {
"allowed_domains": [
"github.com",
"**.npmjs.org",
"**.crates.io",
"**.pypi.org"
],
"denied_domains": ["evil.example.com"],
"network_mode": "full"
}
}
```
Domain filtering applies when the sandbox is active (`--sandbox`). Without `--sandbox`, the sandbox section is ignored.
For enterprise teams, admins can override domain lists via [Team Settings](/cli/enterprise/team-settings#sandbox-enforcement). Enterprise allowlists are authoritative (they replace your local `allowed_domains`), while enterprise denylists are additive (merged with your local `denied_domains`).
***
## JSON with Comments
Config files support JavaScript-style comments:
```json theme={null}
{
// Line comments
"agent": {
"model": "sonnet" // Inline comments
},
/* Block
comments */
"permissions": {}
}
```
# Configuration Precedence
Source: https://docs.devinenterprise.com/cli/reference/configuration/global-vs-local
How global, project, and local settings interact
Devin CLI loads configuration from multiple sources and merges them together. Understanding the precedence order helps you set up the right configuration for your team and personal preferences.
***
## Configuration Layers
From highest to lowest priority:
| Priority | Source | Notes |
| ----------- | ------------------------------------------------------------------------------ | -------------------- |
| 1 (highest) | Organization / Team Settings | Cannot be overridden |
| 2 | Session (interactive approvals) | In-memory only |
| 3 | Project Local (`.devin/config.local.json`) | Personal, gitignored |
| 4 | Project (`.devin/config.json`) | Shared with team |
| 5 (lowest) | User (`~/.config/devin/config.json`; `%APPDATA%\devin\config.json` on Windows) | Your defaults |
When the same setting is defined at multiple levels, the higher-priority source wins.
MCP servers follow the same precedence but live in dedicated files at each level: `~/.config/devin/mcp_config.json` (`%APPDATA%\devin\mcp_config.json` on Windows), `.devin/mcp_config.json`, and `.devin/mcp_config.local.json`. In CLI versions before v3000.3 (the Local 3.6 release), MCP servers are stored in the `mcpServers` key of the `config.json` files instead; newer versions migrate them to the dedicated files automatically on startup.
***
## When to Use Each Level
**Path:** `~/.config/devin/config.json` (`%APPDATA%\devin\config.json` on Windows)
Use for personal preferences that apply everywhere:
* Default model preference
* Theme preference
* Personal MCP servers (e.g., your own API keys)
* Global permission grants
```json theme={null}
{
"agent": { "model": "opus" },
"permissions": {
"allow": ["Read(**)", "Exec(git)"]
}
}
```
**Path:** `.devin/config.json`
Use for team standards committed to the repository. Only `permissions`, `read_config_from`, and `hooks` are available in `.devin/config.json`; MCP servers go in `.devin/mcp_config.json` alongside it:
* Shared MCP servers (with non-secret config, in `.devin/mcp_config.json`)
* Team permission policies
* Import settings
* Lifecycle hooks
```json theme={null}
// .devin/config.json
{
"permissions": {
"allow": ["Exec(npm run)", "Read(src/**)"],
"deny": ["Exec(sudo)"]
}
}
```
```json theme={null}
// .devin/mcp_config.json
{
"mcpServers": {
"github": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-github"]
}
}
}
```
**Path:** `.devin/config.local.json`
Use for personal overrides that shouldn't be committed:
* API keys and secrets (MCP servers go in `.devin/mcp_config.local.json`)
* Personal tool preferences for this project
* Permission overrides
```json theme={null}
// .devin/mcp_config.local.json
{
"mcpServers": {
"github": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-github"],
"env": {
"GITHUB_TOKEN": "ghp_my_personal_token"
}
}
}
}
```
Local config files are automatically excluded from git via `.git/info/exclude`.
Managed by your enterprise admin through the team settings dashboard. These settings cannot be overridden by individual users and enforce organization-wide policies like model restrictions and MCP server allowlists.
***
## What's Available at Each Level
Project configs (`.devin/config.json` and `.devin/config.local.json`) only support a subset of settings. The table below shows which settings are available at each level (`mcpServers` lives in the dedicated `mcp_config.json` files at each level, not in `config.json`):
| Setting | User config | Project config |
| ----------------------------------- | :---------: | :------------: |
| `permissions` | ✓ | ✓ |
| `mcpServers` (in `mcp_config.json`) | ✓ | ✓ |
| `read_config_from` | ✓ | ✓ |
| `hooks` | ✓ | ✓ |
| `agent` (model) | ✓ | ✗ |
| `theme_mode` | ✓ | ✗ |
| `unicode_mode` | ✓ | ✗ |
| `show_path` | ✓ | ✗ |
| `show_hints` | ✓ | ✗ |
| `include_gitignored_files` | ✓ | ✗ |
| `sandbox` | ✓ | ✗ |
Settings marked as user-config only can only be set in the user config (`~/.config/devin/config.json`; `%APPDATA%\devin\config.json` on Windows) and do not participate in the precedence hierarchy above.
***
## How Merging Works
The precedence table above only applies to settings that support multiple levels (`permissions`, `mcpServers`, `read_config_from`, `hooks`).
### Permissions
Permission lists are **merged** (combined) across levels. A denial at a higher level cannot be overridden by an allow at a lower level.
For example, if your organization denies `Exec(sudo)`, adding `Exec(sudo)` to your user allow list has no effect — the organization denial always wins. However, other permissions like `Read(**)` at the project level are applied normally.
### MCP Servers
MCP server configs are **merged by name**. A server defined at a higher level overrides the same-named server at a lower level.
For example, if both your user config and project config define a "github" server, the project config version wins because it has higher priority than user config.
### Hooks
Hooks are **collected** from all sources and all run. A hook defined in the user config runs alongside hooks defined in the project config — they do not override each other.
***
## Project Root Detection
Devin CLI finds your project root by looking for a `.git` or `.jj` directory, walking up from your current working directory. Project config (`.devin/`) is loaded from the project root.
If you have nested `.devin/` directories (e.g., in a monorepo), subdirectory configs take precedence over ancestor configs.
***
## File Discovery Summary
| File | Found by | Shared? |
| ----------------------------------- | ------------------- | --------------- |
| `~/.config/devin/config.json` | XDG path | No |
| `.devin/config.json` | Walking up from cwd | Yes (committed) |
| `.devin/config.local.json` | Walking up from cwd | No (gitignored) |
| `~/.config/devin/mcp_config.json` | XDG path | No |
| `.devin/mcp_config.json` | Walking up from cwd | Yes (committed) |
| `.devin/mcp_config.local.json` | Walking up from cwd | No (gitignored) |
| `.devin/skills/*/SKILL.md` | Project root | Yes (committed) |
| `~/.config/devin/skills/*/SKILL.md` | XDG path | No |
| `AGENTS.md` | Project root | Yes (committed) |
| `~/.config/devin/AGENTS.md` | XDG path | No |
**Windows:** Paths shown as `~/.config/devin/` use the XDG convention for Linux/macOS. On Windows, these resolve to `%APPDATA%\devin\` (typically `C:\Users\\AppData\Roaming\devin\`).
# Configuration Import
Source: https://docs.devinenterprise.com/cli/reference/configuration/read-config-from
Control how Devin CLI imports settings from Cursor, Windsurf, Claude Code, GitHub Copilot, OpenCode, and Zed
Devin CLI can automatically import rules and configuration from other AI coding tools installed in your project. This happens when standard project rule files or configuration files from Cursor, Windsurf, Claude Code, GitHub Copilot, OpenCode, or Zed are detected in your workspace.
***
## How It Works
When you start a session, Devin CLI checks for standard project rule files and configuration files from supported tools, then imports what it finds.
### Standard project rules
| What's imported | Source files |
| --------------- | ------------------------------------------------------------ |
| Rules | `AGENTS.md`, `AGENTS.local.md`, `AGENT.md`, `.windsurfrules` |
### Cursor
| What's imported | Source files |
| --------------- | ------------------------------------------- |
| Rules | `.cursor/rules/*.md`, `.cursor/rules/*.mdc` |
| MCP servers | `.cursor/mcp.json` |
### Windsurf
| What's imported | Source files |
| --------------- | ------------------------------------------------------------------------------------------ |
| Rules | `.windsurf/rules/*.md`, `.windsurf/global_rules.md` (at workspace root and subdirectories) |
| Skills | `.windsurf/skills/` (project), `~/.codeium//skills/` (global, channel-dependent) |
| MCP servers | `~/.codeium//mcp_config.json` (channel-dependent) |
Devin CLI reads from the Windsurf config directory matching its own channel: stable reads from `~/.codeium/windsurf/`, next reads from `~/.codeium/windsurf-next/`, insiders reads from `~/.codeium/windsurf-insiders/`. `.windsurf/rules/` directories can exist at multiple levels in your project. Rules at the workspace root are loaded at session start. Rules in subdirectories are discovered lazily when the agent accesses files in that directory.
Windsurf workflows (`.windsurf/workflows/` and `~/.codeium//global_workflows/`) are **not** imported as skills.
### Claude Code
| What's imported | Source files |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Rules | `CLAUDE.md`, `~/.claude/CLAUDE.md` |
| Skills | `.claude/skills/**/SKILL.md` |
| Commands (as skills) | `.claude/commands/**/*.md` |
| MCP servers | `.mcp.json`, `.claude/settings.json`, `.claude/settings.local.json`, `~/.claude.json`, `~/.claude/settings.json`, `~/.claude/settings.local.json`, `~/.claude/mcp_servers.json` |
### GitHub Copilot
| What's imported | Source files |
| --------------- | -------------------------------------------------------------------------------- |
| Skills | `.github/skills/**/SKILL.md` (project), `~/.copilot/skills/**/SKILL.md` (global) |
Copilot skills use the same `SKILL.md` format as Devin skills, so they are read in place rather than migrated. If `COPILOT_HOME` is set, global skills are read from `$COPILOT_HOME/skills/` instead of `~/.copilot/skills/`.
Copilot custom instructions (`.github/copilot-instructions.md` and `.github/instructions/*.instructions.md`) are **not** imported.
### OpenCode
| What's imported | Source files |
| --------------- | ---------------------------------------------------------------------- |
| MCP servers | `opencode.json` (project), `~/.config/opencode/opencode.json` (global) |
OpenCode uses a different MCP schema from the standard format. Commands can be arrays or strings, environment variables use the `"environment"` key, and servers use an `"enabled"` flag (inverted from the standard `"disabled"` flag). These are automatically converted during import.
### Zed
| What's imported | Source files |
| --------------- | ---------------------------------------------------------------------- |
| MCP servers | `.zed/settings.json` (project), `~/.config/zed/settings.json` (global) |
Zed uses a `"context_servers"` key in its settings file.
***
## Disabling Configuration Import
To stop importing from a specific tool, set it to `false` in your config:
```json theme={null}
// ~/.config/devin/config.json
// (on Windows: %APPDATA%\devin\config.json)
{
"read_config_from": {
"agents_standard": false,
"cursor": false,
"windsurf": false,
"claude": false,
"copilot": false,
"opencode": false,
"zed": false
}
}
```
```json theme={null}
// .devin/config.json
{
"read_config_from": {
"windsurf": false
}
}
```
You can disable imports selectively — for example, import from Cursor but not Windsurf:
```json theme={null}
{
"read_config_from": {
"cursor": true,
"windsurf": false
}
}
```
***
## Options
| Option | Type | Default | Description |
| ----------------- | ------- | ------- | --------------------------------------------------------------------------------------------------- |
| `agents_standard` | boolean | `true` | Import standard project rules from `AGENTS.md`, `AGENTS.local.md`, `AGENT.md`, and `.windsurfrules` |
| `cursor` | boolean | `true` | Import rules and MCP servers from Cursor config files |
| `windsurf` | boolean | `true` | Import rules, skills, and MCP servers from Windsurf |
| `claude` | boolean | `true` | Import rules, skills, commands, and MCP servers from Claude Code |
| `copilot` | boolean | `true` | Import skills from GitHub Copilot's project and global skill directories |
| `opencode` | boolean | `true` | Import MCP servers from OpenCode config files |
| `zed` | boolean | `true` | Import MCP servers from Zed settings files |
Setting a value to `true` (or leaving it unset) enables import. Setting it to `false` disables import for that tool.
***
## Default Behavior
If you don't explicitly configure `read_config_from`, all imports are enabled by default. Set any option to `false` to disable imports from that tool.
# Keyboard Shortcuts
Source: https://docs.devinenterprise.com/cli/reference/keyboard-shortcuts
Common keyboard shortcuts in Devin CLI
Every shortcut on this page is a **default** — shortcuts are rebindable. Run `/shortcuts` to browse and rebind them interactively, or edit the [`keymap`](/cli/reference/configuration/config-file#keymap) section of your config file directly.
## Input Shortcuts
These shortcuts work while typing at the prompt.
| Shortcut | Description |
| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------- |
| `Enter` | Submit your message |
| `Shift+Enter`\* or `Alt+Enter` | Insert a newline (for multi-line input) |
| `Shift+Tab` | Cycle between modes (Normal, Accept Edits, Smart, Bypass, Autonomous) |
| `Ctrl+C` | Cancel current input (clears text), or cancel running agent |
| `Ctrl+D` | Exit (when input is empty) |
| `Esc` | Cancel running agent |
| `Ctrl+G` | Open external editor for composing your message |
| `Ctrl+R` | Open fuzzy search over previous prompts and insert the selected prompt |
| `Ctrl+O` | Open full-screen viewer for the thinking trace |
| `Ctrl+L` | Redraw / refresh the screen |
| `Ctrl+V` or `Shift+Insert` | Paste from clipboard (images appear in input area; use Left/Right to navigate, Backspace to remove) |
| `!` | Enter bash mode to run a shell command directly (when input is empty). Press `Backspace` or `Esc` on an empty input to exit bash mode |
| `@` | Open file/directory autocomplete to add context |
On macOS, `Alt` is the `Option` key. Some shortcuts below use `Alt` (Option) as a modifier. We recommend [configuring Option as Meta](/cli/reference/terminal-compatibility#configuring-option-as-meta-on-macos) for the best experience.
\* Requires a [compatible terminal](/cli/reference/terminal-compatibility). Terminals that do not support the Kitty keyboard protocol cannot distinguish `Shift+Enter` from `Enter`. Use `Alt+Enter` or `Ctrl+J` instead.
***
## Mode & Model Shortcuts
| Shortcut | Description |
| ------------------------ | ------------------------------------------------------------------------------------- |
| `Shift+Tab` | Cycle to the next mode (Normal → Accept Edits → Smart → Bypass → Autonomous → Normal) |
| `Alt+T` (macOS: `Opt+T`) | Cycle thinking level for the current model |
[Smart mode](/cli/reference/permissions#smart-mode) is rolling out gradually; the cycle skips it when it is not enabled for your account. Autonomous only appears in [sandbox sessions](/cli/sandbox), where it is the only available permission mode.
You can also switch modes with slash commands: `/normal`, `/accept-edits`, `/smart`, `/plan`, `/bypass`, or `/mode `. Use `/ask ` as a oneshot command to ask questions without switching modes.
***
## Rebinding Shortcuts
Run `/shortcuts` to open an interactive list of every shortcut, grouped by category. Type to search across all categories, press `Enter` on an action to rebind it, then press the key combination you want. Each row shows the action's `context.action` identifier (for example `editor.accept_line`) — that is the key to use when editing the config file by hand. Rebinding from `/shortcuts` saves the new binding to your user config.
To set bindings directly, add a [`keymap`](/cli/reference/configuration/config-file#keymap) section to your config file:
```json theme={null}
// ~/.config/devin/config.json
{
"keymap": {
"global": {
"clear_screen": "ctrl-shift-k"
}
}
}
```
`Ctrl+C` cannot be unbound — it always cancels the running agent.
***
## Text Editing
The input uses readline-style or Emacs-style keybindings for text editing.
***
## Customizing Keybindings
Every keybinding can be viewed — and most can be changed — from inside the CLI or via the config file.
### Browsing shortcuts with `/shortcuts`
Run `/shortcuts` to open an interactive picker listing every keybinding, grouped by category (Input, Mode & model, Text editing, Lists & pickers, Completion, Prompts & panels, Config editor, and more). Each row shows the active keys, a description, and the shortcut's `context.action` identifier (e.g. `editor.insert_newline`) — the identifier you use for config-file overrides. Type to search across all categories.
### Rebinding interactively
In `/shortcuts`, press `Enter` on a shortcut row, then press the new key combination:
```
Press the new key for Open external editor (readbox_input.open_external_editor)
Currently: ctrl+g
any key rebind · esc cancel
```
The change takes effect immediately and is saved to the `keymap` section of your user config file, so it persists across sessions. Press `Esc` to cancel without changing anything.
A few global "chrome" keys (clear screen, the thinking-trace viewer, force full redraw) can't be rebound interactively — the picker shows `can't be rebound` — because the rebind prompt must capture every key. You can still override them via the [config file](#rebinding-via-the-config-file).
### Rebinding via the config file
Add a `keymap` section to your user config (`~/.config/devin/config.json`; `%APPDATA%\devin\config.json` on Windows). Overrides are keyed by context, then action:
```json theme={null}
{
"keymap": {
"global": {
"clear_screen": "ctrl-shift-k",
"history_search": ["ctrl-r", "f5"],
"feedback_up": []
},
"editor": {
"insert_newline": ["shift-enter", "alt-enter", "ctrl-j"]
}
}
}
```
* A value may be a single key spec, a list of specs (all of them trigger the action), or an empty list `[]` to unbind the action.
* Overrides fully replace the built-in defaults for that action; actions you don't list keep their defaults.
* Find the `context.action` names in `/shortcuts` — each row displays its identifier.
See the [config file reference](/cli/reference/configuration/config-file#keymap) for the full key spec syntax.
### Key spec syntax
A key spec is zero or more `-`-separated modifiers followed by one key name, e.g. `ctrl-shift-p`, `alt-enter`, `f5`, `K`:
| Element | Values |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Modifiers | `ctrl`/`control`/`c`, `alt`/`meta`/`option`/`opt`/`m`, `shift`/`s` — case-insensitive, any order, no duplicates |
| Named keys | `enter`/`return`, `esc`/`escape`, `tab`, `backspace`, `delete`/`del`, `insert`/`ins`, `up`, `down`, `left`, `right`, `home`, `end`, `page-up`/`pageup`/`pgup`, `page-down`/`pagedown`/`pgdn`, `space`, `f1`–`f24` — case-insensitive |
| Characters | Any other single character binds that character key, keeping its case: `K` (equivalently `shift-k`) binds the shifted letter. Use `-` for the minus key (`ctrl--` is Ctrl+minus) |
### Validation and conflicts
Invalid entries are reported as warnings at startup and skipped — the rest of your overrides and config still apply:
```
Warning: keymap: unknown context `bogus_context`
Warning: keymap.editor: unknown action `bogus_action`
Warning: keymap: override creates a conflict (editor: `ctrl+a` bound to both
`beginning_of_line` and `kill_line`); restoring built-in default for `editor.kill_line`
```
This covers unknown context/action names, malformed key specs, wrong-typed values, and overrides that collide with another binding in the same context (the conflicting override reverts to its default). `Ctrl+C` (cancel) cannot be unbound.
# Permissions
Source: https://docs.devinenterprise.com/cli/reference/permissions
Control what the agent can do with fine-grained permission rules
The permission system controls which actions the agent can perform without asking for your approval. You can pre-approve safe actions, block dangerous ones, and always prompt for sensitive operations.
***
## Default Permission Behavior
Devin CLI uses a tiered permission system to balance power and safety. The default behavior depends on the current [mode](/cli/essential-commands#modes):
Each cell shows whether that tool runs automatically (**Auto**, no prompt) or waits for your approval (**Prompt**) in that mode:
| Tool type | Example | Normal | Accept Edits | Smart | Bypass | Autonomous (sandbox) |
| ----------------------------- | ---------------------- | ------ | ------------------- | --------------------- | ------ | -------------------- |
| Read-only | File reads, grep, glob | Auto | Auto | Auto | Auto | Auto |
| Fetch | HTTP requests | Prompt | Prompt | Auto when judged safe | Auto | Auto |
| Bash commands | Shell execution | Prompt | Prompt | Auto when judged safe | Auto | Auto |
| File edits via `edit`/`write` | Edit/write files | Prompt | Auto (in workspace) | Auto (in workspace) | Auto | Prompt |
In **Normal mode** (the default), read-only operations are auto-approved while writes and shell commands require your explicit approval. Each time you approve an action, you can choose to allow it once, for the session, or permanently for the project.
In **Accept Edits mode**, file edits within the workspace are auto-approved, but shell commands and writes outside the workspace still prompt.
In **Smart mode**, workspace edits auto-approve as they do in Accept Edits, and every other action is judged by a fast model that auto-runs it only when it is clearly safe. Anything else prompts as usual. See [Smart Mode](#smart-mode) below.
In **Bypass mode**, all tool calls are auto-approved without prompting.
In **Autonomous mode**, shell commands and network fetches auto-approve because the OS-level sandbox enforces what they can touch. Direct file edits via the `edit`/`write` tools still prompt, because those tools operate outside the sandbox. Autonomous is only available when the [OS-level sandbox](#autonomous-mode) is active.
Smart, Bypass, and Autonomous modes do **not** override organization-level permissions. Admin-enforced deny and ask rules configured via [Team Settings](/cli/enterprise/team-settings) remain active regardless of the user's permission mode. See [Precedence](#precedence) for details.
### Smart Mode
Smart sits between Accept Edits and Bypass. Workspace file edits auto-approve exactly as they do in Accept Edits. For every other action — shell commands, web fetches, MCP tools, writes outside the workspace — a fast model judges whether the action is safe to run unattended. If it is clearly safe, the action runs without a prompt; if it is not, or the model is uncertain or unavailable, you get the normal approval prompt.
```bash theme={null}
/smart
# or
/mode smart
```
You can also cycle to Smart with `Shift+Tab`, pick it in the mode selector, or start in it:
```bash theme={null}
devin --permission-mode smart
# or
DEVIN_PERMISSION_MODE=smart devin
```
The model's judgment is scoped to routine development work — building, testing, linting, formatting, and inspecting the project. Some categories are **never** auto-approved in Smart mode, no matter what the model thinks:
* Package installs (`npm install`, `pip install`, `cargo install`, `brew install`, …)
* Mutating `git` operations (read-only subcommands such as `git status` are still eligible)
* `rm`, `sudo`, and other destructive or privilege-escalating commands
* `kubectl delete` and destructive cloud-CLI operations (`aws`, `gcloud`, `az`, `terraform`, …)
* Anything that reads or writes dotenv files, key material, Git config, or the agent's own configuration
Smart differs from the neighboring modes in what it delegates:
| | Accept Edits | Smart | Bypass |
| ----------------------------------------------------------- | ------------- | ----------------------------------------- | ----------- |
| Workspace file edits | Auto | Auto | Auto |
| Shell commands and fetches | Always prompt | Auto only when the model judges them safe | Always auto |
| High-risk commands (installs, `rm`, `sudo`, mutating `git`) | Always prompt | Always prompt | Always auto |
Your own rules still come first. Smart's judgment only applies where no rule already decides the call, so a `deny` rule blocks the action and an `ask` rule always prompts, exactly as described in [How Permissions Work](#how-permissions-work). Organization-level deny and ask rules are likewise unaffected.
Smart mode is rolling out gradually, so it may not appear in your mode selector or `Shift+Tab` cycle yet.
### Autonomous Mode
Autonomous is the permission mode that pairs with the `--sandbox` flag. Conceptually it is roughly "Accept Edits in the current workspace" plus the ability to run any shell command, with both behaviors contained by the OS-level sandbox. When sandbox is active:
* **It is the only permission mode available.** Normal, Accept Edits, Smart, and Bypass are hidden in sandbox sessions. Plan mode remains available.
* **Shell commands and fetches auto-approve** instead of prompting, because the sandbox enforces what they can read, write, and reach over the network.
* **Direct file edits via the `edit` and `write` tools still prompt.** These tools run inside the CLI process rather than inside the sandbox, so they cannot be bounded by it. Granting a `Write(...)` scope at the prompt dynamically expands the sandbox so subsequent shell commands can write there.
* **`Write(...)` scopes granted mid-session dynamically expand the sandbox** for subsequent commands. Mid-session `Read(...)` approvals affect only the agent's own tools; paths hidden by `Read(...)` deny rules stay hidden for the whole session.
```bash theme={null}
devin --sandbox --permission-mode autonomous
```
Use Bypass when you want unrestricted execution without OS-level isolation; use `--sandbox` (which selects Autonomous) when you want unattended execution with OS-enforced limits on filesystem and network access. See the [sandbox configuration reference](/cli/reference/configuration/config-file#sandbox) for details on writable roots, deny rules, and domain filtering, and [Team Settings → Sandbox Enforcement](/cli/enterprise/team-settings#sandbox-enforcement) for enterprise controls.
***
## How Permissions Work
When the agent calls a tool, the permission system checks your rules in priority order:
1. **Deny rules** — Checked first. If matched, the action is blocked immediately.
2. **Ask rules** — Checked second. If matched, you're always prompted (overrides any allow rules).
3. **Allow rules** — Checked last. If matched, the action proceeds without prompting.
4. **Default** — If no rule matches, you're prompted for approval.
Because deny is checked before ask, and ask is checked before allow, a deny rule always wins. If the same scope matches both a deny and an ask rule, the deny takes effect.
***
## Configuration
Add permissions to your config file's `permissions` section:
On Windows, the user config path is `%APPDATA%\devin\config.json` (typically `C:\Users\\AppData\Roaming\devin\config.json`) rather than `~/.config/devin/config.json`. See [Configuration File](/cli/reference/configuration/config-file#file-locations) for details.
```json theme={null}
// .devin/config.json
{
"permissions": {
"allow": [
"Read(src/**)",
"Exec(npm run)"
],
"deny": [
"Exec(rm)"
]
}
}
```
```json theme={null}
// ~/.config/devin/config.json
{
"permissions": {
"allow": [
"Read(**)",
"Exec(git)"
]
}
}
```
```json theme={null}
// .devin/config.local.json
{
"permissions": {
"allow": [
"Exec(docker compose)"
]
}
}
```
***
## Permission Syntax
There are two types of permission matchers: **scope-based** (controlling what paths/commands/URLs are accessible) and **tool-based** (controlling which tools can be used).
### Scope-Based Permissions
Controls file read access. The glob pattern matches file paths.
```json theme={null}
"allow": [
"Read(src/**)", // All files under src/
"Read(~/.config/**)", // Home config files
"Read(/tmp/**)" // Temp directory
]
```
Directory paths automatically match all files within them.
Controls file write/edit access.
```json theme={null}
"allow": [
"Write(src/**)", // Can write anywhere in src/
"Write(tests/**)" // Can write test files
],
"deny": [
"Write(*.lock)", // Can't modify lock files
"Write(.env*)" // Can't modify env files
]
```
Controls shell command execution. Matches commands that start with the given prefix.
```json theme={null}
"allow": [
"Exec(git)", // git, git status, git commit...
"Exec(npm run)", // npm run test, npm run build...
"Exec(python)" // python, python script.py...
],
"deny": [
"Exec(rm)", // Blocks rm, rm -rf, etc.
"Exec(sudo)" // Blocks sudo commands
]
```
`Exec(git)` matches "git", "git status", "git commit -m 'msg'" but NOT "gitk" or "github-cli". The prefix must match as a complete word.
Controls HTTP fetch access using URL patterns.
```json theme={null}
"allow": [
"Fetch(https://api.github.com/*)", // GitHub API
"Fetch(https://*.example.com/*)", // All example.com subdomains
"Fetch(domain:npmjs.org)" // Any URL on npmjs.org
]
```
URL patterns follow the [WHATWG URL Pattern](https://urlpattern.spec.whatwg.org/) standard. The `domain:` shorthand matches any path on the exact domain.
### Tool-Based Permissions
Match by tool name to control entire tools:
```json theme={null}
{
"permissions": {
"deny": [
"edit", // Block all file edits
"exec" // Block all command execution
],
"allow": [
"read", // Allow all file reads
"grep", // Allow all searches
"glob" // Allow all file finding
]
}
}
```
**Available tool names:** `read`, `edit`, `grep`, `glob`, `exec`
### MCP Tool Permissions
Control access to MCP server tools:
```json theme={null}
{
"permissions": {
"allow": [
"mcp__github__list_issues", // Specific tool on specific server
"mcp__github__*", // All tools on github server
"mcp__*" // All MCP tools
],
"deny": [
"mcp__github__delete_repo" // Block specific dangerous tool
]
}
}
```
| Pattern | Matches |
| ------------------- | ------------------------ |
| `mcp__server__tool` | One specific tool |
| `mcp__server__*` | All tools on a server |
| `mcp__*` | All MCP tools everywhere |
***
## Path Patterns
Glob patterns in `Read()` and `Write()` support:
| Pattern | Meaning |
| ------- | ----------------------------------------------- |
| `*` | Any characters in a single path segment |
| `**` | Any characters across path segments (recursive) |
| `~` | Home directory expansion |
**Examples:**
```json theme={null}
"allow": [
"Read(**)", // All files everywhere
"Read(src/**/*.ts)", // All TypeScript in src/
"Write(~/projects/myapp/**)" // Write to specific project
]
```
Use an absolute path prefix (e.g., `Read(/**)`) when you want to match all files on the system. A bare `Read(**)` without a leading `/` is resolved relative to your current working directory, so it only matches files under that directory — not files accessed via absolute paths elsewhere.
***
## Persistence Options
When the agent asks for permission during a session, you can choose how to save your decision:
| Option | Where it's saved | Shared with team? |
| ------------------------- | ------------------------------------------------------------------------ | ----------------- |
| Allow once | Not saved | No |
| Allow for session | In memory only | No |
| Allow for project | `.devin/config.json` | Yes |
| Allow for project (local) | `.devin/config.local.json` | No |
| Allow globally | `~/.config/devin/config.json` (`%APPDATA%\devin\config.json` on Windows) | No |
Command prompts offer both scopes explicitly: "Yes, always allow `` commands in ``" saves the grant for the current project, and "Yes, always allow `` commands in all projects" saves it to your user config so it applies everywhere. Web-fetch prompts for a specific URL or domain add an equivalent "Yes, always allow all web fetches" option that whitelists fetching in one step.
### Editing a Command Before Approving
Command approval prompts are not just yes/no. Alongside the approval options, a command prompt offers:
| Option | Effect |
| -------------------------- | ------------------------------------------------------------------------------------------------------------------ |
| Edit command | Opens the proposed command for inline editing so you can tweak it before it runs |
| Describe change to command | Rewrites the command from a plain-language description of what you want it to do, for you to review before running |
### MCP Server-Level Grants
When prompted for a specific MCP tool (e.g., `list_issues` on the Figma server), the permission prompt also offers broader server-level options:
| Option | Effect |
| --------------------------------------------- | ---------------------------------------------------------- |
| Allow this tool (this session) | Grants access to the specific tool for the current session |
| Always allow this tool | Persists the specific tool grant to config |
| Allow all tools on this server (this session) | Grants access to every tool on the server for the session |
| Always allow tools on this server | Persists server-wide access to config |
This lets you quickly grant blanket access to a trusted MCP server without approving each tool individually.
***
## Precedence
When multiple permission sources define rules, they're merged with this precedence (highest first):
1. Organization/team settings (if enterprise)
2. Session-level grants (interactive approvals)
3. Project local config (`.devin/config.local.json`)
4. Project config (`.devin/config.json`)
5. User config (`~/.config/devin/config.json`; `%APPDATA%\devin\config.json` on Windows)
Organization-level denials cannot be overridden by project or user config. This ensures enterprise policies are enforced.
***
## Examples
### Minimal Development Setup
Allow common read-only operations, prompt for everything else:
```json theme={null}
{
"permissions": {
"allow": [
"Read(**)",
"Exec(git status)",
"Exec(git diff)",
"Exec(git log)"
]
}
}
```
### Full Trust for a Project
Auto-approve most operations within the project:
```json theme={null}
{
"permissions": {
"allow": [
"Read(**)",
"Write(src/**)",
"Write(tests/**)",
"Exec(npm)",
"Exec(git)",
"Exec(node)"
],
"deny": [
"Exec(rm -rf)",
"Exec(sudo)",
"Write(.env*)"
]
}
}
```
### Locked-Down Enterprise
Restrict to specific safe operations, always prompt for writes:
```json theme={null}
{
"permissions": {
"allow": [
"Read(src/**)",
"Exec(git status)",
"Exec(git diff)",
"Exec(npm run lint)"
],
"deny": [
"Exec(rm)",
"Exec(sudo)",
"Write(.env*)"
],
"ask": [
"Write(**)",
"exec"
]
}
}
```
In this example, writes to `.env*` are denied outright, all other writes always prompt the user, and only a few read-only commands are auto-approved. Since deny is checked before ask, the `.env*` denial takes priority over the `Write(**)` ask rule.
# Terminal Compatibility
Source: https://docs.devinenterprise.com/cli/reference/terminal-compatibility
Supported terminals and recommendations for the best Devin CLI experience
Devin CLI works across a wide range of terminal emulators, but some terminals offer a better experience than others. This page covers compatibility levels, recommendations, and configuration tips.
***
## Compatibility Overview
Terminals are grouped into three tiers based on their feature support:
### Fully Supported (all features work)
These terminals support the [Kitty keyboard protocol](https://sw.kovidgoyal.net/kitty/keyboard-protocol/), which enables reliable detection of key combinations like `Shift+Enter` for multi-line input.
| Terminal | Platform | Notes |
| ------------------------------------------- | ---------------------- | --------------------------------------------------------------------- |
| [Kitty](https://sw.kovidgoyal.net/kitty/) | macOS†, Linux | Recommended for power users. Used by the developers of Devin CLI. |
| [Ghostty](https://ghostty.org/) | macOS†, Linux | Recommended for power users. Used by the developers of Devin CLI. |
| [WezTerm](https://wezfurlong.org/wezterm/) | macOS†, Linux, Windows | Recommended for power users. |
| [iTerm2](https://iterm2.com/) | macOS† | Recommended for most users. Version 3.5+ required for best support. |
| [Windows Terminal](https://aka.ms/terminal) | Windows | Recommended for most users. 1.25 or higher required for best support. |
### Supported (some features limited)
These terminals work with Devin CLI but are not ideal because they do not support the Kitty keyboard protocol. For example, `Shift+Enter` will not insert a newline — use `Alt+Enter` or `Ctrl+J` instead.
| Terminal | Platform | Notes |
| -------------------------------------------------------------------- | ---------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| [Terminal.app](https://support.apple.com/guide/terminal/welcome/mac) | macOS† | Built-in macOS terminal. Requires [Option-as-Meta configuration](#configuring-option-as-meta-on-macos) for `Alt` shortcuts. |
| Git Bash | Windows | Included with [Git for Windows](https://git-scm.com/download/win). |
| DEC VT100 | Various | Set terminal mode to `legacy` in `/config`. |
| Generic ANSI terminals | Various | Any terminal with basic ANSI escape code support. |
| [Alacritty](https://alacritty.org/) | macOS†, Linux, Windows | Strongly discouraged / not recommended for best performance. |
† On macOS, we recommend [configuring Option as Meta](#configuring-option-as-meta-on-macos) for the best experience with `Alt`-based shortcuts.
On macOS terminals that have not been configured for Option-as-Meta, `Alt` (Option) shortcuts like `Alt+Enter` for multi-line input won't work. See [Configuring Option-as-Meta on macOS](#configuring-option-as-meta-on-macos) below.
### Unsupported
These terminals are not supported and may exhibit significant issues. We highly recommend switching to a supported terminal.
| Terminal | Platform | Notes |
| ----------------- | -------- | --------------------------------------------------------------------------------------- |
| cmd.exe (conhost) | Windows | Legacy Windows command prompt. Use [Windows Terminal](https://aka.ms/terminal) instead. |
***
## Recommendations
| Platform | Recommendation |
| ------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| **Windows** | [Windows Terminal](https://aka.ms/terminal) 1.25 or higher |
| **macOS** (general) | [iTerm2](https://iterm2.com/) |
| **macOS / Linux** (power users) | [Kitty](https://sw.kovidgoyal.net/kitty/), [Ghostty](https://ghostty.org/), or [WezTerm](https://wezfurlong.org/wezterm/) |
***
## Configuring Option-as-Meta on macOS
On macOS, the Option key is used as a compose key by default in most terminals, which means `Alt`-based shortcuts (like `Alt+Enter` for multi-line input or `Alt+T` for cycling thinking level) won't work until you configure the terminal to treat Option as Meta/Alt.
1. Open **iTerm2 > Settings** (or press `Cmd+,`)
2. Go to **Profiles > Keys > General**
3. Set **Left Option Key** to **Esc+**
4. Optionally set **Right Option Key** to **Esc+** as well
[iTerm2 documentation](https://iterm2.com/documentation-preferences-profiles-keys.html)
1. Open **Terminal > Settings** (or press `Cmd+,`)
2. Go to **Profiles** and select your active profile
3. Click the **Keyboard** tab
4. Check **Use Option as Meta Key**
[Apple documentation](https://support.apple.com/guide/terminal/change-profiles-keyboard-settings-trmlkbrd/mac)
Add the following to your `alacritty.toml` configuration file:
```toml theme={null}
[keyboard]
option_as_alt = "Both"
```
[Alacritty configuration reference](https://alacritty.org/config-alacritty.html)
Add the following to your `kitty.conf` configuration file:
```text theme={null}
macos_option_as_alt yes
```
Restart Kitty after making this change.
[Kitty documentation](https://sw.kovidgoyal.net/kitty/conf/#opt-kitty.macos_option_as_alt)
Add the following to your Ghostty configuration file:
```text theme={null}
macos-option-as-alt = true
```
Restart Ghostty after making this change.
[Ghostty documentation](https://ghostty.org/docs/config/reference#macos-option-as-alt)
Add the following to your `~/.wezterm.lua` configuration file:
```lua theme={null}
config.send_composed_key_when_left_alt_is_pressed = false
config.send_composed_key_when_right_alt_is_pressed = false
```
[WezTerm documentation](https://wezfurlong.org/wezterm/config/lua/config/send_composed_key_when_left_alt_is_pressed.html)
# Analytics
Source: https://docs.devinenterprise.com/desktop/accounts/analytics
View individual user analytics, team analytics, usage patterns, and metrics for your Devin Desktop usage including code completion stats and AI-written code percentage.
## Individuals
User analytics are available for viewing and sharing on your [analytics page](/enterprise/security-access/personal-analytics).
See your completion stats, look into your language breakdown, and unlock achievement badges by using Devin Desktop in your daily workflow.
## Teams
Devin Desktop makes managing your team easy from one dashboard.
You will need team admin privileges in order to view the following team links.
Team leads and managers can also see an aggregate of their team members' usage patterns and analytics, including Percent of Code Written (PCW) by AI, total lines of code written, total tool calls, credit consumption, and more.
## Personal Analytics
Enterprise users can also view their own Devin ACU consumption across every organization from the **My analytics** page. See [Personal Analytics](/enterprise/security-access/personal-analytics) for details.
# Analytics API
Source: https://docs.devinenterprise.com/desktop/accounts/api-reference/analytics-api-introduction
Enterprise analytics API for querying Devin Desktop usage data including autocomplete, chat, command, and Cascade metrics.
## Overview
The Devin Desktop Analytics API enables enterprise customers to programmatically access detailed usage analytics for their teams. Query data from autocomplete, chat, command features, and Cascade with flexible filtering, grouping, and aggregation options.
API data is refreshed every 3 hours
## Common Parameters
Most Analytics API endpoints support these common parameters:
| Parameter | Type | Required | Description |
| ----------------- | ------ | -------- | ------------------------------------------------------------ |
| `service_key` | string | Yes | Your service key for authentication |
| `group_name` | string | No | Filter results to a specific group |
| `start_timestamp` | string | Varies | Start time in RFC 3339 format (e.g., `2023-01-01T00:00:00Z`) |
| `end_timestamp` | string | Varies | End time in RFC 3339 format (e.g., `2023-12-31T23:59:59Z`) |
## Available Endpoints
The Analytics API provides three main endpoints:
1. **[User Page Analytics](/desktop/accounts/api-reference/user-page-analytics)** - Get user activity data from the teams page
2. **[Cascade Analytics](/desktop/accounts/api-reference/cascade-analytics)** - Query Cascade-specific usage metrics
3. **[Custom Analytics](/desktop/accounts/api-reference/custom-analytics)** - Flexible querying with custom selections, filters, and aggregations
# Analytics API v2
Source: https://docs.devinenterprise.com/desktop/accounts/api-reference/analytics-v2-introduction
Next-generation analytics API for querying consumption data with Bearer-token authentication, flexible grouping, and cursor-based pagination.
The v2 APIs are in **alpha** and subject to change at any time.
## Overview
Analytics API v2 is the next generation of the Devin Desktop Analytics API. It exposes consumption
analytics (credits and ACUs) through clean REST endpoints with query-parameter filtering, flexible
grouping, cursor-based pagination, and response caching.
v2 endpoints are currently served under the **`/api/v2alpha`** prefix while the API surface is
finalized. The base URL is `https://server.codeium.com`.
## What's new in v2
The biggest change from [v1](/desktop/accounts/api-reference/analytics-api-introduction) is **authentication**.
| | v1 Analytics API | v2 Analytics API |
| ---------- | ------------------------------------------- | ------------------------------------------------- |
| Transport | `POST` with a JSON request body | `GET` with query parameters |
| Auth | `service_key` field **in the request body** | **`Authorization: Bearer ` header** |
| Permission | Varies per endpoint | **Analytics Read** |
| Pagination | None | Cursor-based (`next_page_cursor` / `page_cursor`) |
| Caching | None | `ETag` + `If-None-Match` (`304 Not Modified`) |
## Authentication
v2 uses **Bearer token** authentication. Pass your service key in the `Authorization` header instead
of in the request body:
```
Authorization: Bearer
```
The service key must have the **Analytics Read** permission.
### Creating a service key
1. Navigate to your [team settings page](https://windsurf.com/team/settings)
2. Go to the "Service Keys" section
3. Create a new service key with the **Analytics Read** permission
4. Use the key as a Bearer token in the `Authorization` header
Keep your service keys secure and never expose them in client-side code or public repositories.
Group-scoped service keys are supported — when a key is scoped to a group, results are automatically
limited to that group.
## Available endpoints
| Endpoint | Description |
| ---------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- |
| [Get Consumption](/desktop/accounts/api-reference/get-consumption) (`GET /api/v2alpha/analytics/consumption`) | Query credit or ACU consumption with filtering, grouping, granularity, and pagination |
| [Get Active Users](/desktop/accounts/api-reference/get-active-users) (`GET /api/v2alpha/analytics/active-users`) | Count distinct active users, optionally by day/month or per user |
## Billing strategy
Responses adapt to your team's billing strategy, reported in `metadata.billing_strategy`:
* **`CREDITS`** — rows include `prompt_credits` and `flex_credits`
* **`ACU`** — rows include `billed_acus`
The `message_count` field is always returned regardless of strategy.
## Pagination
List responses are paginated. When more data is available, the response includes a
`pagination.next_page_cursor`; pass it back as the `page_cursor` query parameter to fetch the next
page. Cursors expire after 24 hours.
## Caching
Responses include an `ETag` header. Send it back in the `If-None-Match` header on subsequent requests
to receive a `304 Not Modified` when the data is unchanged.
## Rate limits
These endpoints are **not** intended for real-time usage monitoring. Data is hourly-aggregated and
the rate limit is low (10 requests per hour per team). Use them for periodic reporting and bulk
export, not live dashboards or per-request tracking.
v2 endpoints are rate-limited to **10 requests per hour per team**. Exceeding the limit returns
`429 Too Many Requests` with a `Retry-After` header.
Paginating an earlier query (following a `next_page_cursor`) does **not** count against the rate
limit — only the initial query for each report does. The low limit reflects that these endpoints are
for periodic reporting, not real-time monitoring.
# API Reference
Source: https://docs.devinenterprise.com/desktop/accounts/api-reference/api-introduction
Enterprise API for querying Devin Desktop usage data and managing configurations with service key authentication.
## Overview
The Devin Desktop API enables enterprise customers to programmatically access detailed usage analytics and manage usage configurations for their teams.
The API is available for Enterprise plans only
## Base URL
All API requests should be made to:
```
https://server.codeium.com/api/v1/
```
## Authentication
The Devin Desktop API uses service keys for authentication. Service keys must be included in the request body of all API calls.
### Creating a Service Key
1. Navigate to your [team settings page](https://windsurf.com/team/settings)
2. Go to the "Service Keys" section
3. Create a new service key with appropriate permissions
4. Copy the generated service key for use in API requests
### Required Permissions
Different API endpoints require different permissions. Refer to the individual endpoint documentation for the specific permission required:
| Endpoint | Required Permission |
| ------------------------------------------------------------------------------------------------------------ | ------------------- |
| [Custom Analytics](/desktop/accounts/api-reference/custom-analytics) (`/Analytics`) | Analytics Read |
| [User Page Analytics](/desktop/accounts/api-reference/user-page-analytics) (`/UserPageAnalytics`) | Teams Read-Only |
| [Cascade Analytics](/desktop/accounts/api-reference/cascade-analytics) (`/CascadeAnalytics`) | Teams Read-Only |
| [Set Usage Configuration](/desktop/accounts/api-reference/usage-config) (`/UsageConfig`) | Billing Write |
| [Get Usage Configuration](/desktop/accounts/api-reference/get-usage-config) (`/GetUsageConfig`) | Billing Read |
| [Get Team Credit Balance](/desktop/accounts/api-reference/get-team-credit-balance) (`/GetTeamCreditBalance`) | Billing Read |
### Using Service Keys
Include your service key in the request body of all API calls:
```json theme={null}
{
"service_key": "your_service_key_here",
// ... other parameters
}
```
Keep your service keys secure and never expose them in client-side code or public repositories
## Rate Limits
API requests are subject to rate limiting to ensure service stability. If you exceed the rate limit, you'll receive a `429 Too Many Requests` response.
## Support
For API support and questions, please contact [Devin Desktop Support](https://windsurf.com/support).
# Get Cascade Analytics
Source: https://docs.devinenterprise.com/desktop/accounts/api-reference/cascade-analytics
POST https://server.codeium.com/api/v1/CascadeAnalytics
Query Cascade-specific usage metrics including lines suggested/accepted, model usage, credit consumption, and tool usage statistics.
## Overview
Retrieve Cascade-specific analytics data including lines suggested/accepted, model usage, credit consumption, and tool usage statistics.
## Request
Your service key with "Teams Read-only" permissions
Filter results to users in a specific group. Cannot be used with `emails` parameter.
Start time in RFC 3339 format (e.g., `2023-01-01T00:00:00Z`)
End time in RFC 3339 format (e.g., `2023-12-31T23:59:59Z`)
Array of email addresses to filter results. Cannot be used with `group_name` parameter.
Filter by IDE type. Available options:
* `"editor"` - Devin Desktop Editor
* `"jetbrains"` - JetBrains Plugin
* `"cli"` - Devin CLI
If omitted, returns data for all IDEs.
When filtering by Devin CLI (`"cli"`), the `mode` field of `cascade_runs` is not populated. `cascade_lines` and `cascade_tool_usage` cover Devin CLI and Devin Local activity, but only include data recorded after those agents began reporting it.
Array of data source queries to execute. Each object should contain one of the supported data sources.
## Data Sources
### cascade\_lines
Query for daily Cascade lines suggested and accepted.
```json theme={null}
{
"cascade_lines": {}
}
```
**Response Fields:**
* `day` - Date in RFC 3339 format
* `linesSuggested` - Number of lines suggested
* `linesAccepted` - Number of lines accepted
### cascade\_runs
Query for model usage, credit consumption, and mode data.
```json theme={null}
{
"cascade_runs": {}
}
```
**Response Fields:**
* `day` - Date in RFC 3339 format
* `model` - Model name used
* `mode` - Cascade mode (see modes below)
* `messagesSent` - Number of messages sent
* `cascadeId` - Unique conversation ID
* `promptsUsed` - Credits consumed (in cents)
**Cascade Modes:**
* `CONVERSATIONAL_PLANNER_MODE_DEFAULT` - Write mode
* `CONVERSATIONAL_PLANNER_MODE_READ_ONLY` - Read mode
* `CONVERSATIONAL_PLANNER_MODE_NO_TOOL` - Legacy mode
* `UNKNOWN` - Unknown mode
### cascade\_tool\_usage
Query for tool usage statistics (aggregate counts).
```json theme={null}
{
"cascade_tool_usage": {}
}
```
**Response Fields:**
* `tool` - Tool identifier (see tool mappings below)
* `count` - Number of times tool was used
## Tool Usage Mappings
| Tool Identifier | Display Name |
| ------------------- | ----------------- |
| `CODE_ACTION` | Code Edit |
| `VIEW_FILE` | View File |
| `RUN_COMMAND` | Run Command |
| `FIND` | Find tool |
| `GREP_SEARCH` | Grep Search |
| `VIEW_FILE_OUTLINE` | View File Outline |
| `MQUERY` | Riptide |
| `WORKFLOWS_USED` | Workflows Used |
| `LIST_DIRECTORY` | List Directory |
| `MCP_TOOL` | MCP Tool |
| `PROPOSE_CODE` | Propose Code |
| `SEARCH_WEB` | Search Web |
| `MEMORY` | Memory |
| `PROXY_WEB_SERVER` | Browser Preview |
| `DEPLOY_WEB_APP` | Deploy Web App |
## Example Request
```bash theme={null}
curl -X POST --header "Content-Type: application/json" \
--data '{
"service_key": "your_service_key_here",
"group_name": "engineering_team",
"start_timestamp": "2025-01-01T00:00:00Z",
"end_timestamp": "2025-01-02T00:00:00Z",
"emails": ["user1@cognition.ai", "user2@cognition.ai"],
"ide_types": ["editor"],
"query_requests": [
{
"cascade_lines": {}
},
{
"cascade_runs": {}
},
{
"cascade_tool_usage": {}
}
]
}' \
https://server.codeium.com/api/v1/CascadeAnalytics
```
## Response
Array of query results, one for each query request
Array of daily line statistics
Date in RFC 3339 format
Number of lines suggested on this day
Number of lines accepted on this day
Array of model usage statistics
Date in RFC 3339 format
Model name used for the run
Cascade mode identifier
Number of messages sent
Unique conversation identifier
Credits consumed in cents (e.g., "100" = 1 credit)
Array of tool usage statistics
Tool identifier
Number of times tool was used
### Example Response
```json theme={null}
{
"queryResults": [
{
"cascadeLines": {
"cascadeLines": [
{
"day": "2025-05-01T00:00:00Z",
"linesSuggested": "206",
"linesAccepted": "157"
},
{
"day": "2025-05-02T00:00:00Z",
"linesSuggested": "16"
}
]
}
},
{
"cascadeRuns": {
"cascadeRuns": [
{
"day": "2025-05-01T00:00:00Z",
"model": "Claude 3.7 Sonnet (Thinking)",
"mode": "CONVERSATIONAL_PLANNER_MODE_DEFAULT",
"messagesSent": "1",
"cascadeId": "0d35c1f7-0a85-41d0-ac96-a04cd2d64444"
}
]
}
},
{
"cascadeToolUsage": {
"cascadeToolUsage": [
{
"tool": "CODE_ACTION",
"count": "15"
},
{
"tool": "LIST_DIRECTORY",
"count": "20"
}
]
}
}
]
}
```
## Notes
* The API returns raw data which may contain "UNKNOWN" values
* For metrics analysis, aggregate by specific fields of interest (e.g., sum `promptsUsed` for usage patterns)
* Mode and prompt data may be split across multiple entries
* Credit consumption (`promptsUsed`) is returned in cents (100 = 1 credit)
# Custom Analytics Query
Source: https://docs.devinenterprise.com/desktop/accounts/api-reference/custom-analytics
POST https://server.codeium.com/api/v1/Analytics
Flexible analytics querying with custom selections, filters, and aggregations for autocomplete, chat, command, and PCW data.
## Overview
The Custom Analytics API provides flexible querying capabilities for autocomplete, chat, and command data with customizable selections, filters, aggregations, and orderings.
## Request
Your service key with "Analytics Read" permissions
Filter results to users in a specific group (optional)
Array of query request objects defining the data to retrieve
Data source to query. Options:
* `QUERY_DATA_SOURCE_USER_DATA` - Autocomplete data
* `QUERY_DATA_SOURCE_CHAT_DATA` - Chat data
* `QUERY_DATA_SOURCE_COMMAND_DATA` - Command data
* `QUERY_DATA_SOURCE_PCW_DATA` - Percent Code Written data
Array of field selections to retrieve
Field name to select (see Available Fields section)
Alias for the field. If not specified, defaults to `{aggregation_function}_{field_name}` (lowercase)
Aggregation function to apply:
* `QUERY_AGGREGATION_UNSPECIFIED` (default)
* `QUERY_AGGREGATION_COUNT`
* `QUERY_AGGREGATION_SUM`
* `QUERY_AGGREGATION_AVG`
* `QUERY_AGGREGATION_MAX`
* `QUERY_AGGREGATION_MIN`
Array of filters to apply
Field name to filter on
Filter operation:
* `QUERY_FILTER_EQUAL`
* `QUERY_FILTER_NOT_EQUAL`
* `QUERY_FILTER_GREATER_THAN`
* `QUERY_FILTER_LESS_THAN`
* `QUERY_FILTER_GE` (greater than or equal)
* `QUERY_FILTER_LE` (less than or equal)
Value to compare against
Array of aggregations to group by
Field name to group by
Alias for the aggregation field
## Query Request Structure
Each query request object contains:
* **data\_source** (required): Data source to query
* **selections** (required): Array of field selections to retrieve
* **filters** (optional): Array of filters to apply
* **aggregations** (optional): Array of aggregations to group by
## Selections
Selections define which fields to retrieve and how to aggregate them.
* **field** (required): Field name to select
* **name** (optional): Alias for the field
* **aggregation\_function** (optional): Aggregation function to apply
### Selection Example
```json theme={null}
{
"field": "num_acceptances",
"name": "total_acceptances",
"aggregation_function": "QUERY_AGGREGATION_SUM"
}
```
## Filters
Filters narrow down data to elements meeting specific criteria.
* **name** (required): Field name to filter on
* **filter** (required): Filter operation
* **value** (required): Value to compare against
### Filter Example
```json theme={null}
{
"name": "language",
"filter": "QUERY_FILTER_EQUAL",
"value": "PYTHON"
}
```
## Aggregations
Aggregations group data by specified criteria.
* **field** (required): Field name to group by
* **name** (required): Alias for the aggregation field
### Aggregation Example
```json theme={null}
{
"field": "ide",
"name": "ide_type"
}
```
## Available Fields
### User Data
All User Data is aggregated per user, per hour.
| Field Name | Description | Valid Aggregations |
| -------------------------- | --------------------------------------------------------- | ------------------ |
| `api_key` | Hash of user API key | UNSPECIFIED, COUNT |
| `date` | UTC date of autocompletion | UNSPECIFIED, COUNT |
| `date UTC-x` | Date with timezone offset (e.g., "date UTC-8" for PST) | UNSPECIFIED, COUNT |
| `hour` | UTC hour of autocompletion | UNSPECIFIED, COUNT |
| `language` | Programming language | UNSPECIFIED, COUNT |
| `ide` | IDE being used | UNSPECIFIED, COUNT |
| `version` | Extension/plugin (language-server) version, e.g. `1.48.x` | UNSPECIFIED, COUNT |
| `num_acceptances` | Number of autocomplete acceptances | SUM, MAX, MIN, AVG |
| `num_lines_accepted` | Lines of code accepted | SUM, MAX, MIN, AVG |
| `num_bytes_accepted` | Bytes accepted | SUM, MAX, MIN, AVG |
| `distinct_users` | Distinct users | UNSPECIFIED, COUNT |
| `distinct_developer_days` | Distinct (user, day) tuples | UNSPECIFIED, COUNT |
| `distinct_developer_hours` | Distinct (user, hour) tuples | UNSPECIFIED, COUNT |
### Chat Data
Chat data is separate from Cascade data and represents usage of our legacy, non-agentic plugins
All Chat Data represents chat model responses, not user questions.
| Field Name | Description | Valid Aggregations |
| ------------------------- | --------------------------------------------------------- | ------------------ |
| `api_key` | Hash of user API key | UNSPECIFIED, COUNT |
| `model_id` | Chat model ID | UNSPECIFIED, COUNT |
| `date` | UTC date of chat response | UNSPECIFIED, COUNT |
| `date UTC-x` | Date with timezone offset | UNSPECIFIED, COUNT |
| `ide` | IDE being used | UNSPECIFIED, COUNT |
| `version` | Extension/plugin (language-server) version, e.g. `1.48.x` | UNSPECIFIED, COUNT |
| `latest_intent_type` | Chat intent type (see Intent Types below) | UNSPECIFIED, COUNT |
| `num_chats_received` | Number of chat messages received | SUM, MAX, MIN, AVG |
| `chat_accepted` | Whether chat was accepted (thumbs up) | SUM, COUNT |
| `chat_inserted_at_cursor` | Whether "Insert" button was clicked | SUM, COUNT |
| `chat_applied` | Whether "Apply Diff" button was clicked | SUM, COUNT |
| `chat_loc_used` | Lines of code used from chat | SUM, MAX, MIN, AVG |
#### Chat Intent Types
* `CHAT_INTENT_GENERIC` - Regular chat
* `CHAT_INTENT_FUNCTION_EXPLAIN` - Function explanation code lens
* `CHAT_INTENT_FUNCTION_DOCSTRING` - Function docstring code lens
* `CHAT_INTENT_FUNCTION_REFACTOR` - Function refactor code lens
* `CHAT_INTENT_CODE_BLOCK_EXPLAIN` - Code block explanation code lens
* `CHAT_INTENT_CODE_BLOCK_REFACTOR` - Code block refactor code lens
* `CHAT_INTENT_PROBLEM_EXPLAIN` - Problem explanation code lens
* `CHAT_INTENT_FUNCTION_UNIT_TESTS` - Function unit tests code lens
### Command Data
Command Data includes all commands, including declined ones. Use the `accepted` field to filter for accepted commands only.
| Field Name | Description | Valid Aggregations |
| ----------------- | --------------------------------------------------------- | ------------------ |
| `api_key` | Hash of user API key | UNSPECIFIED, COUNT |
| `date` | UTC date of command | UNSPECIFIED, COUNT |
| `timestamp` | UTC timestamp of command | UNSPECIFIED, COUNT |
| `language` | Programming language | UNSPECIFIED, COUNT |
| `ide` | IDE being used | UNSPECIFIED, COUNT |
| `version` | Extension/plugin (language-server) version, e.g. `1.48.x` | UNSPECIFIED, COUNT |
| `command_source` | Command trigger source (see Command Sources below) | UNSPECIFIED, COUNT |
| `provider_source` | Generation or edit mode | UNSPECIFIED, COUNT |
| `lines_added` | Lines of code added | SUM, MAX, MIN, AVG |
| `lines_removed` | Lines of code removed | SUM, MAX, MIN, AVG |
| `bytes_added` | Bytes added | SUM, MAX, MIN, AVG |
| `bytes_removed` | Bytes removed | SUM, MAX, MIN, AVG |
| `selection_lines` | Lines selected (zero for generations) | SUM, MAX, MIN, AVG |
| `selection_bytes` | Bytes selected (zero for generations) | SUM, MAX, MIN, AVG |
| `accepted` | Whether command was accepted | SUM, COUNT |
#### Command Sources
* `COMMAND_REQUEST_SOURCE_LINE_HINT_CODE_LENS`
* `COMMAND_REQUEST_SOURCE_DEFAULT` - Typical command usage
* `COMMAND_REQUEST_SOURCE_RIGHT_CLICK_REFACTOR`
* `COMMAND_REQUEST_SOURCE_FUNCTION_CODE_LENS`
* `COMMAND_REQUEST_SOURCE_FOLLOWUP`
* `COMMAND_REQUEST_SOURCE_CLASS_CODE_LENS`
* `COMMAND_REQUEST_SOURCE_PLAN`
* `COMMAND_REQUEST_SOURCE_SELECTION_HINT_CODE_LENS`
#### Provider Sources
* `PROVIDER_SOURCE_COMMAND_GENERATE` - Generation mode
* `PROVIDER_SOURCE_COMMAND_EDIT` - Edit mode
### PCW Data
Percent Code Written data with separate tracking for autocomplete and command contributions.
| Field Name | Description | Valid Aggregations |
| ------------------------------- | ------------------------------------------------------------- | ------------------ |
| `percent_code_written` | Calculated as codeium\_bytes / (codeium\_bytes + user\_bytes) | UNSPECIFIED |
| `codeium_bytes` | Total Codeium-generated bytes | UNSPECIFIED |
| `user_bytes` | Total user-written bytes | UNSPECIFIED |
| `total_bytes` | codeium\_bytes + user\_bytes | UNSPECIFIED |
| `codeium_bytes_by_autocomplete` | Codeium bytes from autocomplete | UNSPECIFIED |
| `codeium_bytes_by_command` | Codeium bytes from command | UNSPECIFIED |
#### PCW Filters
| Field Name | Description | Examples |
| ---------- | --------------------------------------------------------- | ----------------- |
| `language` | Programming language | KOTLIN, GO, JAVA |
| `ide` | IDE being used | jetbrains, vscode |
| `version` | Extension/plugin (language-server) version, e.g. `1.48.x` | 1.28.0, 130.0 |
For date filtering in PCW queries, use `start_timestamp` and `end_timestamp` in the main request body.
## Example Requests
### User Data Example
```bash theme={null}
curl -X POST --header "Content-Type: application/json" \
--data '{
"service_key": "your_service_key_here",
"query_requests": [
{
"data_source": "QUERY_DATA_SOURCE_USER_DATA",
"selections": [
{
"field": "num_acceptances",
"name": "total_acceptances",
"aggregation_function": "QUERY_AGGREGATION_SUM"
},
{
"field": "num_lines_accepted",
"name": "total_lines",
"aggregation_function": "QUERY_AGGREGATION_SUM"
}
],
"filters": [
{
"name": "date",
"filter": "QUERY_FILTER_GE",
"value": "2024-01-01"
},
{
"name": "date",
"filter": "QUERY_FILTER_LE",
"value": "2024-02-01"
}
]
}
]
}' \
https://server.codeium.com/api/v1/Analytics
```
### Chat Data Example
```bash theme={null}
curl -X POST --header "Content-Type: application/json" \
--data '{
"service_key": "your_service_key_here",
"query_requests": [
{
"data_source": "QUERY_DATA_SOURCE_CHAT_DATA",
"selections": [
{
"field": "chat_loc_used",
"name": "lines_used",
"aggregation_function": "QUERY_AGGREGATION_SUM"
}
],
"filters": [
{
"name": "latest_intent_type",
"filter": "QUERY_FILTER_EQUAL",
"value": "CHAT_INTENT_FUNCTION_DOCSTRING"
}
],
"aggregations": [
{
"field": "ide",
"name": "ide_type"
}
]
}
]
}' \
https://server.codeium.com/api/v1/Analytics
```
### Command Data Example
```bash theme={null}
curl -X POST --header "Content-Type: application/json" \
--data '{
"service_key": "your_service_key_here",
"query_requests": [
{
"data_source": "QUERY_DATA_SOURCE_COMMAND_DATA",
"selections": [
{
"field": "lines_added",
"name": "total_lines_added",
"aggregation_function": "QUERY_AGGREGATION_SUM"
},
{
"field": "lines_removed",
"name": "total_lines_removed",
"aggregation_function": "QUERY_AGGREGATION_SUM"
}
],
"filters": [
{
"name": "provider_source",
"filter": "QUERY_FILTER_EQUAL",
"value": "PROVIDER_SOURCE_COMMAND_EDIT"
},
{
"name": "accepted",
"filter": "QUERY_FILTER_EQUAL",
"value": "true"
}
],
"aggregations": [
{
"field": "language",
"name": "programming_language"
}
]
}
]
}' \
https://server.codeium.com/api/v1/Analytics
```
### PCW Data Example
```bash theme={null}
curl -X POST --header "Content-Type: application/json" \
--data '{
"service_key": "your_service_key_here",
"start_timestamp": "2024-01-01T00:00:00Z",
"end_timestamp": "2024-12-22T00:00:00Z",
"query_requests": [
{
"data_source": "QUERY_DATA_SOURCE_PCW_DATA",
"selections": [
{
"field": "percent_code_written",
"name": "pcw"
},
{
"field": "codeium_bytes",
"name": "ai_bytes"
},
{
"field": "total_bytes",
"name": "total"
},
{
"field": "codeium_bytes_by_autocomplete",
"name": "autocomplete_bytes"
},
{
"field": "codeium_bytes_by_command",
"name": "command_bytes"
}
],
"filters": [
{
"filter": "QUERY_FILTER_EQUAL",
"name": "language",
"value": "GO"
}
]
}
]
}' \
https://server.codeium.com/api/v1/Analytics
```
## Response
Array of query results, one for each query request
Array of result items
Object containing the selected fields and their values
### Example Responses
#### User Data Response
```json theme={null}
{
"queryResults": [
{
"responseItems": [
{
"item": {
"total_acceptances": "125",
"total_lines": "863"
}
}
]
}
]
}
```
#### Chat Data Response
```json theme={null}
{
"queryResults": [
{
"responseItems": [
{
"item": {
"lines_used": "74",
"ide_type": "jetbrains"
}
},
{
"item": {
"lines_used": "41",
"ide_type": "vscode"
}
}
]
}
]
}
```
#### Command Data Response
```json theme={null}
{
"queryResults": [
{
"responseItems": [
{
"item": {
"programming_language": "PYTHON",
"total_lines_added": "21",
"total_lines_removed": "5"
}
},
{
"item": {
"programming_language": "GO",
"total_lines_added": "31",
"total_lines_removed": "27"
}
}
]
}
]
}
```
#### PCW Data Response
```json theme={null}
{
"queryResults": [
{
"responseItems": [
{
"item": {
"ai_bytes": "6018",
"autocomplete_bytes": "4593",
"command_bytes": "1425",
"pcw": "0.61",
"total": "9900"
}
}
]
}
]
}
```
## Important Notes
* PCW (Percent Code Written) has high variance within single days or users - aggregate over weeks for better insights
* All selection fields must either have aggregation functions or none should (cannot mix)
* Fields with "distinct\_\*" pattern cannot be used in aggregations
* Field aliases must be unique across all selections and aggregations
* If no aggregation function is specified, it defaults to UNSPECIFIED
# Get Consumption
Source: https://docs.devinenterprise.com/desktop/accounts/api-reference/get-consumption
desktop/accounts/api-reference/analytics-v2-openapi.yaml GET /api/v2alpha/analytics/consumption
Query credit or ACU consumption analytics with flexible filtering, grouping, and pagination.
This is a **v2 endpoint** that uses Bearer token authentication and query parameters, unlike the v1 Analytics API which uses service keys in the request body. See [Authentication](#authentication) below.
This endpoint is **not** intended for real-time usage monitoring. Data is hourly-aggregated and the
rate limit is low (10 requests per hour per team). Use it for periodic reporting and bulk export.
## Authentication
This endpoint uses **Bearer token** authentication. Include your service key in the `Authorization` header:
```
Authorization: Bearer
```
The service key must have the **Analytics Read** permission. Create one in your [team settings](https://windsurf.com/team/settings) under "Service Keys".
## Billing Strategy
The response shape depends on your team's billing strategy:
| Strategy | Populated fields | Description |
| --------- | -------------------------------- | ----------------------------------- |
| `CREDITS` | `prompt_credits`, `flex_credits` | Standard Enterprise SaaS teams |
| `ACU` | `billed_acus` | Teams billed by Agent Compute Units |
The `message_count` field (inside `consumption`) is always populated regardless of billing strategy.
## Grouping and Granularity
Use `granularity` and `group_by` to control the shape of returned data:
* **No granularity or grouping** — returns a single aggregated row for the entire date range
* **`granularity=daily`** — each row includes a `timestamp` in `YYYY-MM-DD` format
* **`granularity=monthly`** — each row includes a `timestamp` in `YYYY-MM` format
* **`group_by=user`** — each row includes a `user_id` and `user_email`
* **`group_by=user,model_uid`** — each row includes `user_id`, `user_email`, and `model_uid`
* **`group_by=ide`** — each row includes an `ide`
* **`group_by=ide,ide_version`** — each row includes `ide` and `ide_version` (grouping by `ide_version` requires `ide` to also be included)
* **`group_by=os`** — each row includes an `os`, such as `darwin` (macOS), `windows`, or `linux`
## Pagination
Results are paginated with a default page size of 1,000 rows (max 10,000). When more results are available,
the response includes a `next_page_cursor` in the `pagination` object. Pass it as the `page_cursor` query
parameter to fetch the next page.
Page cursors expire after 24 hours. A follow-up page request does not count as a new query against your rate limit.
## Caching
Responses include an `ETag` header. To avoid redundant data transfer, include the `If-None-Match` header
with the previous `ETag` value — the server will return `304 Not Modified` if the data has not changed.
## Rate Limits
This endpoint is rate-limited to **10 requests per hour** per team. If you exceed this limit, the
server returns `429 Too Many Requests` with a `Retry-After` header.
Paginating an earlier query (following a `next_page_cursor`) does **not** count against this limit —
only the initial query for each report does. The low limit reflects that this endpoint is for
periodic reporting, not real-time usage monitoring.
# Get User Page Analytics
Source: https://docs.devinenterprise.com/desktop/accounts/api-reference/user-page-analytics
POST https://server.codeium.com/api/v1/UserPageAnalytics
Retrieve user activity statistics including names, emails, last activity times, active days, and prompt credits used from the teams page.
## Overview
Get user activity statistics that appear on the teams page, including user names, emails, last activity times, active days, and prompt credits used.
## Request
Your service key with "Teams Read-only" permissions
Filter results to users in a specific group (optional)
Start time in RFC 3339 format (e.g., `2023-01-01T00:00:00Z`). **Only affects the `activeDays` calculation.** If not provided, defaults to 1 year ago.
End time in RFC 3339 format (e.g., `2023-12-31T23:59:59Z`). **Only affects the `activeDays` calculation.** If not provided, defaults to the current time.
### Example Request
```bash theme={null}
curl -X POST --header "Content-Type: application/json" \
--data '{
"service_key": "your_service_key_here",
"group_name": "engineering_team",
"start_timestamp": "2024-01-01T00:00:00Z",
"end_timestamp": "2024-12-31T23:59:59Z"
}' \
https://server.codeium.com/api/v1/UserPageAnalytics
```
## Response
Array of user statistics objects
User's display name
User's email address
Timestamp of user's last activity in RFC 3339 format
Hashed version of the user's API key
The number of days the user was active within the queried time range (defined by `start_timestamp` and `end_timestamp`). A day is counted as active if the user had any autocomplete acceptances, Cascade usage, or command usage on that day.
Indicates whether Devin Desktop access has been disabled for the user by an admin. This field is only present if access has been explicitly disabled, and will always be set to true in that case.
The user's role within the team (e.g., admin, member)
Timestamp of when the user signed up, in RFC 3339 format
The most recent timestamp the Tab/Autocomplete modality was used, in RFC 3339 format
The most recent timestamp the Cascade modality was used, in RFC 3339 format
The most recent timestamp the Command modality was used, in RFC 3339 format
The total number of prompt credits used by this user during the **current billing cycle**, returned in **cents** (1 credit = 100 cents). To get the actual credit usage, divide this value by 100. This value is **not** affected by the `start_timestamp` or `end_timestamp` request parameters. The billing cycle window is indicated by the top-level `billingCycleStart` and `billingCycleEnd` fields.
The user's team membership status. Possible values: `USER_TEAM_STATUS_UNSPECIFIED`, `USER_TEAM_STATUS_PENDING`, `USER_TEAM_STATUS_APPROVED`, `USER_TEAM_STATUS_REJECTED`. Note that the API returns all users regardless of team status, while the Manage Members UI only shows approved users.
The start of the current billing cycle in RFC 3339 format. The `promptCreditsUsed` values in `userTableStats` correspond to usage within this billing cycle.
The end of the current billing cycle in RFC 3339 format. The `promptCreditsUsed` values in `userTableStats` correspond to usage within this billing cycle.
### Example Response
```json theme={null}
{
"userTableStats": [
{
"name": "Alice",
"email": "alice@cognition.ai",
"lastUpdateTime": "2024-10-10T22:56:10.771591Z",
"apiKey": "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa",
"activeDays": 178,
"role": "admin",
"signupTime": "2024-01-15T08:30:00Z",
"lastAutocompleteUsageTime": "2024-10-10T22:56:10Z",
"lastChatUsageTime": "2024-10-10T20:30:00Z",
"promptCreditsUsed": 12500,
"teamStatus": "USER_TEAM_STATUS_APPROVED"
},
{
"name": "Bob",
"email": "bob@cognition.ai",
"lastUpdateTime": "2024-10-10T18:11:23.980237Z",
"apiKey": "bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbbbb",
"activeDays": 210,
"role": "member",
"signupTime": "2024-02-01T10:00:00Z",
"lastAutocompleteUsageTime": "2024-10-10T18:11:23Z",
"lastChatUsageTime": "2024-10-09T14:22:00Z",
"lastCommandUsageTime": "2024-10-08T09:15:00Z",
"promptCreditsUsed": 8300,
"teamStatus": "USER_TEAM_STATUS_APPROVED"
}
],
"billingCycleStart": "2024-10-01T00:00:00Z",
"billingCycleEnd": "2024-11-01T00:00:00Z"
}
```
## Error Responses
Error message describing what went wrong
Common error scenarios:
* Invalid service key or insufficient permissions
* Invalid timestamp format
* Group not found
* Rate limit exceeded
# Quota-Based Usage
Source: https://docs.devinenterprise.com/desktop/accounts/quota
Learn how Devin Desktop's quota-based usage system works, including daily and weekly allowances, extra usage, and migration details for existing subscribers.
In March 2026, Devin Desktop replaced the credit-based system with a **quota-based usage system**. Instead of buying and spending credits, your plan now includes a daily and weekly usage allowance that refreshes automatically.
## How quotas work
Your plan includes a usage allowance measured as a **daily and weekly budget**.
Your budget is based on how many tokens the model uses for each request. The cost per token varies by model, and free models don't count against your quota at all.
Short requests, with only a few files in context, will use fewer tokens than longer requests with larger codebases.
This system is different from the previous credit-based system, but better reflects the underlying costs of using different models.
### When you hit your limit
* **Free**: Wait until your next daily or weekly reset.
* **Pro, Teams, or Max**: Purchase extra usage to keep working without interruption.
Your quota resets on a daily and weekly basis, based on the calendar date.
Your daily quota is more than 1/7 of your weekly quota, enabling users who work on weekends to fully use their weekly allowance.
### Checking your remaining quota
You can check your remaining quota and when it resets from the usage meter in Devin Desktop, or on your [plan page](https://windsurf.com/subscription/manage-plan).
### Making your quota last longer
* Be precise with your instructions and remove unnecessary context.
* Switch to models that don't count against your quota, like SWE-1.7 (free through August 8, 2026) or SWE-1.6, for routine tasks.
* Avoid unnecessarily long sessions when a quick prompt will do.
* Try to choose a single frontier model for your tasks—requests to the same model leverage caching and reduce overall token usage.
## Extra usage
Extra usage lets you continue using Devin Desktop **after hitting your included quota**.
Usage is billed at API list prices for the model you're using, based on how many tokens the model uses for each request.
Priority and speed configurations (e.g., SWE-1.5 Fast, fast Opus variants) will increase the cost.
Quota limits **never** limit your extra usage, just the built-in allowance from your plan.
## Migration for existing subscribers
Your price is grandfathered in at \$15/mo indefinitely. You are moved to the new quota system, but you keep your current price.
Your per-seat price is grandfathered in at \$30/mo per Developer seat indefinitely.
Every existing paid subscriber gets a free extra week added to their current plan. This means your next renewal date was extended by 7 days.
Use that week to try the new quota system and see how it maps to your actual workflow.
Your annual subscription renewal date will be extended by 7 days for the trial week. If you decide to cancel, you can request a refund for all remaining months on your subscription.
Enterprise Self-Serve customers continue under their existing billing agreements. These changes do not affect you at this point.
Enterprise customers continue under their existing billing agreements. Reach out to your account team with any questions.
## Add-on credits & extra usage conversion
Quotas replace the built-in prompt credits that were part of the previous credit-based system.
All add-on credits are converted into a dollar amount of extra usage at the rate you paid for them.
Since prompt credits were sold for \$0.04/credit, for every 250 add-on credits you had remaining on your account you received \$10 in extra usage balance.
Yes. After conversion, you can request a refund of your unspent extra usage balance at any time through [support](https://windsurf.com/support). You'll receive the equivalent dollar amount back.
No. Credits are converted at exactly the rate you paid. You can either use that balance as extra usage going forward, or request a refund.
## Other questions
If you previously purchased SSO as an add-on, you keep SSO access under your grandfathered plan. New Teams plans do not include SSO — it is now an Enterprise-only feature.
## Token pricing example
To show how token pricing works in practice, let us walk through an example conversation with the agent using Claude Opus 4.6:
| Role | Message | Tokens | Note |
| :------------ | :------------------------------------------------------------------------------------------- | :------- | :------------------------------------------------------------------------------------- |
| User | Refactor @my\_function | 20k | Input (cache write). Note: Incl. full shared timeline, editor context & system prompt. |
| Devin Desktop | Let me first analyze my\_function to come up with a plan to refactor it. | 1k | Output tokens. |
| `tool_call` | Analyze my\_function | 23k | Input (cache read) + Input (cache write). |
| Devin Desktop | Here is a plan to refactor my\_function \[...] do you want me to continue with implementing? | 2k | Output tokens. |
| User | Yes, continue. | 46k | Input (cache read) + Input (cache write). |
| `tool_call` | Edit foo.py | 50k | Input (cache read) + Output tokens. |
| `tool_call` | Add bar.py | 56k | Input (cache read) + Output tokens. |
| Devin Desktop | I am done refactoring my\_function. Here is a summary of my changes: \[...] | 2k | Output tokens. |
| **Total** | | **200k** | |
The actual per-token cost can be calculated based on the model [pricing table](/desktop/models) page.
# Role Based Access & Management
Source: https://docs.devinenterprise.com/desktop/accounts/rbac-role-management
Configure RBAC permissions, create custom roles, and manage user access for Devin Desktop Enterprise plans.
Devin Desktop's Role-Based Access Control system provides granular, role-based access to enterprise resources, enabling administrators to assign permissions and roles dynamically for secure and efficient access management.
Role-based access features are available for Enterprise plans only.
## Role Based Access Controls
Devin Desktop's role-based access system allows enterprise organizations to implement fine-grained access controls across all team resources. The system enables:
* **Granular Permission Management**: Control access to specific features and data based on user roles
* **Dynamic Role Assignment**: Administrators can assign and modify roles for individual users or user groups
* **Secure Resource Access**: Ensure users only have access to the resources they need for their responsibilities
* **Audit and Compliance**: Track user permissions and access patterns for security and compliance requirements
The role-based access system integrates seamlessly with Devin Desktop's existing authentication mechanisms, including SSO and SCIM, to provide a comprehensive security framework for enterprise deployments.
## Role Management
We are continually working to improve role management features and functionality.
Roles can be created and managed in the Devin Desktop admin console via the Settings tab. For Devin Desktop's SaaS offering, access the Settings tab at:
Manage roles, permissions, and team settings from the admin console.
### Creating a New Role
Go to [windsurf.com/team/settings](https://windsurf.com/team/settings) and locate the Role Management section.
Click the **"Create Role"** button to start creating a new role.
Enter a descriptive name for the role and select the appropriate permissions from the checkbox list.
Review your selections and save the new role. It will now be available for assignment to users.
## Role Permissions
Devin Desktop provides two default roles out of the box:
* **Admin Role**: Includes all available permissions for complete system access
* **User Role**: Includes no permissions by default, providing a minimal access baseline
### Modifying Role Permissions
To modify permissions for custom roles, click the permissions dropdown next to the role name in the Role Management section. This allows you to add or remove specific permissions as needed.
### Available Permissions
Devin Desktop offers a comprehensive set of permissions organized into the following categories:
#### Attribution
* **Attribution Read**: Read access to the attribution page
#### Analytics
* **Analytics Read**: Read access to the analytics page
#### Teams
* **Teams Read-Only**: Read-only access to the teams page
* **Teams Update**: Allows updating user roles in the teams page
* **Teams Delete**: Allows deleting users from the teams page
* **Teams Invite**: Allows inviting users to the teams page
#### Indexing
* **Indexing Read**: Read access to the indexing page
* **Indexing Create**: Create access to the indexing page
* **Indexing Update**: Allows updating indexed repos
* **Indexing Delete**: Allows deleting indexes
* **Indexing Management**: Allows index database management and pruning
#### SSO
* **SSO Read**: Read access to the SSO page
* **SSO Write**: Write access to the SSO page
#### Service Key
* **Service Key Read**: Read access to the service keys page
* **Service Key Create**: Allows creating service keys
* **Service Key Update**: Allows updating service keys
* **Service Key Delete**: Allows deleting service keys
#### Billing
* **Billing Read**: Read access to the billing page
* **Billing Write**: Write access to the billing page
#### Role Management
* **Role Read**: Read access to the roles tab in settings
* **Role Create**: Able to create new roles
* **Role Update**: Allows updating roles
* **Role Delete**: Allows deleting roles
#### Team Settings
* **Team Settings Read**: Allows read access to team settings
* **Team Settings Update**: Allows updating team settings
### Disable Devin Desktop Access Feature
For administrators who need access to team analytics and audit/attribution logging but do not wish to consume a license, Devin Desktop provides a "disable Devin Desktop access" feature.
To access this feature:
Go to the **"Manage Team"** tab in your team settings.
Find the user you want to modify and click **"Edit"** next to their name.
In the user edit dialog, you can disable their Devin Desktop access while maintaining their administrative permissions for analytics and logging.
## User Groups
User Groups are available for Enterprise organizations with SCIM integration enabled.
For enterprise organizations, Devin Desktop offers the ability to split users into multiple user groups via SCIM (System for Cross-domain Identity Management) integration. This feature enables:
* **Organizational Structure**: Mirror your company's organizational structure within Devin Desktop
* **Group-Based Analytics**: View analytics and usage data filtered by specific user groups
* **Delegated Administration**: Assign group administrators who can manage specific user groups
* **Scalable Management**: Efficiently manage large numbers of users through group-based operations
User groups are automatically synchronized with your identity provider through SCIM, ensuring that organizational changes are reflected in Devin Desktop's access controls.
## User Management
Devin Desktop's role-based access functionality allows administrators to assign roles to individual users or user groups, providing flexible access control management.
### Assigning Roles to Users
User role management is performed in the Devin Desktop admin console at [windsurf.com/team/settings](https://windsurf.com/team/settings).
Go to the team settings page and locate the user management section.
Scroll through the user list or use the search functionality to find the user you want to modify. Users can be sorted alphabetically by name, email, sign-up time, or last login.
Click **"Edit"** next to the user's name to open the user management dialog.
In the pop-out window, select the appropriate role from the dropdown menu.
Confirm your selection and save the changes. The new role will be applied immediately.
### Administrative Hierarchy
Devin Desktop's role-based access system recognizes different levels of administrative access:
* **Super Admin**: Users with the admin role in the "all users" group have complete system access and can modify any role or permission
* **Group Admins**: Administrators of specific user groups can only make role and permission changes within their assigned groups
This hierarchical structure ensures that administrative responsibilities can be delegated appropriately while maintaining security boundaries.
### User Sorting and Management
The user management interface provides several sorting options to help administrators efficiently manage large teams:
* **Alphabetical by Name**: Sort users by their display names
* **Email Address**: Sort users by their email addresses
* **Sign-up Time**: View users in order of when they joined the team
* **Last Login**: Sort by most recent activity to identify active users
These sorting options make it easier to find specific users and understand team engagement patterns.
# Getting started with Teams and Enterprise
Source: https://docs.devinenterprise.com/desktop/accounts/teams-getting-started
Set up Devin Desktop Teams and Enterprise plans with team management, SSO, analytics, user groups, and priority support for your organization.
Devin Desktop scales from solo projects to large-scale enterprise codebases. Our Teams and Enterprise plans unlock collaboration features such as team management, Single Sign-On (SSO), advanced analytics, and priority support.
If your organisation requires extra security or compliance, please [contact our sales team](https://windsurf.com/contact/enterprise).
## Setup
Visit [windsurf.com/pricing](https://windsurf.com/pricing) and select the `Teams` or `Enterprise` tier.
Enter the number of users you want to include in the subscription.
Devin Desktop makes managing your team easy from one dashboard.
To add members to your team, first navigate to the [invite page](https://windsurf.com/team/members).
Simply click on the "invite" button and then either add via email or share a unique invite link.
Configurable settings for your team.
Select and approve models, MCP servers, SSO configurations, service keys, role management, and more.
Set up SSO, SCIM, Duo, or PingID for your team.
For Teams plans, SSO must be purchased as an add-on [here](https://windsurf.com/team/members), which also comes with access controls and subteam analytics.
## Manage Team
You must be a team admin to make changes to the team.
To add or remove members from your team, navigate to the [Manage team page](https://windsurf.com/team/members).
From here, you can invite and view your team, add SSO, update the number of seats in your team, or even cancel or switch your plan.
## User Groups
This feature is only available in Enterprise plans and for teams with SSO enabled.
Devin Desktop now supports creating user groups. For each group you can now view analytics per group. You can also configure group administrators who can view analytics for the specific groups they manage.
### Existing Subscription
Already subscribed on Pro and want to upgrade? Head to your [Plan Management](https://windsurf.com/subscription/plan-management), click `Switch Plan`, and select the appropriate Teams or Enterprise plan.
# Plans and Usage
Source: https://docs.devinenterprise.com/desktop/accounts/usage
Understand Devin Desktop pricing plans, usage tracking, and how to upgrade from Free to Pro, Teams, or Enterprise.
Windsurf is available as **Free**, **Pro**, **Max**, **Teams**, and **Enterprise** plans. Plans vary in the models available, usage limits, and additional features like centralized billing, admin dashboards, SSO, and RBAC.
For a full comparison of what's included in each plan, see [windsurf.com/pricing](https://windsurf.com/pricing).
Windsurf introduced new usage-based plans for self-serve customers in March 2026. You can learn more about these plans [here](/desktop/accounts/quota).
## Upgrading to a paid plan
To learn more about paid features or to upgrade to a paid plan, [click here](https://windsurf.com/subscription/manage-plan). Paid plans include Pro/Max for individuals, Teams for organizations, and Enterprise for larger companies.
We accept all major credit cards, Apple Pay, Cash App Pay, Google Pay, Link, WeChat Pay, and Alipay. If you have a payment method not listed, please reach out to us at [support](https://windsurf.com/support). You may need to disable your VPN to view the relevant payment methods for your region.
## Trials
From time to time, Windsurf offers free trials of paid plans to eligible customers. Trials are a promotional offer, not an entitlement, and are only made available to a subset of customers.
Trials are generally not offered to:
* Customers who have previously used Windsurf, Devin, or Codeium (including under a different account or plan).
* Customers who our systems predict are unlikely to purchase a Pro subscription.
* Customers flagged for suspected abuse, fraud, or other violations of our [terms of service](https://windsurf.com/terms-of-service).
Eligibility is determined automatically by our systems and is not subject to appeal. If a trial is not offered to you at checkout, you are not eligible for one, and Windsurf support will not be able to apply one retroactively. You are welcome to subscribe directly to a paid plan, and you can request a refund before using the subscription if you change your mind.
## Viewing your usage
There are a few ways to view your usage.
View the settings panel by clicking on "Windsurf Settings" on the status bar, followed by selecting the "Plan Info" tab.
You can also view it on your plan page at [windsurf.com/subscription/manage-plan](https://windsurf.com/subscription/manage-plan) after you're authenticated.
## Viewing or updating your payment & billing information
You can now update your payment method, billing details, tax ID, and view past invoices directly from your Windsurf account. Follow the steps below to make changes securely via Stripe.
Visit [windsurf.com/subscription/manage-plan](https://windsurf.com/subscription/manage-plan) and log into your account if prompted.
You can view and download your previous invoices and receipts.
* On the billing page, select the Update Payment button.
* A secure Stripe pop-up will appear. This will redirect you to your customer portal on Stripe. From the Stripe portal, you can:
* Add or change your payment method
* Update your billing and shipping information (name or company name, tax identification, and address)
* Once you've made the updates, save your changes and close the window.
To change the email associated with your account, update your email in your
[Windsurf profile settings](https://windsurf.com/settings). If you need
further assistance, please [open a support
ticket](https://windsurf.com/support).
## Canceling your paid plan
As a paid individual user, you can cancel your plan at any time by browsing to the [windsurf.com/subscription/manage-plan](https://windsurf.com/subscription/manage-plan) page.
Upon canceling, you'll still have access to your plan's features until the end of the current billing period. After that, you'll be downgraded to the Free plan.
If you change your mind before the end of the billing period, you can renew your plan by visiting the billing page.
For Teams plans, only the admin can cancel the plan, delete the team and remove users.
### Agent Compute Units (ACUs)
Enterprise plans are billed in **Agent Compute Units (ACUs)**. An ACU reflects the amount of agent effort required to complete a given task. ACU consumption scales with the inference used and the model selected.
The exact number of ACUs included depends on your contract. Contact your account team or [sales](https://windsurf.com/contact/sales) for details on pricing and allocation.
### How ACUs work
For local agents — Cascade, Devin CLI, Devin Local, and similar products — ACUs are based on inference. The tokens consumed by the selected model are converted into ACUs at the per-token rates listed on the [models page](/desktop/models). For cloud agents, code review, and other platform capabilities, ACUs reflect a mix of tokens, compute, VMs, and other infrastructure costs. See the [Devin billing page](https://docs.devin.ai/admin/billing) for more details on how ACUs are metered across different products.
### Viewing your usage
There are a few ways to view your usage.
View the settings panel by clicking on "Windsurf Settings" on the status bar, followed by selecting the "Plan Info" tab.
You can also view it on your plan page at [windsurf.com/subscription/manage-plan](https://windsurf.com/subscription/manage-plan) after you're authenticated.
This only applies to credit-based enterprise customers. Newer enterprise plans are billed in ACUs — see the **Enterprise (ACUs)** tab.
### Enterprise Credits
Enterprise plans on the legacy billing model use a **credit-based usage system**. Prompt credits are consumed whenever a message is sent to a Devin Desktop agent with a premium model. Every model has its own credit multiplier, with the default message costing 1 credit. You can view all available models and their associated costs on the [models page](/desktop/models).
### How credits work
When you send a message to a Devin Desktop agent with a premium model, 1 prompt credit is consumed. It doesn't matter how many actions the agent takes to fulfill your request—whether it searches your codebase, analyzes files, or makes edits—you only pay for the initial prompt.
Prompt credits are issued monthly according to your plan. They do not roll over to the next month—whether or not you've used them, your credit balance will reset at the start of each new billing cycle. Once your monthly prompt credits run out, if you have add-on credits, those will automatically be used instead. Unlike prompt credits, add-on credits do not expire and can be carried over until they're fully used.
If a message is unsuccessful, prompt credits will not be consumed. For example, if the agent attempts to write to a file but that file has unsaved changes, the operation will fail and it will not consume a credit.
### Purchasing additional credits
Additional credits are purchased within and treated as a pool amongst all members of the team at a rate of \$120 for 1000 pooled credits. Please contact your Teams admin to purchase more credits if you're on a team plan.
Add-on credits require an active subscription to be used. If your subscription expires, any remaining add-on credits cannot be used until you resubscribe. Your add-on credits will not be removed and will remain available once you resubscribe.
### Automatic Credit Refills
Under your plan settings page on the Windsurf website, you can specify a maximum amount of credits and other refill settings. The system will automatically "top-up" your credits as you start running low (below 15 credits).
Automatic Credit Refills are purchased in configurable increments (multiples of \$120 for Teams/Enterprise) and subject to maximum monthly budget caps (\$160 by default). This ensures you won't lose access to the agent during critical work.
### Seat-Based Credit Allocation
On Enterprise plans, prompt credits are allocated on a per-seat basis. Each seat receives a fixed number of credits at the start of each billing cycle. These credits are tied to the seat itself, not the specific user occupying it.
If a team member leaves mid-billing cycle and a new member joins to fill that seat, the new member inherits the seat's existing credit usage. For example, if your plan has 50 seats and all are in use, and one member departs after using 300 of their 1000 credits, the person who takes that seat will start with only 700 credits remaining for the rest of the billing period.
When this happens, you may see a notice on your usage page indicating that you joined a seat that was previously used during the current billing period. This is expected behavior and does not indicate any error with your account. Your credits will fully reset to the plan's standard allocation at the start of the next billing cycle.
If you are an admin managing a team where members frequently rotate, keep in
mind that adding new members to recently vacated seats may result in those
members starting with fewer credits for the remainder of the billing period.
All seats reset to their full credit allocation at the beginning of each new
billing cycle.
### Viewing your usage
There are a few ways to view your usage.
View the settings panel by clicking on "Windsurf Settings" on the status bar, followed by selecting the "Plan Info" tab.
You can also view it on your plan page at [windsurf.com/subscription/manage-plan](https://windsurf.com/subscription/manage-plan) after you're authenticated.
# Agent Client Protocol
Source: https://docs.devinenterprise.com/desktop/acp
Run third-party agents inside the Devin Desktop Agent Command Center via ACP.
ACP agents are available for Pro, Max, and Teams users. Enterprise admins should contact their account team about enabling third-party agents.
Devin Desktop includes support for running third-party agents inside the [Agent Command Center](/desktop/agent-command-center). We use the [Agent Client Protocol (ACP)](https://agentclientprotocol.com/) to do so.
ACP is an open protocol that standardizes communication between code editors and coding agents — similar to how the Language Server Protocol (LSP) standardized language server integration. Any agent that implements ACP can be plugged into Devin Desktop, and Devin Desktop can talk to any ACP-compatible agent.
When using an external ACP agent, all agent operations are delegated to the agent. Devin Desktop's privacy policy and legal terms do not apply, and billing is directly between you and the third-party agent provider.
## Example agents
Any agent that speaks ACP can be run inside Devin Desktop. Some popular ACP-compatible agents you can plug in include:
* [Codex CLI](https://github.com/openai/codex) — OpenAI's coding agent
* [Claude Agent](https://www.anthropic.com/claude-code) — Anthropic's coding agent
* [OpenCode](https://opencode.ai) — open source coding agent
* [Junie](https://www.jetbrains.com/junie/) — JetBrains' coding agent
* [Gemini CLI](https://github.com/google-gemini/gemini-cli) — Google's coding agent
In addition to third-party agents like these, you can use ACP to integrate a [custom agent](/desktop/acp-custom) with Devin Desktop.
## Enabling custom agents
Once an agent is added to your [local](#local-registry-config) or [team](#team-registry-config) registry, it can be enabled from `Devin Settings`:
1. Open the Command Palette with `Cmd+Shift+P` (macOS) or `Ctrl+Shift+P` (Windows/Linux)
2. Open `Devin User Settings`
3. Click the "Agents" tab
4. Toggle on the ACP agents you want to use
5. Restart Devin Desktop
Once enabled, the agent appears in the agent selector in the bottom right corner of Devin Desktop when starting *new* conversations, alongside built-in agents like [Cascade](/desktop/cascade/cascade) and [Devin Local](/desktop/devin-local).
Every agent — Cascade, Devin Local, and ACP agents alike — is unavailable while a workspace is open in [Restricted Mode](/desktop/devin-local#restricted-mode), where hooks also neither load nor run.
## Browser previews
ACP agents can open a [browser preview](/desktop/previews) of your app, the same workflow Cascade has: the agent proxies your local dev server, the preview opens in the built-in browser pane next to the agent, and the elements and console output you capture land in that agent's message box as pending context.
## Local registry config
Individual users can configure their own ACP agents by editing a local registry file:
* **Devin Desktop:** `~/.windsurf/acp/registry.json`
* **Devin Desktop Next:** `~/.windsurf-next/acp/registry.json`
You can also open the file directly from the Command Palette by running `Open Local ACP Registry Config`.
The file follows the [ACP registry spec](https://agentclientprotocol.com/get-started/registry).
### Sample config for Devin Local
If you would like to test out [Devin Local](/desktop/devin-local) on your machine without enabling it for your entire team, you can configure a local registry pointing to the Devin CLI.
This assumes the `devin` CLI is already installed and available on your `PATH`. Devin Desktop launches it with `devin acp`.
```json theme={null}
{
"version": "1.0.0",
"agents": [
{
"id": "devin-cli",
"name": "Devin Local",
"version": "1.0.0",
"description": "Devin AI coding agent via Devin CLI",
"authors": [
"Cognition AI"
],
"license": "proprietary",
"distribution": {
"binary": {
"darwin-aarch64": {
"archive": "",
"cmd": "devin",
"args": [
"acp"
]
},
"darwin-x86_64": {
"archive": "",
"cmd": "devin",
"args": [
"acp"
]
},
"linux-aarch64": {
"archive": "",
"cmd": "devin",
"args": [
"acp"
]
},
"linux-x86_64": {
"archive": "",
"cmd": "devin",
"args": [
"acp"
]
},
"windows-aarch64": {
"archive": "",
"cmd": "devin",
"args": [
"acp"
]
},
"windows-x86_64": {
"archive": "",
"cmd": "devin",
"args": [
"acp"
]
}
}
}
}
],
"extensions": []
}
```
## Team registry configuration
Team administrators can push out a custom ACP config to their team via the "ACP Registry Config" setting in [Devin Settings](https://windsurf.com/team/settings).
This lets you maintain a static registry of approved ACP agents that all members of your team can use, without each user having to configure them individually.
For security reasons, Devin Desktop does not currently download agent distributions directly from the registry. The agent binary is expected to already be installed on the user's machine — the registry config tells Devin Desktop how to launch it. The `distribution.binary..archive` URLs in the sample below are part of the ACP registry schema for compatibility with the wider ecosystem, but Devin Desktop does not fetch them today.
### Sample config for OpenCode
```json theme={null}
{
"version": "1.0.0",
"agents": [
{
"id": "opencode",
"name": "OpenCode",
"version": "1.15.7",
"description": "The open source coding agent",
"repository": "https://github.com/anomalyco/opencode",
"website": "https://opencode.ai",
"authors": [
"Anomaly"
],
"license": "MIT",
"icon": "https://cdn.agentclientprotocol.com/registry/v1/latest/opencode.svg",
"distribution": {
"binary": {
"darwin-aarch64": {
"archive": "https://github.com/anomalyco/opencode/releases/download/v1.15.7/opencode-darwin-arm64.zip",
"cmd": "./opencode",
"args": [
"acp"
]
},
"darwin-x86_64": {
"archive": "https://github.com/anomalyco/opencode/releases/download/v1.15.7/opencode-darwin-x64.zip",
"cmd": "./opencode",
"args": [
"acp"
]
},
"linux-aarch64": {
"archive": "https://github.com/anomalyco/opencode/releases/download/v1.15.7/opencode-linux-arm64.tar.gz",
"cmd": "./opencode",
"args": [
"acp"
]
},
"linux-x86_64": {
"archive": "https://github.com/anomalyco/opencode/releases/download/v1.15.7/opencode-linux-x64.tar.gz",
"cmd": "./opencode",
"args": [
"acp"
]
},
"windows-aarch64": {
"archive": "https://github.com/anomalyco/opencode/releases/download/v1.15.7/opencode-windows-arm64.zip",
"cmd": "./opencode.exe",
"args": [
"acp"
]
},
"windows-x86_64": {
"archive": "https://github.com/anomalyco/opencode/releases/download/v1.15.7/opencode-windows-x64.zip",
"cmd": "./opencode.exe",
"args": [
"acp"
]
}
}
}
}
],
"extensions": []
}
```
## Troubleshooting
### My existing agent setup isn't working
Third-party agents read their own config files for most settings, but authentication is usually handled separately. Specifically, you typically need to:
* Authenticate via a `/login` slash command in the agent.
* Configure environment variables using the "..." button in the Agents tab of Devin User Settings.
* Set environment variables via the `devin.acp.agentEnv.` setting in your `settings.json` file.
# Building a custom ACP agent
Source: https://docs.devinenterprise.com/desktop/acp-custom
Build a custom agent that runs inside Devin Desktop via the Agent Client Protocol.
This page covers what you need to implement to build a custom [ACP](/desktop/acp) agent that works with Devin Desktop.
For the full protocol specification, see [agentclientprotocol.com](https://agentclientprotocol.com/). Official client libraries are available in [Rust](https://agentclientprotocol.com/libraries/rust), [TypeScript](https://agentclientprotocol.com/libraries/typescript), [Python](https://agentclientprotocol.com/libraries/python), [Kotlin](https://agentclientprotocol.com/libraries/kotlin), and [Java](https://agentclientprotocol.com/libraries/java).
## Basics
ACP agents run as local sub-processes that Devin Desktop launches on demand. All communication happens over JSON-RPC on stdio.
### Methods you must implement
At minimum, your agent needs to handle these methods from Devin Desktop:
* [`initialize`](https://agentclientprotocol.com/protocol/initialization) — Negotiate the protocol version, advertise your agent's capabilities, and return agent info (name, version).
* [`session/new`](https://agentclientprotocol.com/protocol/session-setup) — Create a new session for a working directory and return a session ID. Devin Desktop passes the cwd and any configured MCP servers.
* [`session/prompt`](https://agentclientprotocol.com/protocol/prompt-turn) — Receive a user message, drive the prompt turn, and return a `stopReason` when finished.
* [`session/cancel`](https://agentclientprotocol.com/protocol/prompt-turn) — Abort any in-flight work for a session when the user cancels.
### Prompt turn lifecycle
During a `session/prompt` turn, your agent streams updates back to Devin Desktop as JSON-RPC notifications:
* `session/update` with `agent_message_chunk` for streaming assistant text.
* `session/update` with `tool_call` and `tool_call_update` to show tool calls and their status in the Devin Desktop UI.
* `session/request_permission` to ask the user before running a sensitive tool call.
* `session/update` with `plan` if your agent maintains an [agent plan](https://agentclientprotocol.com/protocol/agent-plan).
The turn ends when your agent returns a `session/prompt` response with a `stopReason` (e.g. `end_turn`, `cancelled`, `max_tokens`).
## Testing
To test your agent against Devin Desktop:
1. Add an entry for your agent in your [local registry config](/desktop/acp#local-registry-config), pointing `cmd` at the path of your local agent binary (or a wrapper script).
2. Make changes to your agent and rebuild as needed.
3. Run `Reload ACP Connections` from the Command Palette to pick up the latest version — no need to restart Devin Desktop between iterations.
## Limitations
Devin Desktop does not currently support every part of the ACP spec. The following are the main differences to be aware of when building an agent targeting Devin Desktop:
* **Session modes are not supported.** [Session modes](https://agentclientprotocol.com/protocol/session-modes) are not exposed in the Devin Desktop UI. If your agent needs to let users pick between modes (e.g. plan / build / review), expose them as a [session config option](https://agentclientprotocol.com/protocol/session-config-options) with the `"mode"` category instead.
* **Terminal capabilities are not exposed.** Devin Desktop does not advertise [terminal capabilities](https://agentclientprotocol.com/protocol/terminals), so agents cannot create terminals in the Devin Desktop UI. Agents should run commands in their own subprocess and stream output back via `tool_call` updates.
# Adaptive
Source: https://docs.devinenterprise.com/desktop/adaptive
Adaptive is Cognition's intelligent model router that automatically selects the best AI model for each task.
## Selecting Adaptive
To use Adaptive, open the model picker below the agent input box and select **Adaptive** at the top of the list. Once selected, Adaptive will be used for all subsequent messages in the conversation.
You can switch away from Adaptive to a specific model at any time.
Adaptive is an intelligent model router that automatically selects the best AI model for each task. Instead of manually choosing between dozens of models, Adaptive analyzes your prompt and routes it to the model that will deliver the best result.
## How it works
When you select **Adaptive**, Devin evaluates each request and dynamically chooses the right underlying model. Simple tasks get routed to fast, efficient models. Complex tasks get routed to more capable ones.
This means you get the right level of intelligence for every prompt without overspending on premium models for routine work. Adaptive helps your usage allowance last longer by avoiding unnecessary use of expensive models.
Adaptive is the best default for most users.
## Enterprise availability
For enterprise organizations, Adaptive is disabled by default. An admin must enable the **Adaptive model router** setting from the enterprise settings page before team members can select Adaptive in the model picker.
* **Devin Desktop**: Go to **Settings > Devin Desktop > Models** and toggle **Adaptive model router** on.
* **Windsurf**: Go to **Team Settings > Models** and toggle **Adaptive model router** on.
## Pricing
Adaptive pricing depends on your billing plan.
Adaptive draws down your quota at a **fixed per-token rate**, regardless of which underlying model is selected for a given request.
Currently, the Adaptive model consumes quota and overage at an introductory promotional rate (through July 7, 2026).
| Token type | Cost per 1M tokens |
| :---------------- | :----------------- |
| Input tokens | \$0.50 |
| Output tokens | \$2.00 |
| Cache read tokens | \$0.10 |
These rates also apply to extra usage beyond your included quota.
Because Adaptive routes simpler tasks to lighter models, it typically consumes fewer tokens overall than manually selecting a frontier model for every request. This makes it the most cost-effective option for most users.
For customers on the Cognition platform, Adaptive usage is metered in **ACUs** (Agent Compute Units). ACU consumption scales with the tokens used and the model selected by the router for each request.
For enterprise customers on credit-based billing, Adaptive uses **variable-token credit pricing**. Each request consumes credits based on the actual tokens used and the model that Adaptive selects for that request according to your credit rate.
This means cheaper models cost fewer credits per request, and Adaptive's routing naturally favors cost-efficient choices — so your credit pool lasts longer compared to always selecting a premium model.
## Tips for getting the most out of Adaptive
* **Be specific with your prompts.** Clear, focused instructions help Adaptive route to the right model and reduce unnecessary token usage.
* **Leverage prompt caching.** Staying on the same model across turns in a conversation enables caching, which significantly reduces input token costs. Adaptive takes this into account when routing.
* **Use Adaptive as your default.** For most workflows, Adaptive is the best starting point. Switch to a specific model only when you have a particular reason to — for example, if you need a specific model's reasoning capabilities for a complex task.
# Advanced Configuration
Source: https://docs.devinenterprise.com/desktop/advanced
Advanced Devin Desktop configurations including SSH support, Dev Containers, WSL, extension marketplace settings, diff zones, and gitignore access for Cascade.
All advanced configurations can be found in Devin Settings which can be accessed by the top right dropdown → Devin Settings or Command Palette (Ctrl/⌘+Shift+P) → Open Devin User Settings.
# Enabling Cascade access to .gitignore files
To provide Cascade with access to files that match patterns in your project's .gitignore, go to your Devin Settings and go to "Cascade Gitignore Access". By default, it is turned off. To provide access, turn it on by clicking the toggle.
# Agent diff zones
When an agent edits files, Devin Desktop displays **diff zones** — inline highlighted regions in the editor that show exactly what changed, with accept and reject controls for each hunk. All agents use diff zones by default.
You can turn off diff zones for non-Cascade agents in Devin Settings → User Interface → **Agent Diff Zones**. When disabled, non-Cascade agent edits are applied directly to the file and the toolbar shows a simple dismiss button instead of accept/reject controls.
# SSH Support
The usual SSH support in VSCode is licensed by Microsoft, so we have implemented our own just for Devin Desktop. It does require you to have [OpenSSH](https://www.openssh.com/) installed, but otherwise has minimal dependencies, and should "just work" like you're used to. You can access SSH under `Remote-SSH` in the Command Palette, or via the `Open a Remote Window` button in the bottom left.
This extension has worked great for our internal development, but there are some known caveats and bugs:
* We currently only support SSHing into Linux-based remote hosts.
* The usual Microsoft "Remote - SSH" extension (and the [open-remote-ssh](https://github.com/jeanp413/open-remote-ssh) extension) will not work—please do not install them, as they conflict with our support.
* We don't have all the features of the Microsoft SSH extension right now. We mostly just support the important thing: connecting to a host. If you have feature requests, let us know!
* To access a devcontainer on a remote host after connecting via SSH, use the Command Palette (Ctrl/Cmd+Shift+P) and choose one of the following options:
* SSH agent-forwarding is on by default, and will use Devin Desktop's latest connection to that host. If you're having trouble with it, try reloading the window to refresh the connection.
* On Windows, you'll see some `cmd.exe` windows when it asks for your password. This is expected—we'll get rid of them soon.
* If you have issues, please first make sure that you can ssh into your remote host using regular `ssh` in a terminal. If the problem persists, include the output from the `Output > Remote SSH (Devin)` tab in any bug reports!
# Dev Containers
Devin Desktop supports Development Containers on Mac, Windows, and Linux for both local and remote (via SSH) workflows.
Prerequisites:
* Local: Docker must be installed on your machine and accessible from the Devin Desktop terminal.
* Remote over SSH: Connect to a remote host using Devin Desktop Remote-SSH. Docker must be installed and accessible on the remote host (from the remote shell). Your project should include a `devcontainer.json` or equivalent config.
Available commands (in both local and remote windows):
1. `Dev Containers: Open Folder in Container`
* Open a new workspace using a specified `devcontainer.json`.
2. `Dev Containers: Reopen in Container`
* Reopen the current workspace in a new container defined by your `devcontainer.json`.
3. `Dev Containers: Attach to Running Container`
* Attach to an existing Docker container and connect your current workspace to it. If the container does not follow the [Development Container Specification](https://containers.dev/implementors/spec/), Devin Desktop will attempt best-effort detection of the remote user and environment.
4. `Dev Containers: Reopen Folder Locally`
* When connected to a development container, disconnect and reopen the workspace on the local filesystem.
5. `Dev Containers: Show Devin Desktop Dev Containers Log`
* Open the Dev Containers log output for troubleshooting.
These commands are available from the Command Palette and will also appear when you click the `Open a Remote Window` button in the bottom left (including when you are connected to a remote host via SSH).
Related:
* `Remote Explorer: Focus on Dev Containers (Devin Desktop) View` — quickly open the Dev Containers view.
### Known Limitations
Devin Desktop does not currently execute [Dev Container Specification lifecycle commands](https://containers.dev/implementors/json_reference/#lifecycle-scripts):
* `onCreateCommand`
* `updateContentCommand`
* `postCreateCommand`
* `postStartCommand`
* `postAttachCommand`
This applies to both container-level lifecycle commands (defined in `devcontainer.json`) and feature-level lifecycle commands (defined in `devcontainer-feature.json`). Dotfiles installation is also not performed.
**What does work:**
* Feature `install.sh` scripts (these run at image-build time)
* Feature `mounts` (volumes are attached at container runtime)
* Feature `entrypoint` field (executes on every container start)
* All other image-build-time operations (Dockerfile, docker-compose, features)
### Workaround: Using a Feature Entrypoint for Runtime Setup
If you are authoring a Dev Container feature that needs to run setup at container start (for example, to configure files from a mounted volume), use the feature's `entrypoint` field instead of a lifecycle command. The entrypoint executes on every container start after mounts are attached, and is fully self-contained — consumers of your feature do not need to modify their `devcontainer.json`.
In your `devcontainer-feature.json`, declare the entrypoint:
```json theme={null}
{
"name": "my-feature",
"id": "my-feature",
"version": "1.0.0",
"mounts": [
{ "type": "volume", "source": "my-volume", "target": "/data/my-dir" }
],
"entrypoint": "/usr/local/share/my-feature/entrypoint.sh"
}
```
In your `install.sh` (runs at image-build time), write the entrypoint script:
```bash theme={null}
#!/usr/bin/env bash
set -e
mkdir -p /usr/local/share/my-feature
cat > /usr/local/share/my-feature/entrypoint.sh << 'EOF'
#!/bin/sh
# Mount-dependent setup (runs on every container start, volume is mounted)
if [ -d /data/my-dir ]; then
mkdir -p /etc/myapp
cp /data/my-dir/config /etc/myapp/config
fi
exit 0
EOF
chmod +x /usr/local/share/my-feature/entrypoint.sh
```
The entrypoint script should perform its setup and exit normally. Do not end it with `exec "$@"` — the CLI's own entrypoint wrapper handles passing control to the container command. Keep the script lightweight since it runs synchronously before the IDE connects.
# WSL (Beta)
As of version 1.1.0, Devin Desktop has beta support for Windows Subsystem for Linux. You must already have WSL set up and configured on your Windows machine.
You can access WSL by clicking on the `Open a Remote Window` button in the bottom left, or under `Remote-WSL` in the Command Palette.
# Extension Marketplace
You can change the marketplace you use to download extensions from. To do this, go to `Devin Settings` and modify the Marketplace URL settings under the `General` section.
## Devin Desktop Plugins
Search "Devin Pyright" or paste in `@id:codeium.windsurfPyright` in the extensions search bar.
# Agent Command Center
Source: https://docs.devinenterprise.com/desktop/agent-command-center
Manage all of your Devin Desktop agents — local and cloud — from a single Kanban-style view inside Devin Desktop.
The Agent Command Center is a new surface inside Devin Desktop 2.0 for managing every agent you have running, both local and cloud, in one place.
It is organized as a Kanban board grouped by status, so you can see at a glance what each agent is working on, what is blocked, and what is ready for review.
## Opening the Agent Command Center
You can switch to the Agent Command Center directly from Devin Desktop without leaving the editor.
## Kanban view
Agents are organized into columns by status so you can quickly tell what is in flight, what needs your attention, and what is finished.
The board includes both:
* **Local agents** — Agent sessions running in your editor.
* **Cloud agents** — [Devin](/desktop/devin) sessions running on their own VMs.
## Working in a session
A few things make it faster to drive a session from the agent window:
* **Add to chat** — select text inside a message transcript and send it to the input with the **Add to chat** button or `Cmd/Ctrl+L`.
* **Duplicate session** — branch off a conversation from the response footer to explore an alternative without losing the original (Devin Local).
* **Rules in the @-mention menu** — pull a manual-trigger [rule](/cli/extensibility/rules) into the conversation (Devin Local).
* **Editable queued messages** — a message queued while the agent is working can be edited before it sends (Devin Local).
Sessions are locked while their agent is running: they appear greyed out and are read-only until the agent finishes. If you are signed out, session tabs show a sign-in prompt rather than an error.
## Agent sidebar
The sidebar lists every session in the workspace and can be shaped to fit how you work:
* Filter, sort, and group sessions per workspace, with grouped spaces keeping a sticky header.
* Right-click a session for its context menu, or double-click it to rename it.
## Notifications
Devin Desktop sends a single native OS notification when an agent session finishes or needs your input. One setting covers every agent — Cascade, [Devin Local](/desktop/devin-local), and [ACP agents](/desktop/acp) — so you get one notification per session rather than one per surface.
The setting id is `devin.agentNotifications`.
## Working with the editor
The Agent Command Center does not replace the editor. It is integrated with the existing Devin Desktop editor features so you can always jump back into a session and make last-mile edits manually. You can always go back to the Devin Desktop you know and love.
## Organizing work with Spaces
Work in the Agent Command Center is organized into [Spaces](/desktop/spaces). A Space groups all of the agent sessions, PRs, files, and context for a specific task or project into a single view.
Group agent sessions, PRs, files, and context for a project into a single view.
# AI Commit Messages
Source: https://docs.devinenterprise.com/desktop/ai-commit-message
Generate meaningful git commit messages automatically with AI by analyzing your code changes with a single click in Devin Desktop.
Generate git commit messages with a single click. This feature analyzes your code changes and creates meaningful commit messages that describe what you've done.
Available with no limits to all paid users!
# How It Works
When you're ready to commit changes:
1. Stage your files in the Git panel
2. Click the sparkle (✨) icon next to the commit message field
3. Review the generated message and edit if needed
4. Complete your commit
The AI analyzes your recent code changes and creates a meaningful commit message that describes what you've done.
# Best Practices
For better results:
* Apply general best practices for commit scope: group together small, meaningful units of changes
* Review the message before committing
# Limitations
* Large or complex commits may result in more generic messages
* Specialized terminology might not always be captured perfectly
* Generated messages are suggestions and may need editing
# Privacy
Your code and commit messages remain private. We don't store your code changes or use them for training our models.
# Autocomplete Overview
Source: https://docs.devinenterprise.com/desktop/autocomplete/overview
AI-powered code autocomplete with single-line and multi-line suggestions, keyboard shortcuts, and customizable speed settings.
**Devin Desktop Autocomplete** is powered by our own models, trained in-house from scratch to optimize for speed and accuracy.
Our autocomplete makes in-line and multi-line suggestions based on the context of your code.
Suggestions appear in grey text as you type. You can press `esc` to cancel a suggestion.
Suggestions will also disappear if you continue typing or navigating without accepting them.
## Keyboard Shortcuts
### General Shortcuts
Here are the general shortcuts that apply for macOS.
Replace `⌘` with `Ctrl` and `⌥` with `Alt` to get the corresponding shortcuts on Windows/Linux.
* **Accept suggestion**: `⇥`
* **Cancel suggestion**: `esc`
* **Accept suggestion word-by-word**: `⌘+→` (VS Code), `⌥+⇧+\` (JetBrains)
* **Next/previous suggestion**: `⌥+]`/`⌥+[`
* **Trigger suggestion**: `⌥+\`
### JetBrains Shortcuts - 2.2.2 (stable) and 2.3.5 (pre-release) and later
* **Accept suggestion**: `⇥`
* **Accept next word**: `⌥→`
* **Accept current line**: `⌘→`
* **Trigger suggestion**: `⌥\`
* **Accept suggestion**: `Tab`
* **Accept next word**: `Ctrl+Right Arrow`
* **Accept current line**: `End`
* **Trigger suggestion**: `Alt+\`
You can customize these keyboard shortcuts by
* Hover over any completion text and select "Custom" from the dropdown.
* Navigate to Settings > Keymap > Main Menu > Code > Code Completion.
## Autocomplete Speeds
You can set the speed of the Autocomplete in your settings.
Fast Autocomplete is currently only available to our Pro, Teams, and Enterprise Users.
# Autocomplete Tips
Source: https://docs.devinenterprise.com/desktop/autocomplete/tips
Tips for getting the most out of Devin Desktop Autocomplete including inline comments, Fill In The Middle (FIM), and snooze functionality.
## Inline Comments
You can instruct autocomplete with the use of comments in your code.
Devin Desktop will read these comments and suggest the code to bring the comment to life.
This method can get you good mileage, but if you're finding value in writing natural-language instructions and having the AI execute them,
consider using [Devin Desktop Command](/desktop/command/plugins-overview).
## Fill In The Middle (FIM)
Devin Desktop's Autocomplete can Fill In The Middle (FIM).
Read more about in-line FIM on our blog [here](https://windsurf.com/blog/inline-fim-code-suggestions).
## Snooze
Click the Devin Desktop widget in the status bar towards the bottom right of your editor to see the option to switch Autocomplete off,
either temporarily or until you reenable it.
# Prompt Engineering
Source: https://docs.devinenterprise.com/desktop/best-practices/prompt-engineering
Best practices for crafting effective prompts to get high-quality code from Devin Desktop, including clear objectives, context, and constraints.
If you're reading this, you're probably someone that already understands some of the use cases and limitations of LLMs. The better prompt and context that you provide to the model, the better the outcome will be.
Similarly with Devin Desktop, there are best practices for crafting more effective prompts to get the most out of the tool, and get the best quality code possible to help you accelerate your workflows.
For more complex tasks that may require you to [@-Mention](/desktop/chat/overview#mentions) specific code blocks, use [Chat](/desktop/chat/overview) instead of [Command](/desktop/command/plugins-overview).
## Components of a high quality prompt
* ***Clear objective or outcome***
* What are you asking the model to produce?
* Are you asking the model for a plan? For new code? Is it a refactor?
* ***All relevant context to perform the task(s)***
* Have you properly used @-Mentions to ensure that the proper context is included?
* Is there any context that is customer specific that may be unclear to Devin Desktop?
* ***Necessary constraints***
* Are there any specific frameworks, libraries, or languages that must be utilized?
* Are there any space or time complexity constraints?
* Are there any security considerations?
## Examples
***Example #1:***
* **Bad**: Write unit tests for all test cases for an Order Book object.
* **Good**: Using `@class:unit-testing-module` write unit tests for `@func:src-order-book-add` testing for exceptions thrown when above or below stop loss
***Example #2***:
* **Bad**: Refactor rawDataTransform.
* **Good**: Refactor `@func:rawDataTransform` by turning the while loop into a for loop and using the same data structure output as `@func:otherDataTransformer`
***Example #3***:
* **Bad**: Create a new Button for the Contact Form.
* **Good**: Create a new Button component for the `@class:ContactForm` using the style guide in `@repo:frontend-components` that says “Continue”
# Common Use Cases
Source: https://docs.devinenterprise.com/desktop/best-practices/use-cases
Common use cases for Devin Desktop including code generation, unit test generation, code documentation, API integration, and code refactoring.
Devin Desktop serves a variety of use cases at a high level. However, we see certain use cases to be more common than others, especially among our enterprise customers within their production codebases.
## Code generation
**Guidance:** Devin Desktop should work well for this use case. Devin Desktop features including single-line suggestions, multi-line suggestions, and fill-in-the-middle (FIM) completions.
**Best Practices:** Ensuring usage of Next Completion (`⌥ + ]`), Context Pinning, @ Mentions, and Custom Context will provide best results.
**Guidance:** Devin Desktop should work well for this use case. Devin Desktop features including single-line suggestions, multi-line suggestions, and fill-in-the-middle (FIM) completions.
**Best Practices:** Ensuring usage of Next Completion (`⌥ + ]`), Context Pinning, @ Mentions, and Custom Context will provide best results.
**Guidance:** Devin Desktop should work well for this use case. Devin Desktop features including single-line suggestions, multi-line suggestions, and fill-in-the-middle (FIM) completions.
**Best Practices:** Ensuring usage of Next Completion (`⌥ + ]`), Context Pinning, @ Mentions, and Custom Context will provide best results.
## Unit Test generation
**Guidance:** Basic usage of Devin Desktop for generating unit tests should reliably generate 60-70% of unit tests. Edge case coverage will only be as good as the user prompting the model is.
**Best Practices:** Use @ Mentions. Prompt Engineering best practices. Examples include:
Write unit test for `@function-name` that tests all edge cases for X and for Y (e.g. email domain).
Use `@testing-utility-class` to write a unit test for `@function-name`.
**Guidance:** Good for low-hanging fruit use cases. For very specific API specs or in-house libraries, Devin Desktop will not know the intricacies well enough to ensure the quality of generated sample data.
**Best Practices:** Be very specific about the interface you expect. Think about the complexity of the task (and if a single-shot LLM call will be sufficient to address).
## Internal Code Commentary
**Guidance:** Devin Desktop should work well for this use case. Use Devin Desktop Command or Devin Desktop Chat to generate in-line comments and code descriptions.
**Best Practices:** Use @ Mentions and use Code Lenses as much as possible to ensure the scope of the LLM call is correct.
**Guidance:** Generally the Refactor button / Devin Desktop Command would be the best ways to prompt for improvements. Devin Desktop Chat is the best place to ask for explanations or clarifications. This is a little vague but Devin Desktop should be good at doing both.
Devin Desktop Chat is the best place to ask for explanations or clarifications.
This is a little vague but Devin Desktop should be good at doing both.
**Best Practices**: Use the dropdown prompts (aka Devin Desktop's Refactor button) - we have custom prompts that are better engineered to deliver the answer you'd more likely expect.
**Guidance**: The best way to do this would be to create the header file, open chat, @ mention the function in the cpp file, and ask it to write the header function. Then do this iteratively for each in the cpp file. This is the best way to ensure no hallucinations along the way.
**Best Practices**: Generally avoid trying to write a whole header file with one LLM call. Breaking down the granularity of the work makes the quality of the generated code significantly higher.
## API Documentation and Integration
**Guidance**: This is similar to test coverage where parts of the API spec that are common across many libraries Devin Desktop would be able to accurately decorate. However, things that are built special for your in-house use case Devin Desktop might struggle to do at the quality that you expect.
**Best Practices**: Similar to test coverage, as much as possible, walk Devin Desktop's model through the best way to think about what the API is doing and it will be able to decorate better.
**Guidance**: Devin Desktop's context length for a single LLM call is 16,000 tokens. Thus, depending on the scope of your search, Devin Desktop's repo-wide search capability may not be sufficient. Repo-wide, multi-step, multi-edit tasks will be supported in upcoming Devin Desktop products.
This is fundamentally a multi-step problem that single-shot LLM calls (i.e. current functionality of all AI code assistants) are not well equipped to address. Additionally, accuracy of result must be much higher than other use cases as integrations are especially fragile.
**Best Practices**: Devin Desktop is not well-equipped to solve this problem today. If you'd like to test the extent of Devin Desktop's existing functionality, build out a step-by-step plan and prompt Devin Desktop individually with each step and high level of details to guide the AI.
## Code Refactoring
**Guidance**: Ensure proper scoping using Devin Desktop Code Lenses or @ Mentions to make sure all of the necessary context is passed to the LLM.
Context lengths for a single LLM call are finite. Thus, depending on the scope of your refactor, this finite context length may be an issue (and for that matter, any single-shot LLM paradigm). Repo-wide, multi-step, multi-edit tasks are now supported by the agent in [Devin Desktop](/desktop/getstarted/overview).
**Best Practices**: Try to break down the prompt as much as possible. The simpler and shorter the command for refactoring the better.
**Guidance**: Ensure proper scoping using Devin Desktop Code Lenses or @ Mentions to make sure all of the necessary context is passed to the LLM.
Devin Desktop's context length for a single LLM call is 16,000 tokens. Thus, depending on the scope of your refactor, Devin Desktop's context length may be an issue (and for that matter, any single-shot LLM paradigm). Repo-wide, multi-step, multi-edit tasks will be supported in upcoming Devin Desktop products.
**Best Practices**: Try to break down the prompt as much as possible. The simpler and shorter the command for refactoring the better.
# AGENTS.md
Source: https://docs.devinenterprise.com/desktop/cascade/agents-md
Create AGENTS.md files to provide directory-scoped instructions to Cascade. Instructions automatically apply based on file location in your project.
`AGENTS.md` files provide a simple way to give Cascade context-aware instructions that automatically apply based on where the file is located in your project. This is particularly useful for providing directory-specific coding guidelines, architectural decisions, or project conventions.
## How It Works
When you create an `AGENTS.md` file (or `agents.md`), Devin Desktop automatically discovers it and feeds it into the same [Rules](/desktop/cascade/memories#rules) engine that powers `.devin/rules/` (and the legacy `.windsurf/rules/`) — just with the activation mode inferred from the file's location instead of frontmatter:
* **Root directory**: Treated as an **always-on** rule — the full content is included in Cascade's system prompt on every message.
* **Subdirectories**: Treated as a **glob** rule with an auto-generated pattern of `/**` — the content is applied only when Cascade reads or edits files inside that directory.
This location-based scoping makes `AGENTS.md` ideal for providing targeted guidance without cluttering a single global configuration file.
The [Devin Local agent](/desktop/devin-local) reads `AGENTS.md` through the Devin CLI [rules system](/cli/extensibility/rules).
## Creating an AGENTS.md File
Simply create a file named `AGENTS.md` or `agents.md` in the desired directory. The file uses plain markdown with no special frontmatter required.
### Example Structure
```
my-project/
├── AGENTS.md # Global instructions for the entire project
├── frontend/
│ ├── AGENTS.md # Instructions specific to frontend code
│ └── src/
│ └── components/
│ └── AGENTS.md # Instructions specific to components
├── backend/
│ └── AGENTS.md # Instructions specific to backend code
└── docs/
└── AGENTS.md # Instructions for documentation
```
### Example Content
Here's an example `AGENTS.md` file for a React components directory:
```markdown theme={null}
# Component Guidelines
When working with components in this directory:
- Use functional components with hooks
- Follow the naming convention: ComponentName.tsx for components, useHookName.ts for hooks
- Each component should have a corresponding test file: ComponentName.test.tsx
- Use CSS modules for styling: ComponentName.module.css
- Export components as named exports, not default exports
## File Structure
Each component folder should contain:
- The main component file
- A test file
- A styles file (if needed)
- An index.ts for re-exports
```
## Discovery and Scoping
Devin Desktop automatically discovers `AGENTS.md` files throughout your workspace:
* **Workspace scanning**: All `AGENTS.md` files within your workspace and its subdirectories are discovered
* **Git repository support**: For git repositories, Devin Desktop also searches parent directories up to the git root
* **Case insensitive**: Both `AGENTS.md` and `agents.md` are recognized
### Automatic Scoping
The key benefit of `AGENTS.md` is automatic scoping based on file location:
| File Location | Scope |
| ----------------------- | ------------------------------------------------------------ |
| Workspace root | Applies to all files (always on) |
| `/frontend/` | Applies when working with files in `/frontend/**` |
| `/frontend/components/` | Applies when working with files in `/frontend/components/**` |
This means you can have multiple `AGENTS.md` files at different levels, each providing increasingly specific guidance for their respective directories.
## Best Practices
To get the most out of `AGENTS.md` files:
* **Keep instructions focused**: Each `AGENTS.md` should contain instructions relevant to its directory's purpose
* **Use clear formatting**: Bullet points, headers, and code blocks make instructions easier for Cascade to follow
* **Be specific**: Concrete examples and explicit conventions work better than vague guidelines
* **Avoid redundancy**: Don't repeat global instructions in subdirectory files; they inherit from parent directories
### Content Guidelines
```markdown theme={null}
# Good Example
- Use TypeScript strict mode
- All API responses must include error handling
- Follow REST naming conventions for endpoints
# Less Effective Example
- Write good code
- Be careful with errors
- Use best practices
```
## Comparison with Rules
While both `AGENTS.md` and [Rules](/desktop/cascade/memories#rules) provide instructions to Cascade, they serve different purposes:
| Feature | AGENTS.md | Rules |
| -------- | -------------------------------- | -------------------------------------------------------- |
| Location | In project directories | `.devin/rules/` (or legacy `.windsurf/rules/`) or global |
| Scoping | Automatic based on file location | Manual (glob, always on, model decision, manual) |
| Format | Plain markdown | Markdown with frontmatter |
| Best for | Directory-specific conventions | Cross-cutting concerns, complex activation logic |
Use `AGENTS.md` when you want simple, location-based instructions. Use Rules when you need more control over when and how instructions are applied.
# App Deploys
Source: https://docs.devinenterprise.com/desktop/cascade/app-deploys
Deploy web applications directly from Devin Desktop to Netlify with public URLs, automatic builds, and project claiming for Next.js, React, Vue, and Svelte.
App Deploys lets you deploy web applications and sites directly within Devin Desktop through Cascade tool calls. This feature helps you share your work through public URLs, update your deployments, and claim projects for further customization. This feature is in beta and support for additional frameworks, more robust builds, etc. are coming soon.
## Overview
With App Deploys, you can:
* Deploy a website or JS web app to a public domain
* Re-deploy to the same URL after making changes
* Claim the project to your personal account
App Deploys run through Cascade tool calls and are unavailable with the [Devin Local agent](/desktop/devin-local).
App Deploys are intended primarily for preview purposes. For production
applications with sensitive data, we recommend claiming your deployment and
following security best practices.
## Supported Providers
We currently support the following deployment provider:
* **Netlify** - For static sites and web applications
Support for additional providers is planned for future releases.
## How It Works
When you use App Deploys, your code is uploaded to our server and deployed to the provider under our umbrella account. The deployed site will be available at a public URL formatted as:
```
.windsurf.build
```
### Deployment Process
1. Cascade analyzes your project to determine the appropriate framework
2. Your project files are securely uploaded to our server
3. The deployment is created on the provider's platform
4. You receive a public URL and a claim link
### Project Configuration
To facilitate redeployment, we create a `windsurf_deployment.yaml` file at the root of your project. This file contains information for future deployments, such as a project ID and framework.
## Using App Deploys
To deploy your application, simply ask Cascade something like:
```
"Deploy this project to Netlify"
"Update my deployment"
```
Cascade will guide you through the process and help troubleshoot common issues.
## Team Deploys
You will need Team admin privileges to toggle this feature.
Users on Teams and Enterprise plans can connect their Netlify accounts with their Devin Desktop accounts and deploy to their Netlify Team.
This can be toggled in Team Settings, which you can access via the Profile page or by clicking [here](https://windsurf.com/team/settings).
## Security Considerations
Your code will be uploaded to our servers for deployment. Only deploy code
that you're comfortable sharing publicly.
We take several precautions to ensure security:
* File size limits and validation
* Rate limiting based on your account tier
* Secure handling of project files
For added privacy, visit [clear-cookies.windsurf.build](https://clear-cookies.windsurf.build) to check for and clear any cookies set by sites under `windsurf.build`. If any cookies show up, they shouldn't be there, and clearing them helps prevent cross-site cookie issues and keeps your experience clean.
Devin Desktop sites are built by humans and AI, and while we encourage the AI to make best practice decisions, it's smart to stay cautious. Devin Desktop isn't responsible for issues caused by sites deployed by our users.
## Claiming Your Deployment
After deploying, you'll receive a claim URL. By following this link, you can claim the project on your personal provider account, giving you:
* Full control over the deployment
* Access to provider-specific features
* Ability to modify the domain name
* Direct access to logs and build information
Unclaimed deployments may be deleted after a certain period. We recommend
claiming important projects promptly.
## Rate Limits
To prevent abuse, we apply these tier-based rate limits:
| Plan | Deployments per day | Max unclaimed sites |
| ---- | ------------------- | ------------------- |
| Free | 1 | 1 |
| Pro | 10 | 5 |
## Supported Frameworks
App Deploys works with most popular JavaScript frameworks, including:
* Next.js
* React
* Vue
* Svelte
* Static HTML/CSS/JS sites
## Troubleshooting
### Failed Deployment Build
If your deployment fails:
1. Check the build logs provided by Cascade
2. Ensure your project can build locally (run `npm run build` to test)
3. Verify that your project follows the framework's recommended structure
4. View the documentation for how to deploy [your framework to Netlify via `netlify.toml`](https://docs.netlify.com/configure-builds/file-based-configuration/)
5. Consider claiming the project to access detailed logs on the provider's dashboard
We cannot provide direct support for framework-specific build errors. If your
deployment fails due to code issues, debug locally or claim the project to
work with the provider's support team.
### Netlify Site Not Found
This likely means that your build failed. Please claim your site (you can find it on your [deploy history](https://windsurf.com/deploy)) and check the build logs for more details. Oftentimes you can paste your build logs into Cascade and ask for help.
### Changing Your Subdomain / URL
#### Updating `netlify.app` domain
You can change your subdomain by claiming your deployment and updating the Netlify site settings. This will update your `.netlify.app` domain.
#### Updating custom `.windsurf.build` subdomain
You cannot change your custom `.windsurf.build` subdomain after you've
deployed. Instead, you'll need to deploy a new site with a new subdomain.
To update your custom `.windsurf.build` subdomain, you'll need to deploy a new site with a new subdomain:
1. Delete the `windsurf_config.yaml` file from your project
2. Ask Cascade to deploy a new site with a new subdomain and tell it which one you want
3. It can help to start a new conversation or clear your auto-generated memories so that Cascade doesn't try to re-deploy to the old subdomain
4. When you create a new deployment, you'll be able to press the "Edit" button on the subdomain UI to update it prior to pressing "Deploy"
### Error: `Unable to get project name for project ID`
This error occurs when your project ID is not found in our system of records or if Cascade is using the subdomain as the project ID incorrectly. To fix this:
1. Check that the project still exists in your Netlify account (assuming it is claimed).
2. Check that the project ID is in the `windsurf_deployment.yaml` file. If it is not in the file, you can download your config file from your [deploy history](https://windsurf.com/deploy) dropdown.
3. Try redeploying and telling Cascade to use the `project_id` from the `windsurf_deployment.yaml` file more explicitly
# Arena Mode
Source: https://docs.devinenterprise.com/desktop/cascade/arena
Run multiple Cascade instances in parallel using arena mode to explore different approaches simultaneously.
Cascade supports **arena mode** to allow you to easily compare responses from different models on the same prompt.
**Arena mode applies to the legacy Cascade agent only.** The [Devin Local agent](/desktop/devin-local) — the default agent for new tabs — does not support arena mode (see [Limitations](/desktop/devin-local#limitations)).
| Mode | Use Case |
| ---------- | --------------------------------------- |
| **Single** | Run Cascade with a single chosen model |
| **Arena** | Compare responses from different models |
## Arena Mode
To enter arena mode, click the **arena** button in the model picker and choose your preferred models.
When you select multiple models, Cascade will independently execute your prompt with each model in a separate session. Each model also gets its own [worktree](./worktrees) for isolation.
If you want to view both conversations at the same time, you can drag the
Cascade tab into the main editor window to expand the available space.
You can independently continue working in each Cascade conversation, including accepting or rejecting changes or asking follow-up questions.
Since each model has its own [worktree](./worktrees), you can iterate on each response without affecting the other sessions.
### Choosing the better response
When you're ready to commit to a particular approach, you should click the "X is better" button to **discard** other conversations and *converge* all models to continue with your chosen approach.
The next message you send after converging will be sent to all models you have selected, allowing you to continue trying out different approaches.
## Battle Groups
Instead of manually selecting models, you can select one of our curated model groups to have Cascade randomly choose two models to compare. We have three random model groups available:
* **Frontier**: Includes frontier reasoning models like GPT 5.2, Claude Opus/Sonnet 4.5, Gemini 3 Pro, etc., optimized for intelligence.
* **Fast**: Includes fast reasoning models like SWE 1.5, Claude Haiku, GPT-5.3-Codex-Spark, etc., optimized for speed.
* **Hybrid**: A mix of frontier and fast models for a balance of speed and intelligence.
When you use one of the battle groups, the exact model names are hidden from you until you click the "X is better" button to converge the models. Then, the original model names are revealed and the conversations are reshuffled.
## Credit Cost
Arena mode charges the same credit cost for each individual model as running it separately. This means that if you select one 6x model and one 4x model, you will be charged 10 credits for each request.
For battle groups, the credit cost displayed is the cost of each individual model in the group. Since each battle group runs two models, the total credit cost per request is double the displayed cost.
## When To Use Arena Mode
Arena mode is particularly useful when you want to:
* Compare code quality across different models
* Explore different approaches to a hard problem
* Test out a new model without abandoning your standard preference
* Access frontier models at reduced cost by using the battle groups
## Limitations
* Arena mode is only supported for workspaces that have git initialized
* By default, only Git-tracked files are copied into the worktrees created for each model; you can configure a [setup hook](./worktrees#setup-hook) to copy additional files as needed
## Related Features
Isolate parallel work in separate git worktrees.
Automate actions before and after Cascade operations.
# Cascade Overview
Source: https://docs.devinenterprise.com/desktop/cascade/cascade
Cascade is Devin Desktop's agentic AI assistant with Code/Chat modes, tool calling, voice input, checkpoints, real-time awareness, and linter integration.
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](/desktop/devin-local), 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.
Cascade, Devin Local, and every other ACP agent are unavailable while a workspace is open in Restricted Mode.
### Quick links to features
Search the web for information to be referenced in Cascade's suggestions.
Memories and rules help customize behavior.
MCP servers extend the agent's capabilities.
An upgraded Terminal experience.
Automate repetitive trajectories.
Deploy applications in one click.
# 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.
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](/desktop/cascade/memories), 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, [Web Search](/desktop/cascade/web-search), [MCP](/desktop/cascade/mcp), and the [terminal](/desktop/terminal).
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.
Cascade can make up to 20 tool calls per prompt. If the trajectory stops, 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 configure an `Auto-Continue` setting to have Cascade automatically continue its response if it hits a limit. These will consume a prompt credit(s) corresponding to the model you are using.
# 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.
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 Cascade
When you have problems in your code which show up in the Problems panel at the bottom of the editor, simply click the `Send to Cascade` button to bring them into the Cascade panel as an @ mention.
# 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 `.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`.
## 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
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.
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](./worktrees) to keep them isolated.
# Cascade Hooks
Source: https://docs.devinenterprise.com/desktop/cascade/hooks
Execute custom shell commands at key points in Cascade's workflow for logging, security controls, validation, and enterprise governance with pre and post hooks.
Cascade Hooks enable you to execute custom shell commands at key points during Cascade's workflow. This powerful extensibility feature allows you to log operations, enforce guardrails, run validation checks, or integrate with external systems.
The hooks described here are Cascade hooks. The [Devin Local agent](/desktop/devin-local) has its own [lifecycle hooks](/cli/extensibility/hooks/lifecycle-hooks) with a different configuration format.
Hooks are designed for power users and enterprise teams who need fine-grained control over Cascade's behavior. They require basic shell scripting knowledge.
Hooks do not load or run while a workspace is open in Restricted Mode.
## What You Can Build
Hooks unlock a wide range of automation and governance capabilities:
* **Logging & Analytics**: Track every file read, code change, command executed, user prompt, or Cascade response for compliance and usage analysis
* **Security Controls**: Block Cascade from accessing sensitive files, running dangerous commands, or processing policy-violating prompts
* **Quality Assurance**: Run linters, formatters, or tests automatically after code modifications
* **Custom Workflows**: Integrate with issue trackers, notification systems, or deployment pipelines
* **Team Standardization**: Enforce coding standards and best practices across your organization
## How Hooks Work
Hooks are shell commands that run automatically when specific Cascade actions occur. Each hook:
1. **Receives context** (details about the action being performed) via JSON as standard input
2. **Executes your script** - Python, Bash, Node.js, or any executable
3. **Returns a result** via exit code and output streams
For **pre-hooks** (executed before an action), your script can **block the action** by exiting with exit code `2`. This makes pre-hooks ideal for implementing security policies or validation checks.
## Configuration
Hooks are configured in JSON files that can be placed at three different levels. Cascade loads and merges hooks from all locations, giving teams flexibility in how they distribute and manage hook configurations.
#### System-Level
System-level hooks are ideal for organization-wide policies enforced on shared development machines. For example, you can use them to enforce security policies, compliance requirements, or mandatory code review workflows. Enterprise teams can also configure hooks via the [cloud dashboard](#cloud-dashboard-configuration) without managing local files.
* **macOS**: `/Library/Application Support/Windsurf/hooks.json`
* **Linux/WSL**: `/etc/windsurf/hooks.json`
* **Windows**: `C:\ProgramData\Windsurf\hooks.json`
#### User-Level
User-level hooks are perfect for personal preferences and optional workflows.
* **Devin Desktop IDE**: `~/.codeium/windsurf/hooks.json`
* **JetBrains Plugin**: `~/.codeium/hooks.json`
#### Workspace-Level
Workspace-level hooks allow teams to version control project-specific policies alongside their code. They may include custom validation rules, project-specific integrations, or team-specific workflows.
* **Location**: `.windsurf/hooks.json` in your workspace root
Hooks from all three locations are **merged together**. If the same hook event is configured in multiple locations, all hooks will execute in order: system → user → workspace.
### Basic Structure
Here is an example of the basic structure of the hooks configuration:
```json theme={null}
{
"hooks": {
"pre_read_code": [
{
"command": "python3 /path/to/your/script.py",
"powershell": "python3 C:\\path\\to\\your\\script.py",
"show_output": true
}
],
"post_write_code": [
{
"command": "python3 /path/to/another/script.py",
"show_output": true
}
]
}
}
```
In this example, `pre_read_code` specifies both a macOS/Linux command and a Windows PowerShell command. The `post_write_code` hook only specifies `command`, so it will run on macOS/Linux and fall back to PowerShell on Windows.
### Configuration Options
Each hook accepts the following parameters:
| Parameter | Type | Description |
| ------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| `command` | string | The shell command to execute on **macOS/Linux** (run via `bash -c`). At least one of `command` or `powershell` must be specified. |
| `powershell` | string | Optional. The command to execute on **Windows** (run via `powershell -Command`). If omitted on Windows, `command` is used as a fallback. |
| `show_output` | boolean | Whether to display the hook's stdout/stderr output on the user-facing Cascade UI. Useful for debugging. |
| `working_directory` | string | Optional. The directory to execute the command from. Defaults to your workspace root. |
#### Cross-Platform Behavior
The `command` and `powershell` fields let you define platform-appropriate commands in a single configuration. This is useful for teams with mixed macOS/Linux and Windows fleets.
| Platform | `command` set | `powershell` set | Result |
| ----------- | :-----------: | :--------------: | ------------------------------------------------- |
| macOS/Linux | ✓ | (ignored) | Runs `command` via `bash -c` |
| macOS/Linux | ✗ | ✓ | Hook is silently skipped |
| Windows | ✓ | ✗ | Falls back to `command` via `powershell -Command` |
| Windows | ✗ | ✓ | Runs `powershell` via `powershell -Command` |
| Windows | ✓ | ✓ | Runs `powershell` via `powershell -Command` |
| Any | ✗ | ✗ | Validation error |
**About the `working_directory` parameter:**
* In multi-repo workspaces, the default is the root of the repo currently being worked on
* Relative paths resolve from the default location (workspace or repo root)
* Absolute paths are supported
* Using `~` for home directory expansion is not supported
## Hook Events
Cascade provides twelve hook events that cover the most critical actions in the agent workflow.
### Common Input Structure
All hooks receive a JSON object with the following common fields:
| Field | Type | Description |
| ------------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `agent_action_name` | string | The hook event name (e.g., "pre\_read\_code", "post\_write\_code") |
| `trajectory_id` | string | Unique identifier for the overall Cascade conversation |
| `execution_id` | string | Unique identifier for the single agent turn |
| `timestamp` | string | ISO 8601 timestamp when the hook was triggered |
| `model_name` | string | Human-readable name of the model associated with this hook invocation (e.g., "Claude Sonnet 4", "GPT 4.1"). This is the same label shown in the Cascade model selector. The value may change over time as Devin Desktop updates model display names. Set to "Unknown" when the model cannot be determined. |
| `tool_info` | object | Event-specific information (varies by hook type) |
In the following examples, the common fields are omitted for brevity. There are twelve major types of hook events:
### pre\_read\_code
Triggered **before** Cascade reads a code file. This may block the action if the hook exits with code 2.
**Use cases**: Restrict file access, log read operations, check permissions
**Input JSON**:
```json theme={null}
{
"agent_action_name": "pre_read_code",
"tool_info": {
"file_path": "/Users/yourname/project/file.py"
}
}
```
This `file_path` may be a directory path when Cascade reads a directory recursively.
### post\_read\_code
Triggered **after** Cascade successfully reads a code file.
**Use cases**: Log successful reads, track file access patterns
**Input JSON**:
```json theme={null}
{
"agent_action_name": "post_read_code",
"tool_info": {
"file_path": "/Users/yourname/project/file.py"
}
}
```
This `file_path` may be a directory path when Cascade reads a directory recursively.
### pre\_write\_code
Triggered **before** Cascade writes or modifies a code file. This may block the action if the hook exits with code 2.
**Use cases**: Prevent modifications to protected files, backup files before changes
**Input JSON**:
```json theme={null}
{
"agent_action_name": "pre_write_code",
"tool_info": {
"file_path": "/Users/yourname/project/file.py",
"edits": [
{
"old_string": "def old_function():\n pass",
"new_string": "def new_function():\n return True"
}
]
}
}
```
### post\_write\_code
Triggered **after** Cascade writes or modifies a code file.
**Use cases**: Run linters, formatters, or tests; log code changes
**Input JSON**:
```json theme={null}
{
"agent_action_name": "post_write_code",
"tool_info": {
"file_path": "/Users/yourname/project/file.py",
"edits": [
{
"old_string": "import os",
"new_string": "import os\nimport sys"
}
]
}
}
```
### pre\_run\_command
Triggered **before** Cascade executes a terminal command. This may block the action if the hook exits with code 2.
**Use cases**: Block dangerous commands, log all command executions, add safety checks
**Input JSON**:
```json theme={null}
{
"agent_action_name": "pre_run_command",
"tool_info": {
"command_line": "npm install package-name",
"cwd": "/Users/yourname/project"
}
}
```
### post\_run\_command
Triggered **after** Cascade executes a terminal command.
**Use cases**: Log command results, trigger follow-up actions
**Input JSON**:
```json theme={null}
{
"agent_action_name": "post_run_command",
"tool_info": {
"command_line": "npm install package-name",
"cwd": "/Users/yourname/project"
}
}
```
### pre\_mcp\_tool\_use
Triggered **before** Cascade invokes an MCP (Model Context Protocol) tool. This may block the action if the hook exits with code 2.
**Use cases**: Log MCP usage, restrict which MCP tools can be used
**Input JSON**:
```json theme={null}
{
"agent_action_name": "pre_mcp_tool_use",
"tool_info": {
"mcp_server_name": "github",
"mcp_tool_arguments": {
"owner": "code-owner",
"repo": "my-cool-repo",
"title": "Bug report",
"body": "Description of the bug here"
},
"mcp_tool_name": "create_issue"
}
}
```
### post\_mcp\_tool\_use
Triggered **after** Cascade successfully invokes an MCP tool.
**Use cases**: Log MCP operations, track API usage, see MCP results
**Input JSON**:
```json theme={null}
{
"agent_action_name": "post_mcp_tool_use",
"tool_info": {
"mcp_result": "...",
"mcp_server_name": "github",
"mcp_tool_arguments": {
"owner": "code-owner",
"perPage": 1,
"repo": "my-cool-repo",
"sha": "main"
},
"mcp_tool_name": "list_commits"
}
}
```
### pre\_user\_prompt
Triggered **before** Cascade processes the text of a user's prompt. This may block the action if the hook exits with code 2.
**Use cases**: Log all user prompts for auditing, block potentially harmful or policy-violating prompts
**Input JSON**:
```json theme={null}
{
"agent_action_name": "pre_user_prompt",
"tool_info": {
"user_prompt": "can you run the echo hello command"
}
}
```
The `show_output` configuration option does not apply to this hook.
### post\_cascade\_response
Triggered asynchronously **after** Cascade completes a response to a user's prompt. This hook receives the full Cascade response ever since the last user input.
**Use cases**: Log all Cascade responses for auditing, analyze response patterns, send responses to external systems for compliance review
**Input JSON**:
```json theme={null}
{
"agent_action_name": "post_cascade_response",
"tool_info": {
"response": "### Planner Response\n\nI'll help you create that file.\n\n*Created file `/path/to/file.py`*\n\n### Planner Response\n\nThe file has been created successfully."
}
}
```
The `response` field contains the markdown-formatted content of Cascade's response since the last user input. This includes planner responses, tool actions (file reads, writes, commands), and any other steps Cascade took. It also includes information about which [rules](/desktop/cascade/memories) were triggered. See the [Tracking Triggered Rules](#tracking-triggered-rules) example for how to parse rule usage.
The `show_output` configuration option does not apply to this hook.
The `response` content is derived from trajectory data and may contain sensitive information from your codebase or conversations. Handle this data according to your organization's security and privacy policies.
### post\_cascade\_response\_with\_transcript
Triggered asynchronously **after** Cascade completes a response to a user's prompt, similar to `post_cascade_response`. Instead of providing a markdown summary inline, this hook writes the full conversation transcript (from the beginning of the conversation) to a local JSONL file and provides the file path.
**Use cases**: Enterprise audit and compliance logging, tracking AI-generated contributions, feeding transcripts to external observability or analytics tools
**Input JSON**:
```json theme={null}
{
"agent_action_name": "post_cascade_response_with_transcript",
"tool_info": {
"transcript_path": "/Users/yourname/.windsurf/transcripts/{trajectory_id}.jsonl"
}
}
```
The `transcript_path` points to a [JSONL](https://jsonlines.org/) file at `~/.windsurf/transcripts/{trajectory_id}.jsonl`. Each line is a JSON object representing a single step in the conversation, with a `type` and `status` field plus step-specific data. For example:
```jsonl theme={null}
{"status":"done","type":"user_input","user_input":{"rules_applied":{"always_on":["my-rule.md"]},"user_response":"create a hello world file"}}
{"planner_response":{"response":"I'll create a hello world file for you."},"status":"done","type":"planner_response"}
{"code_action":{"new_content":"print('hello world')\n","path":"/path/to/file.py"},"status":"done","type":"code_action"}
{"planner_response":{"response":"I created the file for you."},"status":"done","type":"planner_response"}
```
The transcript includes detailed, customer-owned data such as file contents, command outputs, tool arguments, search results, and [rules](/desktop/cascade/memories) that were applied. Please note that the exact structure of each step may change in future versions, so please build any hook consumers to be resilient.
Transcript files are written with `0600` permissions. Devin Desktop automatically limits the transcripts directory to 100 files, pruning the oldest by modification time.
The `show_output` configuration option does not apply to this hook.
This table shows the key differences between `post_cascade_response` and `post_cascade_response_with_transcript` hooks:
| | `post_cascade_response` | `post_cascade_response_with_transcript` |
| ---------------- | ---------------------------------------- | --------------------------------------------------------------------- |
| **Data scope** | Only the steps since the last user input | The full conversation from the beginning |
| **Format** | Markdown summary in `tool_info.response` | Structured JSONL file at `tool_info.transcript_path` |
| **Detail level** | Condensed, human-readable summary | Detailed, machine-readable data (file contents, command output, etc.) |
| **Delivery** | Inline via stdin JSON | File on disk (`~/.windsurf/transcripts/`) |
Transcript files will contain sensitive information from your codebase including file contents, command outputs, and conversation history. Handle these files according to your organization's security and privacy policies.
### post\_setup\_worktree
Triggered **after** a new [git worktree](./worktrees) is created and configured. The hook is executed inside the new **worktree** directory.
**Use cases**: Copy `.env` files or other untracked files into the worktree, install dependencies, run setup scripts
**Environment Variables**:
| Variable | Description |
| ---------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| `$ROOT_WORKSPACE_PATH` | The absolute path to the original workspace. Use this to access files or run commands relative to the original repository. |
**Input JSON**:
```json theme={null}
{
"agent_action_name": "post_setup_worktree",
"tool_info": {
"worktree_path": "/Users/me/.windsurf/worktrees/my-repo/abmy-repo-c123",
"root_workspace_path": "/Users/me/projects/my-repo"
}
}
```
## Exit Codes
Your hook scripts communicate results through exit codes:
| Exit Code | Meaning | Effect |
| --------- | -------------- | ---------------------------------------------------------------------------------------------------- |
| `0` | Success | Action proceeds normally |
| `2` | Blocking Error | The Cascade agent will see the error message from stderr. For pre-hooks, this **blocks** the action. |
| Any other | Error | Action proceeds normally |
Only **pre-hooks** (pre\_user\_prompt, pre\_read\_code, pre\_write\_code, pre\_run\_command, pre\_mcp\_tool\_use) can block actions using exit code 2. Post-hooks cannot block since the action has already occurred.
Keep in mind that the user can see any hook-generated standard output and standard error in the Cascade UI if `show_output` is true.
## Example Use Cases
### Logging All Cascade Actions
Track every action Cascade takes for auditing purposes.
**Config**:
```json theme={null}
{
"hooks": {
"post_read_code": [
{
"command": "python3 /Users/yourname/hooks/log_input.py",
"show_output": true
}
],
"post_write_code": [
{
"command": "python3 /Users/yourname/hooks/log_input.py",
"show_output": true
}
],
"post_run_command": [
{
"command": "python3 /Users/yourname/hooks/log_input.py",
"show_output": true
}
],
"post_mcp_tool_use": [
{
"command": "python3 /Users/yourname/hooks/log_input.py",
"show_output": true
}
],
"post_cascade_response": [
{
"command": "python3 /Users/yourname/hooks/log_input.py"
}
]
}
}
```
**Script** (`log_input.py`):
```python theme={null}
#!/usr/bin/env python3
import sys
import json
def main():
# Read the JSON data from stdin
input_data = sys.stdin.read()
# Parse the JSON
try:
data = json.loads(input_data)
# Write formatted JSON to file
with open("/Users/yourname/hooks/input.txt", "a") as f:
f.write('\n' + '='*80 + '\n')
f.write(json.dumps(data, indent=2, separators=(',', ': ')))
f.write('\n')
print(json.dumps(data, indent=2))
except json.JSONDecodeError as e:
print(f"Error parsing JSON: {e}", file=sys.stderr)
sys.exit(1)
if __name__ == "__main__":
main()
```
This script appends every hook invocation to a log file, creating an audit trail of all Cascade actions. You may transform the input data or perform custom logic as you see fit.
### Restricting File Access
Prevent Cascade from reading files outside a specific directory.
**Config**:
```json theme={null}
{
"hooks": {
"pre_read_code": [
{
"command": "python3 /Users/yourname/hooks/block_read_access.py",
"show_output": true
}
]
}
}
```
**Script** (`block_read_access.py`):
```python theme={null}
#!/usr/bin/env python3
import sys
import json
ALLOWED_PREFIX = "/Users/yourname/my-project/"
def main():
# Read the JSON data from stdin
input_data = sys.stdin.read()
# Parse the JSON
try:
data = json.loads(input_data)
if data.get("agent_action_name") == "pre_read_code":
tool_info = data.get("tool_info", {})
file_path = tool_info.get("file_path", "")
if not file_path.startswith(ALLOWED_PREFIX):
print(f"Access denied: Cascade is only allowed to read files under {ALLOWED_PREFIX}", file=sys.stderr)
sys.exit(2) # Exit code 2 blocks the action
print(f"Access granted: {file_path}", file=sys.stdout)
except json.JSONDecodeError as e:
print(f"Error parsing JSON: {e}", file=sys.stderr)
sys.exit(1)
if __name__ == "__main__":
main()
```
When Cascade attempts to read a file outside the allowed directory, this hook blocks the operation and displays an error message.
### Blocking Dangerous Commands
Prevent Cascade from executing potentially harmful commands.
**Config**:
```json theme={null}
{
"hooks": {
"pre_run_command": [
{
"command": "python3 /Users/yourname/hooks/block_dangerous_commands.py",
"show_output": true
}
]
}
}
```
**Script** (`block_dangerous_commands.py`):
```python theme={null}
#!/usr/bin/env python3
import sys
import json
DANGEROUS_COMMANDS = ["rm -rf", "sudo rm", "format", "del /f"]
def main():
# Read the JSON data from stdin
input_data = sys.stdin.read()
# Parse the JSON
try:
data = json.loads(input_data)
if data.get("agent_action_name") == "pre_run_command":
tool_info = data.get("tool_info", {})
command = tool_info.get("command_line", "")
for dangerous_cmd in DANGEROUS_COMMANDS:
if dangerous_cmd in command:
print(f"Command blocked: '{dangerous_cmd}' is not allowed for safety reasons.", file=sys.stderr)
sys.exit(2) # Exit code 2 blocks the command
print(f"Command approved: {command}", file=sys.stdout)
except json.JSONDecodeError as e:
print(f"Error parsing JSON: {e}", file=sys.stderr)
sys.exit(1)
if __name__ == "__main__":
main()
```
This hook scans commands for dangerous patterns and blocks them before execution.
### Blocking Policy-Violating Prompts
Prevent users from submitting prompts that violate organizational policies.
**Config**:
```json theme={null}
{
"hooks": {
"pre_user_prompt": [
{
"command": "python3 /Users/yourname/hooks/block_bad_prompts.py"
}
]
}
}
```
**Script** (`block_bad_prompts.py`):
```python theme={null}
#!/usr/bin/env python3
import sys
import json
BLOCKED_PATTERNS = [
"something dangerous",
"bypass security",
"ignore previous instructions"
]
def main():
# Read the JSON data from stdin
input_data = sys.stdin.read()
# Parse the JSON
try:
data = json.loads(input_data)
if data.get("agent_action_name") == "pre_user_prompt":
tool_info = data.get("tool_info", {})
user_prompt = tool_info.get("user_prompt", "").lower()
for pattern in BLOCKED_PATTERNS:
if pattern in user_prompt:
print(f"Prompt blocked: Contains prohibited content. The user cannot ask the agent to do bad things.", file=sys.stderr)
sys.exit(2) # Exit code 2 blocks the prompt
except json.JSONDecodeError as e:
print(f"Error parsing JSON: {e}", file=sys.stderr)
sys.exit(1)
if __name__ == "__main__":
main()
```
This hook examines user prompts before they are processed and blocks any that contain prohibited patterns. When a prompt is blocked, the user sees an error message in the Cascade UI.
### Logging Cascade Responses
Track all Cascade responses for compliance auditing or analytics.
**Config**:
```json theme={null}
{
"hooks": {
"post_cascade_response": [
{
"command": "python3 /Users/yourname/hooks/log_cascade_response.py"
}
]
}
}
```
**Script** (`log_cascade_response.py`):
```python theme={null}
#!/usr/bin/env python3
import sys
import json
from datetime import datetime
def main():
# Read the JSON data from stdin
input_data = sys.stdin.read()
# Parse the JSON
try:
data = json.loads(input_data)
if data.get("agent_action_name") == "post_cascade_response":
tool_info = data.get("tool_info", {})
cascade_response = tool_info.get("response", "")
trajectory_id = data.get("trajectory_id", "unknown")
timestamp = data.get("timestamp", datetime.now().isoformat())
# Log to file
with open("/Users/yourname/hooks/cascade_responses.log", "a") as f:
f.write(f"\n{'='*80}\n")
f.write(f"Timestamp: {timestamp}\n")
f.write(f"Trajectory ID: {trajectory_id}\n")
f.write(f"Response:\n{cascade_response}\n")
print(f"Logged Cascade response for trajectory {trajectory_id}")
except json.JSONDecodeError as e:
print(f"Error parsing JSON: {e}", file=sys.stderr)
sys.exit(1)
if __name__ == "__main__":
main()
```
This hook logs every Cascade response to a file, creating an audit trail of all AI-generated content. You can extend this to send data to external logging systems, databases, or compliance platforms.
### Tracking Triggered Rules
Track which [rules](/desktop/cascade/memories) were applied during Cascade interactions for observability and metrics.
**Config**:
```json theme={null}
{
"hooks": {
"post_cascade_response": [
{
"command": "python3 /Users/yourname/hooks/track_rules.py"
}
]
}
}
```
**Script** (`track_rules.py`):
```python theme={null}
#!/usr/bin/env python3
import sys
import json
import re
from datetime import datetime
def extract_triggered_rules(response: str) -> dict:
"""
Parse triggered rules from the Cascade response.
Rules appear as: - (Rule-Type) Triggered Rule: rule-filename.md
"""
pattern = r"- \(([^)]+)\) Triggered Rule: (.+?)(?:\s*$)"
rules = {}
for match in re.finditer(pattern, response, re.MULTILINE):
rule_type, rule_name = match.groups()
if rule_type not in rules:
rules[rule_type] = []
rules[rule_type].append(rule_name)
return rules
def main():
input_data = sys.stdin.read()
try:
data = json.loads(input_data)
if data.get("agent_action_name") == "post_cascade_response":
response = data.get("tool_info", {}).get("response", "")
trajectory_id = data.get("trajectory_id", "unknown")
timestamp = data.get("timestamp", datetime.now().isoformat())
rules = extract_triggered_rules(response)
total_rules = sum(len(v) for v in rules.values())
# Log to file
with open("/Users/yourname/hooks/rules_usage.log", "a") as f:
f.write(f"\n{'='*60}\n")
f.write(f"Timestamp: {timestamp}\n")
f.write(f"Trajectory: {trajectory_id}\n")
f.write(f"Total rules triggered: {total_rules}\n")
for rule_type, rule_list in rules.items():
if rule_list:
f.write(f" {rule_type}: {', '.join(rule_list)}\n")
print(f"Tracked {total_rules} triggered rules")
except json.JSONDecodeError as e:
print(f"Error parsing JSON: {e}", file=sys.stderr)
sys.exit(1)
if __name__ == "__main__":
main()
```
**Rule types:**
* `Always On` - Rules that are always included
* `Model Decision` - Rules whose descriptions were shown to the model for conditional application
* `Manual` - Rules explicitly @-mentioned in user input
* `Global` - Global rules from `global_rules.md`
* `Glob` - Rules triggered by file access matching glob patterns
This tracks which rules were *presented* to the model or *triggered* by file access, but does not indicate whether the model actually *followed* a rule. Rules that have already been shown recently in the conversation are deduplicated and may not appear again until later.
### Running Code Formatters After Edits
Automatically format code files after Cascade modifies them.
**Config**:
```json theme={null}
{
"hooks": {
"post_write_code": [
{
"command": "bash /Users/yourname/hooks/format_code.sh",
"show_output": false
}
]
}
}
```
**Script** (`format_code.sh`):
```bash theme={null}
#!/bin/bash
# Read JSON from stdin
input=$(cat)
# Extract file path using jq
file_path=$(echo "$input" | jq -r '.tool_info.file_path')
# Format based on file extension
if [[ "$file_path" == *.py ]]; then
black "$file_path" 2>&1
echo "Formatted Python file: $file_path"
elif [[ "$file_path" == *.js ]] || [[ "$file_path" == *.ts ]]; then
prettier --write "$file_path" 2>&1
echo "Formatted JS/TS file: $file_path"
elif [[ "$file_path" == *.go ]]; then
gofmt -w "$file_path" 2>&1
echo "Formatted Go file: $file_path"
fi
exit 0
```
This hook automatically runs the appropriate formatter based on the file type after each edit.
### Setting Up Worktrees
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.
## Best Practices
### Security
**Use Cascade Hooks at Your Own Risk**: Hooks execute shell commands automatically with your user account's full permissions. You are entirely responsible for the code you configure. Poorly designed or malicious hooks can modify files, delete data, expose credentials, or compromise your system.
* **Validate all inputs**: Never trust the input JSON without validation, especially for file paths and commands.
* **Use absolute paths**: Always use absolute paths in your hook configurations to avoid ambiguity.
* **Protect sensitive data**: Avoid logging sensitive information like API keys or credentials.
* **Review permissions**: Ensure your hook scripts have appropriate file system permissions.
* **Audit before deployment**: Review every hook command and script before adding to your configuration.
* **Test in isolation**: Run hooks in a test environment before enabling them on your primary development machine.
### Performance Considerations
* **Keep hooks fast**: Slow hooks will impact Cascade's responsiveness. Aim for sub-100ms execution times.
* **Use async operations**: For non-blocking hooks, consider logging to a queue or database asynchronously.
* **Filter early**: Check the action type at the start of your script to avoid unnecessary processing.
### Error Handling
* **Always validate JSON**: Use try-catch blocks to handle malformed input gracefully.
* **Log errors properly**: Write errors to `stderr` so they're visible when `show_output` is enabled.
* **Fail safely**: If your hook encounters an error, consider whether it should block the action or allow it to proceed.
### Testing Your Hooks
1. **Start with logging**: Begin by implementing a simple logging hook to understand the data flow.
2. **Use `show_output: true`**: Enable output during development to see what your hooks are doing.
3. **Test blocking behavior**: Verify that exit code 2 properly blocks actions in pre-hooks.
4. **Check all code paths**: Test both success and failure scenarios in your scripts.
## Enterprise Distribution
Enterprise organizations need to enforce security policies, compliance requirements, and development standards that individual users cannot bypass. Cascade Hooks supports two enterprise distribution methods:
1. **Cloud Dashboard** - Configure hooks via Team Settings in the Devin Desktop dashboard
2. **System-Level Files** - Deploy hooks via MDM or configuration management tools
Both methods can be used together — hooks from all sources are combined and executed in order.
### Cloud Dashboard Configuration
Team admins can configure Cascade Hooks directly from the Devin Desktop dashboard.
**Requirements:**
* Enterprise plan
* `TEAM_SETTINGS_UPDATE` permission
**To configure:**
1. Navigate to **Team Settings** in the Devin Desktop dashboard
2. Find the **Cascade Hooks** section
3. Enter your hooks configuration in JSON format
4. Save your changes
Hooks configured through the dashboard are automatically distributed to all team members and loaded when Devin Desktop starts. Cloud-configured hooks are loaded first, followed by system-level, user-level, and workspace-level hooks.
When multiple team configurations are merged, hooks are combined per action rather than overwritten. This means hooks from all applicable team configs will run together.
### System-Level File Deployment
For organizations that prefer file-based configuration or need hooks to work offline, deploy your mandatory `hooks.json` configuration to these OS-specific locations:
**macOS:**
```
/Library/Application Support/Windsurf/hooks.json
```
**Linux/WSL:**
```
/etc/windsurf/hooks.json
```
**Windows:**
```
C:\ProgramData\Windsurf\hooks.json
```
Place your hook scripts in a corresponding system directory (e.g., `/usr/local/share/windsurf-hooks/` on Unix systems).
System-level hooks take precedence over user and workspace hooks, and cannot be disabled by end users without root permissions.
#### MDM and Configuration Management
Enterprise IT teams can deploy system-level hooks using standard tools:
**Mobile Device Management (MDM)**
* **Jamf Pro** (macOS) - Deploy via configuration profiles or scripts
* **Microsoft Intune** (Windows/macOS) - Use PowerShell scripts or policy deployment
* **Workspace ONE**, **Google Endpoint Management**, and other MDM solutions
**Configuration Management**
* **Ansible**, **Puppet**, **Chef**, **SaltStack** - Use your existing infrastructure automation
* **Custom deployment scripts** - Shell scripts, PowerShell, or your preferred tooling
#### Verification and Auditing
After deployment, verify that hooks are properly installed:
```bash theme={null}
# Verify system hooks are present
ls -la /etc/windsurf/hooks.json # Linux
ls -la "/Library/Application Support/Windsurf/hooks.json" # macOS
# Test hook execution (should see hook output in Cascade)
# Have a developer trigger the relevant Cascade action
# Verify users cannot modify system hooks
sudo chown root:root /etc/windsurf/hooks.json
sudo chmod 644 /etc/windsurf/hooks.json
```
**Important**: System-level hooks are entirely managed by your IT or security team. Devin Desktop does not deploy or manage files at system-level paths. Ensure your internal teams handle deployment, updates, and compliance according to your organization's policies.
### Workspace Hooks for Team Projects
For project-specific conventions, teams can use workspace-level hooks in version control:
```bash theme={null}
# Add to your repository
.windsurf/
├── hooks.json
└── scripts/
└── format-check.py
# Commit to git
git add .windsurf/
git commit -m "Add workspace hooks for code formatting"
```
This allows teams to standardize development practices. Keep security-critical policies at the cloud or system level, and avoid checking sensitive information into version control.
## Additional Resources
* **MCP Integration**: Learn more about [Model Context Protocol in Devin Desktop](/desktop/cascade/mcp)
* **Workflows**: Discover how to combine hooks with [Cascade Workflows](/desktop/cascade/workflows)
* **Analytics**: Track Cascade usage with [Team Analytics](/desktop/accounts/analytics)
# Model Context Protocol (MCP)
Source: https://docs.devinenterprise.com/desktop/cascade/mcp
Integrate MCP servers with Cascade to access custom tools like GitHub, databases, and APIs. Configure stdio, HTTP, and SSE transports with admin controls for Teams.
**MCP (Model Context Protocol)** is a protocol that enables LLMs to access custom tools and services.
An MCP client (Cascade, in this case) can make requests to MCP servers to access tools that they provide.
Cascade now natively integrates with MCP, allowing you to bring your own selection of MCP servers for Cascade to use.
See the [official MCP docs](https://modelcontextprotocol.io/) for more information.
Enterprise users must manually turn this on via settings
**The MCP configuration on this page applies to the legacy Cascade agent only.** The [Devin Local agent](/desktop/devin-local) — the default agent for new tabs — configures MCP servers in the Devin CLI [config files](/cli/extensibility/mcp/configuration) instead.
## Adding a new MCP
New MCPs can be added from the MCP Marketplace, which you access by
clicking on the `MCPs` icon in the top right menu in the Cascade panel, or from
the `Devin Settings` > `Cascade` > `MCP Servers` section.
If you cannot find your desired MCP, you can add it manually by editing the raw `mcp_config.json` file.
Official MCPs will show up with a blue checkmark, indicating that they are made by the parent service company.
When you click on a MCP, simply click `Install` to expose the server and its tools to Cascade.
### One-Click Install via Deeplink
Devin Desktop supports one-click MCP installation through deeplinks. You can use these links to open the MCP
registry page directly in Devin Desktop, which is useful for sharing MCP server recommendations or embedding
install buttons in documentation.
The deeplink format is:
```
windsurf://windsurf-mcp-registry?serverName=
```
* **With `serverName`**: Opens the MCP registry page for the specified server, where the user can review and install it.
* **Without `serverName`**: Opens the MCP Marketplace page.
For example, `windsurf://windsurf-mcp-registry?serverName=github-mcp-server` will open the GitHub MCP server's
registry page in Devin Desktop.
One-click install deeplinks require that the user's team has MCP access enabled. If MCP access is disabled by an admin, the deeplink will not open the registry page.
Devin Desktop supports three [transport types](https://modelcontextprotocol.io/docs/concepts/transports) for MCP
servers: `stdio`, `Streamable HTTP`, and `SSE`.
Devin Desktop also supports OAuth for each transport type.
For `http` servers, the URL should reflect that of the endpoint and resemble `https:///mcp`.
## Configuring MCP tools
Each MCP has a certain number of tools it has access to. Cascade has a limit of 100 total tools that it has access to at any given time.
On each MCP settings page, you can toggle the tools that you wish to enable. To
open settings for a MCP, click on the `MCPs` icon in the top right menu in the
Cascade panel, and click on the desired MCP.
## mcp\_config.json
The `~/.codeium/windsurf/mcp_config.json` file is a JSON file that contains a list of servers that Cascade can connect to.
Here’s an example configuration, which sets up a single server for GitHub:
```json theme={null}
{
"mcpServers": {
"github": {
"command": "npx",
"args": [
"-y",
"@modelcontextprotocol/server-github"
],
"env": {
"GITHUB_PERSONAL_ACCESS_TOKEN": ""
}
}
}
}
```
Be sure to provide the required arguments and environment variables for the servers that you want to use.
See the [official MCP server reference repository](https://github.com/modelcontextprotocol/servers) or [OpenTools](https://opentools.com/) for some example servers.
### Popular MCP Server Examples
Below are configuration examples for some commonly used MCP servers. These can be added to your `mcp_config.json` file.
The GitHub MCP server provides tools for repository management, file operations, issue tracking, and pull request management.
**Using npx:**
```json theme={null}
{
"mcpServers": {
"github": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-github"],
"env": {
"GITHUB_PERSONAL_ACCESS_TOKEN": ""
}
}
}
}
```
**Using Docker:**
```json theme={null}
{
"mcpServers": {
"github": {
"command": "docker",
"args": [
"run", "-i", "--rm",
"-e", "GITHUB_PERSONAL_ACCESS_TOKEN",
"ghcr.io/github/github-mcp-server"
],
"env": {
"GITHUB_PERSONAL_ACCESS_TOKEN": ""
}
}
}
}
```
To create a personal access token, visit [GitHub Settings > Developer settings > Personal access tokens](https://github.com/settings/tokens).
The Slack MCP server enables channel management, messaging, and workspace interactions.
```json theme={null}
{
"mcpServers": {
"slack": {
"command": "npx",
"args": ["-y", "@anthropic/mcp-server-slack"],
"env": {
"SLACK_BOT_TOKEN": "",
"SLACK_TEAM_ID": ""
}
}
}
}
```
To set up a Slack bot token:
1. Create a Slack App at [api.slack.com/apps](https://api.slack.com/apps)
2. Add the required OAuth scopes (e.g., `channels:read`, `chat:write`, `users:read`)
3. Install the app to your workspace and copy the Bot User OAuth Token
The PostgreSQL MCP server provides read-only access to PostgreSQL databases, including schema inspection and query execution.
```json theme={null}
{
"mcpServers": {
"postgres": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-postgres"],
"env": {
"POSTGRES_CONNECTION_STRING": "postgresql://user:password@localhost:5432/database"
}
}
}
}
```
The PostgreSQL server provides read-only access by default for safety. Ensure your connection string uses appropriate credentials with limited permissions.
The Filesystem MCP server provides secure access to local files and directories with configurable access controls.
```json theme={null}
{
"mcpServers": {
"filesystem": {
"command": "npx",
"args": [
"-y", "@modelcontextprotocol/server-filesystem",
"/path/to/allowed/directory"
]
}
}
}
```
You can specify multiple allowed directories by adding additional path arguments. Only files within these directories will be accessible.
The Brave Search MCP server enables web search capabilities using Brave's Search API.
```json theme={null}
{
"mcpServers": {
"brave-search": {
"command": "npx",
"args": ["-y", "@anthropic/mcp-server-brave-search"],
"env": {
"BRAVE_API_KEY": ""
}
}
}
}
```
To get a Brave API key, sign up at [brave.com/search/api](https://brave.com/search/api/).
The Memory MCP server provides a persistent memory system using a knowledge graph, allowing Cascade to remember information across sessions.
```json theme={null}
{
"mcpServers": {
"memory": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-memory"]
}
}
}
```
The memory server stores data locally and persists across sessions, making it useful for maintaining context about projects, preferences, and learned information.
### Remote HTTP MCPs
It's important to note that for remote HTTP MCPs, the configuration is slightly
different and requires a `serverUrl` or `url` field.
Here's an example configuration for an HTTP server:
```json theme={null}
{
"mcpServers": {
"remote-http-mcp": {
"serverUrl": "/mcp",
"headers": {
"API_KEY": "value"
}
}
}
}
```
### Config Interpolation
The `~/.codeium/windsurf/mcp_config.json` file supports variable interpolation
in the following fields: `command`, `args`, `env`, `serverUrl`, `url`, and
`headers`. This lets you avoid hardcoding secrets directly in the config file.
Two interpolation patterns are supported:
* **`${env:VAR_NAME}`** — replaced with the value of the environment variable `VAR_NAME`. If the variable is not set, it resolves to an empty string.
* **`${file:/path/to/file}`** — replaced with the trimmed contents of the file at the given path. Tilde paths (e.g. `~/secrets/key.txt`) are supported. If the file cannot be read, the pattern is left unchanged.
Here's an example using an environment variable in `headers`:
```json theme={null}
{
"mcpServers": {
"remote-http-mcp": {
"serverUrl": "/mcp",
"headers": {
"API_KEY": "Bearer ${env:AUTH_TOKEN}"
}
}
}
}
```
Here's an example reading an API key from a file:
```json theme={null}
{
"mcpServers": {
"my-server": {
"command": "node",
"args": ["server.js"],
"env": {
"API_KEY": "${file:~/.secrets/api_key.txt}"
}
}
}
}
```
## Admin Controls (Teams & Enterprises)
Team admins can toggle MCP access for their team, as well as allowlist approved MCP servers for their team to use:
### MCP Registry
Enterprise teams can configure custom MCP registries to replace the default Devin Desktop MCP marketplace. Teams can link their own registry URLs to control which MCPs are available to their users.
Registries are the preferred approach for managing MCP access, though allowlists will also work.
#### Configuring Custom Registries
1. Navigate to your team settings
2. Find the **MCP Registry URLs** setting
3. Add one or more registry URLs
When multiple registry URLs are configured, Devin Desktop takes the **union** of all registries—users will see MCPs from all configured sources combined. The team's MCP marketplace will then fetch from these internal registries rather than the default Devin Desktop registry.
Custom registries must follow the [official MCP registry schema](https://modelcontextprotocol.io/). This ensures compatibility and standardized server definitions.
### MCP Allowlist
Configurable MCP settings for your team.
The above link will only work if you have admin privileges for your team.
By default, users within a team will be able to configure their own MCP servers. However, once you allowlist even a single MCP server, **all non-allowlisted servers will be blocked** for your team.
The Server ID in the allowlist must match the key name (case-sensitive) used in the user's `mcp_config.json`.
### How Server Matching Works
When you allowlist an MCP server, the system uses **regex pattern matching** with the following rules:
* **Full String Matching**: All patterns are automatically anchored (wrapped with `^(?:pattern)$`) to prevent partial matches
* **Command Field**: Must match exactly or according to your regex pattern
* **Arguments Array**: Each argument is matched individually against its corresponding pattern
* **Array Length**: The number of arguments must match exactly between allowlist and user config
* **Special Characters**: Characters like `$`, `.`, `[`, `]`, `(`, `)` have special regex meaning and should be escaped with `\` if you want literal matching
### Configuration Options
**Admin Allowlist Configuration:**
* **Server ID**: `github-mcp-server`
* **Server Config (JSON)**: *(leave empty)*
```json theme={null}
{}
```
**Matching User Config (`mcp_config.json`):**
```json theme={null}
{
"mcpServers": {
"github-mcp-server": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"-e",
"GITHUB_PERSONAL_ACCESS_TOKEN",
"ghcr.io/github/github-mcp-server"
],
"env": {
"GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_your_token_here"
}
}
}
}
```
This allows users to install the GitHub MCP server with any valid configuration, as long as the server ID matches the plugin store entry.
**Admin Allowlist Configuration:**
* **Server ID**: `github-mcp-server`
* **Server Config (JSON)**:
```json theme={null}
{
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"-e",
"GITHUB_PERSONAL_ACCESS_TOKEN",
"ghcr.io/github/github-mcp-server"
],
"env": {
"GITHUB_PERSONAL_ACCESS_TOKEN": ""
}
}
```
**Matching User Config (`mcp_config.json`):**
```json theme={null}
{
"mcpServers": {
"github-mcp-server": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"-e",
"GITHUB_PERSONAL_ACCESS_TOKEN",
"ghcr.io/github/github-mcp-server"
],
"env": {
"GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_your_token_here"
}
}
}
}
```
Users must use this exact configuration - any deviation in command or args will be blocked. The `env` section can have different values.
**Admin Allowlist Configuration:**
* **Server ID**: `python-mcp-server`
* **Server Config (JSON)**:
```json theme={null}
{
"command": "python3",
"args": ["/.*\\.py", "--port", "[0-9]+"]
}
```
**Matching User Config (`mcp_config.json`):**
```json theme={null}
{
"mcpServers": {
"python-mcp-server": {
"command": "python3",
"args": ["/home/user/my_server.py", "--port", "8080"],
"env": {
"PYTHONPATH": "/home/user/mcp"
}
}
}
}
```
This example allows users flexibility while maintaining security:
* The regex `/.*\\.py` matches any Python file path like `/home/user/my_server.py`
* The regex `[0-9]+` matches any numeric port like `8080` or `3000`
* Users can customize file paths and ports while admins ensure only Python scripts are executed
### Common Regex Patterns
| Pattern | Matches | Example |
| --------------- | ------------------------- | ---------------------- |
| `.*` | Any string | `/home/user/script.py` |
| `[0-9]+` | Any number | `8080`, `3000` |
| `[a-zA-Z0-9_]+` | Alphanumeric + underscore | `api_key_123` |
| `\\$HOME` | Literal `$HOME` | `$HOME` (not expanded) |
| `\\.py` | Literal `.py` | `script.py` |
| `\\[cli\\]` | Literal `[cli]` | `mcp[cli]` |
## Notes
### Admin Configuration Guidelines
* **Environment Variables**: The `env` section is not regex-matched and can be configured freely by users
* **Disabled Tools**: The `disabledTools` array is handled separately and not part of allowlist matching
* **Case Sensitivity**: All matching is case-sensitive
* **Error Handling**: Invalid regex patterns will be logged and result in access denial
* **Testing**: Test your regex patterns carefully - overly restrictive patterns may block legitimate use cases
### Troubleshooting
If users report that their MCP servers aren't working after allowlisting:
1. **Check Exact Matching**: Ensure the allowlist pattern exactly matches the user's configuration
2. **Verify Regex Escaping**: Special characters may need escaping (e.g., `\.` for literal dots)
3. **Review Logs**: Invalid regex patterns are logged with warnings
4. **Test Patterns**: Use a regex tester to verify your patterns work as expected
Remember: Once you allowlist any server, **all other servers are automatically blocked** for your team members.
### General Information
* Since MCP tool calls can invoke code written by arbitrary server implementers, we do not assume liability
for MCP tool call failures. To reiterate:
* We currently support an MCP server's [tools](https://modelcontextprotocol.io/docs/concepts/tools), [resources](https://modelcontextprotocol.io/docs/concepts/resources), and [prompts](https://modelcontextprotocol.io/docs/concepts/prompts).
# Memories & Rules
Source: https://docs.devinenterprise.com/desktop/cascade/memories
Persist context across Cascade conversations with auto-generated memories and user-defined rules at global, workspace, and system levels for enterprise teams.
`Memories` is the system for sharing and persisting context across conversations.
There are two mechanisms for this in Devin Desktop: **Memories**, which are automatically generated by Cascade, and **Rules**, which are manually defined by the user at the global, workspace, or system level.
**Memories apply to the legacy Cascade agent only.** The [Devin Local agent](/desktop/devin-local) — the default agent for new tabs — does not persist memories. Migrate the ones you rely on to [skills](/desktop/cascade/skills) with the **Devin: Open Cascade Migration Wizard** command.
## Memories, Rules, Workflows, or Skills?
Devin Desktop offers several ways to customize Cascade. Use this table to pick the right one:
| Feature | What it does | How it's activated | When to use it |
| ------------------------------------------- | ------------------------------------------------------------------------ | ----------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
| **[Rules](#rules)** | Tell Cascade *how to behave* (e.g. "use bun, not npm") | `always_on`, `glob`, `model_decision`, or `manual` ([see below](#activation-modes)) | Coding conventions, style guides, project constraints |
| **[AGENTS.md](/desktop/cascade/agents-md)** | Location-scoped rules with zero config | Automatic — root = always-on, subdirectory = glob | Directory-specific conventions without frontmatter |
| **[Workflows](/desktop/cascade/workflows)** | Prompt templates for repeatable multi-step tasks | **Manual only** via `/[workflow-name]` slash command | Deployments, PR reviews, release checklists |
| **[Skills](/desktop/cascade/skills)** | Multi-step procedures bundled with supporting files (scripts, templates) | Dynamically invoked by the model, or `@mention` | Complex tasks where Cascade needs reference files — **invest here** |
| **[Memories](#memories)** | Context Cascade auto-generates during conversations | Automatic retrieval when relevant | Let Cascade remember one-off facts; for durable knowledge, prefer Rules or AGENTS.md |
**Recommendation:** For knowledge you want Cascade to reliably reuse, write it as a Rule or add it to `AGENTS.md` in your repo rather than relying on auto-generated Memories. Rules are version-controlled, shareable with your team, and give you explicit control over activation.
## How to Manage Memories
Memories and Rules can be accessed and configured at any time by clicking on the `Customizations` icon in the top right slider menu in Cascade, or via “Devin - Settings” in the bottom-right hand corner. To edit an existing memory, simply click into it and then click the `Edit` button.
## Memories
During conversation, Cascade can automatically generate and store memories if it encounters context that it believes is useful to remember.
Additionally, you can ask Cascade to create a memory at any time. Just prompt Cascade to "create a memory of ...".
Cascade's autogenerated memories are associated with the workspace they were created in and are stored locally in `~/.codeium/windsurf/memories/`. Cascade retrieves them when it believes they're relevant. Memories generated in one workspace are not available in another, and they are not committed to your repository.
Creating and using auto-generated memories do NOT consume credits.
Auto-generated memories live only on your machine. If you want Cascade to remember something durably — and share it with your team — ask Cascade to write it to a [Rule](#rules) in `.devin/rules/` (or the legacy `.windsurf/rules/`) or to your repo's `AGENTS.md` instead.
## Rules
Users can explicitly define their own rules for Cascade to follow.
Rules can be defined at the global, workspace, or system level, and can also be inferred from [AGENTS.md](/desktop/cascade/agents-md) files.
| Scope | Location | Notes |
| ----------------------------------------------------- | --------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Global | `~/.codeium/windsurf/memories/global_rules.md` | Single file, applied across all workspaces. Always on. Limited to 6,000 characters. |
| Workspace | `.devin/rules/*.md` (preferred) or `.windsurf/rules/*.md` (fallback) | One file per rule, each with its own [activation mode](#activation-modes). Limited to 12,000 characters per file. The legacy single-file `.windsurfrules` at the workspace root is also still read. |
| [AGENTS.md](/desktop/cascade/agents-md) | Any directory in your workspace | Processed by the same Rules engine — root-level = always-on, subdirectory = auto-glob for that directory. |
| [System (Enterprise)](#system-level-rules-enterprise) | OS-specific (e.g. `/etc/devin/rules/`, legacy `/etc/windsurf/rules/`) | Deployed by IT, read-only for end users. |
## Rules Discovery
Devin Desktop automatically discovers rules from multiple locations to provide flexible organization. The `.devin/` directory is the preferred location and takes precedence, with `.windsurf/` kept as a fallback for backward compatibility:
* **Current workspace and sub-directories**: All `.devin/rules` (and legacy `.windsurf/rules`) 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 rules in parent directories
* **Multiple workspace support**: When multiple folders are open in the same workspace, rules are deduplicated and displayed with the shortest relative path
### Rules Storage Locations
Rules can be stored in any of these locations (`.devin/` is preferred and takes precedence over `.windsurf/`):
* `.devin/rules` or `.windsurf/rules` in your current workspace directory
* `.devin/rules` or `.windsurf/rules` in any sub-directory of your workspace
* `.devin/rules` or `.windsurf/rules` in parent directories up to the git root (for git repositories)
When you create a new rule, it will be saved in the `.devin/rules` directory of your current workspace, not necessarily at the git root.
To get started with Rules, click on the `Customizations` icon in the top right slider menu in Cascade, then navigate to the `Rules` panel. Here, you can click on the `+ Global` or `+ Workspace` button to create new rules at either the global or workspace level, respectively.
You can find example rule templates curated by the Devin Desktop team at [https://windsurf.com/editor/directory](https://windsurf.com/editor/directory) to help you get started.
Workspace rule files are limited to 12,000 characters each. The global rules file is limited to 6,000 characters.
### Activation Modes
Each workspace rule declares an activation mode in its frontmatter via the `trigger` field. This controls **when** the rule's content is given to Cascade and **how much context window it consumes**:
| Mode | `trigger:` value | How it reaches Cascade | Context cost |
| ------------------ | ---------------- | ----------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------ |
| **Always On** | `always_on` | Full rule content is included in the system prompt on every message. | Every message |
| **Model Decision** | `model_decision` | Only the `description` is shown in the system prompt. Cascade reads the full rule file when it decides the description is relevant. | Description always; full content on demand |
| **Glob** | `glob` | Rule is applied when Cascade reads or edits a file matching the `globs` pattern (e.g. `*.js`, `src/**/*.ts`). | Only when matching files are touched |
| **Manual** | `manual` | Rule is **not** in the system prompt. You activate it by typing `@rule-name` in the Cascade input box. | Only when @mentioned |
The global rules file (`global_rules.md`) and root-level `AGENTS.md` files don't use frontmatter — they are always on.
Example workspace rule with frontmatter:
```markdown theme={null}
---
trigger: glob
globs: **/*.test.ts
---
All test files must use `describe`/`it` blocks and mock external API calls.
```
### Best Practices
To help Cascade follow your rules effectively, follow these best practices:
* Keep rules simple, concise, and specific. Rules that are too long or vague may confuse Cascade.
* There's no need to add generic rules (e.g. "write good code"), as these are already baked into Cascade's training data.
* Format your rules using bullet points, numbered lists, and markdown. These are easier for Cascade to follow compared to a long paragraph. For example:
```
# Coding Guidelines
- My project's programming language is python
- Use early returns when possible
- Always add documentation when creating new functions and classes
```
* XML tags can be an effective way to communicate and group similar rules together. For example:
```
- My project's programming language is python
- Use early returns when possible
- Always add documentation when creating new functions and classes
```
## System-Level Rules (Enterprise)
Enterprise organizations can deploy system-level rules that apply globally across all workspaces and cannot be modified by end users without administrator permissions. This is ideal for enforcing organization-wide coding standards, security policies, and compliance requirements.
System-level rules are loaded from OS-specific directories. The `Devin` directory is preferred and takes precedence, with the legacy `Windsurf` directory kept as a fallback:
**macOS:**
```
/Library/Application Support/Devin/rules/*.md
/Library/Application Support/Windsurf/rules/*.md # legacy fallback
```
**Linux/WSL:**
```
/etc/devin/rules/*.md
/etc/windsurf/rules/*.md # legacy fallback
```
**Windows:**
```
C:\ProgramData\Devin\rules\*.md
C:\ProgramData\Windsurf\rules\*.md # legacy fallback
```
Place your rule files (as `.md` files) in the appropriate directory for your operating system. The system will automatically load all `.md` files from these directories.
### How System Rules Work
System-level rules are merged with workspace and global rules, providing additional context to Cascade without overriding user-defined rules. This allows organizations to establish baseline standards while still permitting teams to add project-specific customizations.
In the Devin Desktop UI, system-level rules are displayed with a "System" label and cannot be deleted by end users.
**Important**: System-level rules 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.
# Cascade Modes
Source: https://docs.devinenterprise.com/desktop/cascade/modes
Devin Desktop offers multiple distinct agent modes, each optimized for different types of tasks.
Devin Desktop offers three distinct agent modes, each with a different set of capabilities designed for specific workflows.
| Mode | Use case | Tools |
| ------------------ | ----------------------------------- | ----------------- |
| [Code](#code-mode) | Complex features, refactoring | All tools enabled |
| [Plan](#plan-mode) | Complex features requiring planning | All tools enabled |
| [Ask](#ask-mode) | Learning, planning, questions | Search tools only |
You can switch between different modes using the mode selector below the input box, or by using the keyboard shortcut `⌘+.` (Mac) or `Ctrl+.` (Windows/Linux). The selector also offers permission modes, which control how much the agent asks before acting — see [Permissions](/cli/reference/permissions).
## Code Mode
**Code mode** is Devin Desktop's default fully agentic mode, designed for making changes to your codebase.
In Code mode, the agent can:
* Create, edit, and delete files
* Run terminal commands
* Search and analyze your codebase
* Install dependencies
* Execute multi-step tasks autonomously
Use Code mode when you want the agent to actively work on your project and implement changes.
We recommend you use Code mode as your default mode for most tasks.
## Plan Mode
**Plan mode** helps you think through complex tasks by developing a detailed implementation plan before writing any code.
In Plan mode, the agent will:
* Explore your codebase to understand the current state
* Ask clarifying questions to ensure the plan aligns with your goals
* Provide multiple options for you to choose from with an interactive interface
* Present a detailed plan, written in an external Markdown file, with implementation steps
The plan file lives outside your repository and persists for the session, so planning can span several messages. When the agent is finished, it asks to start implementing — or you can click "Implement" on the plan file yourself to switch to Code mode and begin.
### Planning more deeply
Including the keyword `megaplan`, `ultraplan`, or `masterplan` anywhere in your message switches the conversation into Plan mode and makes the agent plan more extensively, asking at least one clarifying question before it writes the plan. The previous mode is restored once you remove the keyword.
### Continuing from a plan
The markdown file created in plan mode can be particularly useful for continuing work across multiple sessions.
Plans are stored in your `~/.windsurf/plans` or `~/.devin/plans` directory, depending on the agent, and are available in the [@mentions](/desktop/chat/overview#%40-mentions) menu.
By mentioning a plan file, you can continue implementation with a fresh context.
This can be particularly useful when an initial implementation went awry: just discard the original changes, tweak the plan file, and click "Implement" to attempt implementation again in a new conversation.
### Exiting plan mode
There are multiple different ways to move from planning to implementation:
* Click the "Implement" button on the plan file
* Approve the agent's request to leave Plan mode once the plan is ready
* Change your mode to Code mode in the input box
* Let the agent *automatically* switch to Code mode when it detects that you're ready to implement
## Ask Mode
**Ask mode** is a read-only mode optimized for questions and exploration.
In ask mode, the agent can search and analyze your codebase, but cannot make any changes.
# Skills
Source: https://docs.devinenterprise.com/desktop/cascade/skills
Skills help Cascade handle complex, multi-step tasks.
The hardest engineering tasks often take more than just good prompts. They might require reference scripts, templates, checklists, and other supporting files. Skills let you bundle all of these together into folders that Cascade can invoke (read and use).
Skills are a great way to teach Cascade how to execute multi-step workflows consistently.
The [Devin Local agent](/desktop/devin-local) uses the Devin CLI skills format and discovery — see [Skills](/cli/extensibility/skills/overview).
Cascade uses [**progressive disclosure**](https://agentskills.io/what-are-skills#how-skills-work): only the skill's `name` and `description` are shown to the model by default. The full `SKILL.md` content and supporting files are loaded **only when Cascade decides to invoke the skill** (or when you `@mention` it). This keeps your context window lean even with many skills defined.
For more details on the Skills specification, visit [agentskills.io](https://agentskills.io/home).
## How to Create a Skill
### Using the UI (easiest)
1. Open the Cascade panel
2. Click the three dots in the top right of the panel to open up the customizations menu
3. Click on the `Skills` section
4. Click `+ Workspace` to create a workspace (project-specific) skill, or `+ Global` to create a global skill
5. Name the skill (lowercase letters, numbers, and hyphens only)
### Manual Creation
**Workspace Skill (project-specific):**
1. Create a directory: `.windsurf/skills//`
2. Add a `SKILL.md` file with YAML frontmatter
**Global Skill (available in all workspaces):**
1. Create a directory: `~/.codeium/windsurf/skills//`
2. Add a `SKILL.md` file with YAML frontmatter
## SKILL.md File Format
Each skill requires a `SKILL.md` file with YAML frontmatter containing the skill's metadata:
### Example skill
```markdown theme={null}
---
name: deploy-to-production
description: Guides the deployment process to production with safety checks
---
## Pre-deployment Checklist
1. Run all tests
2. Check for uncommitted changes
3. Verify environment variables
## Deployment Steps
Follow these steps to deploy safely...
[Reference supporting files in this directory as needed]
```
### Required Frontmatter Fields
* **name**: Unique identifier for the skill (displayed in UI and used for @-mentions)
* **description**: Brief explanation shown to the model to help it decide when to invoke the skill
Examples of valid names: `deploy-to-staging`, `code-review`, `setup-dev-environment`
## Adding Supporting Resources
Place any supporting files in the skill folder alongside `SKILL.md`. These files become available to Cascade when the skill is invoked:
```
.windsurf/skills/deploy-to-production/
├── SKILL.md
├── deployment-checklist.md
├── rollback-procedure.md
└── config-template.yaml
```
## Invoking Skills
### Automatic Invocation
When your request matches a skill's description, Cascade automatically invokes the skill and uses its instructions and resources to complete the task. This is the most common way skills are used—you simply describe what you want to do, and Cascade determines which skills are relevant.
The `description` field in your skill's frontmatter is key: it helps Cascade understand when to invoke the skill. Write descriptions that clearly explain what the skill does and when it should be used.
### Manual Invocation
You can always explicitly activate a skill by typing `@skill-name` in the Cascade input. This is useful when you want to ensure a specific skill is used, or when you want to invoke a skill that might not be automatically triggered by your request.
## Skill Scopes
| Scope | Location | Availability |
| ------------------- | ----------------------------- | ------------------------------------------------- |
| Workspace | `.windsurf/skills/` | Current workspace only. Committed with your repo. |
| Global | `~/.codeium/windsurf/skills/` | All workspaces on your machine. Not committed. |
| System (Enterprise) | OS-specific (see below) | All workspaces, deployed by IT. Read-only. |
For cross-agent compatibility, Devin Desktop also discovers skills in `.agents/skills/` and `~/.agents/skills/`. If you have enabled Claude Code config reading, `.claude/skills/` and `~/.claude/skills/` are scanned as well.
### System-Level Skills (Enterprise)
Enterprise organizations can deploy skills that are available across all workspaces and cannot be modified by end users:
| OS | Path |
| --------- | ----------------------------------------------- |
| macOS | `/Library/Application Support/Windsurf/skills/` |
| Linux/WSL | `/etc/windsurf/skills/` |
| Windows | `C:\ProgramData\Windsurf\skills\` |
Each skill is a subdirectory containing a `SKILL.md` file, just like workspace skills.
## Example Use Cases
### Deployment Workflow
Create a skill with deployment scripts, environment configs, and rollback procedures:
```
.windsurf/skills/deploy-staging/
├── SKILL.md
├── pre-deploy-checks.sh
├── environment-template.env
└── rollback-steps.md
```
### Code Review Guidelines
Include style guides, security checklists, and review templates:
```
.windsurf/skills/code-review/
├── SKILL.md
├── style-guide.md
├── security-checklist.md
└── review-template.md
```
### Testing Procedures
Bundle test templates, coverage requirements, and CI/CD configs:
```
.windsurf/skills/run-tests/
├── SKILL.md
├── test-template.py
├── coverage-config.json
└── ci-workflow.yaml
```
## Best Practices
1. **Write clear descriptions**: The description helps Cascade decide when to invoke the skill. Be specific about what the skill does and when it should be used.
2. **Include relevant resources**: Templates, checklists, and examples make skills more useful. Think about what files would help someone complete the task.
3. **Use descriptive names**: `deploy-to-staging` is better than `deploy1`. Names should clearly indicate what the skill does.
## Skills vs Rules vs Workflows
All three customize Cascade, but they differ in **structure**, **invocation**, and **context cost**:
| | Skills | Rules | Workflows |
| --------------------- | ------------------------------------------------------------------------ | -------------------------------------------------- | ---------------------------------------- |
| **Purpose** | Multi-step procedures with supporting files | Behavioral guidelines ("how to behave") | Prompt templates for repeatable tasks |
| **Structure** | Folder with `SKILL.md` + any resource files | Single `.md` file with frontmatter | Single `.md` file |
| **Invocation** | Model decides (progressive disclosure) or `@mention` | `always_on` / `glob` / `model_decision` / `manual` | **Manual only** via `/slash-command` |
| **In system prompt?** | No — only name + description until invoked | Depends on activation mode | No — listed as available commands |
| **Best for** | Deployments, code review, testing procedures that need scripts/templates | Coding style, project conventions, constraints | One-shot runbooks you trigger explicitly |
**Rule of thumb:** if Cascade should pick it up automatically *and* it needs supporting files, use a Skill. If it's a short behavioral constraint, use a Rule. If you always want to trigger it yourself, use a Workflow.
## Related Documentation
If Skills aren't what you're looking for, check out these other Cascade features:
* **[Workflows](./workflows)** - Automate repetitive tasks with reusable markdown workflows invoked via slash commands
* **[AGENTS.md](./agents-md)** - Provide directory-scoped instructions that automatically apply based on file location
* **[Memories & Rules](./memories)** - Persist context across conversations with auto-generated memories and user-defined rules
# Web and Docs Search
Source: https://docs.devinenterprise.com/desktop/cascade/web-search
Search the web and documentation directly from Cascade using @web and @docs mentions, URL parsing, and real-time context from web pages.
Cascade can now intuitively parse through and chunk up web pages and documentation, providing real-time context to the models. The key way to understand this feature is that Cascade will browse the Internet as a human would.
Our web tools are designed in such a way that gets only the information that is necessary in order to efficiently use your credits.
The [Devin Local agent](/desktop/devin-local) has its own web fetch and search tools, governed by the Devin CLI [permission system](/cli/reference/permissions).
## Overview
To help you better understand how Web Search works, we've recorded a short video covering the key concepts and best practices.
### Quick Start
The fastest way to get started is to activate web search in your Devin Settings in the bottom right corner of the editor. You can activate it a couple of different ways:
1. Ask a question that probably needs the Internet (i.e., "What's new in the latest version of React?").
2. Use `@web` to force a docs search.
3. Use `@docs` to query over a list of docs that we are confident we can read with high quality.
4. Paste a URL into your message.
## Search the web
Cascade can deduce that certain prompts from the user may require a real-time web search to provide the optimal response. In these cases, Cascade will perform a web search and provide the results to the user. This can happen automatically or manually using the `@web` mention.
The **Enable Web Search** admin setting controls whether Cascade can perform web searches on the open Internet. It does not affect Cascade's ability to read specific URLs (see [Reading Pages](#reading-pages) below), which is performed locally on the user's machine.
## Reading Pages
Cascade can read individual pages for things like documentation, blog posts, and GitHub files. The page reads happen entirely on your device within your network so if you're using a VPN you shouldn't have any problems.
Pages are picked up either from web search results, inferred based on the conversation, or from URLs pasted directly into your message.
We break pages up into multiple chunks, very similar to how a human would read a page: for a long page we skim to the section we want then read the text that's relevant. This is how Cascade operates as well.
It's worth noting that not all pages can be parsed. We are actively working on improving the quality of our website reading. If you have specific sites you'd like us to handle better, feel free to file a feature request!
# Workflows
Source: https://docs.devinenterprise.com/desktop/cascade/workflows
Automate repetitive tasks in Cascade with reusable workflows defined as markdown files. Create PR review, deployment, testing, and code formatting 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]`.
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](/desktop/cascade/skills) instead.
Workflows are specific to Cascade — the [Devin Local agent](/desktop/devin-local) does not support them. Migrate your workflows to [skills](/desktop/cascade/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.
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 `+ Workflow` button to create a new Workflow.
Workflows are saved as markdown files within `.windsurf/workflows/` directories 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 `.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 | `.windsurf/workflows/*.md` | 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/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 `.windsurf/workflows/` directory of your current workspace, not necessarily at the git root. 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:
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.
```
Commit using predefined formats and create pull requests with standardized title and descriptions using the appropriate CLI commands.
Automate the installation or updating of project dependencies based on a configuration file (e.g., requirements.txt, package.json).
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 or add unit or end-to-end tests and fix the errors automatically to ensure code quality before committing, merging, or deploying.
Automate the steps to deploy your application to various environments (development, staging, production), including any necessary pre-deployment checks or post-deployment verifications.
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:
**macOS:**
```
/Library/Application Support/Windsurf/workflows/*.md
```
**Linux/WSL:**
```
/etc/windsurf/workflows/*.md
```
**Windows:**
```
C:\ProgramData\Windsurf\workflows\*.md
```
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 `.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.
**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
Source: https://docs.devinenterprise.com/desktop/cascade/worktrees
Automatically set up git worktrees for parallel Cascade tasks
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](/desktop/devin-local) 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.
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.
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](./worktrees#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](./hooks#post_setup_worktree) 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.showWindsurfWorktrees` to `true` in your settings to override this and enable visualizing the worktrees in the SCM Panel.
# Devin Desktop changelog
Source: https://docs.devinenterprise.com/desktop/changelog
Release notes for every Devin Desktop (Windsurf) stable release: new features, improvements, and fixes in each version of the agent-native editor.
**Devin Desktop**
* Faster sidebar for users with thousands of cached sessions: filtering, space grouping, and sorting now only process the sessions actually fetched for display, eliminating multi-second lag after "Reload Window" or while scrolling.
**Devin Local**
* Fixed authentication issues with certain MCP servers, such as self-hosted GitLab servers and older Atlassian MCP instances
**Devin Desktop**
* "Restart to Update" now asks for confirmation when local agents are still working and says how many will be stopped; cloud sessions keep running.
* Settings and Keyboard Shortcuts open as regular editor tabs by default; set `"workbench.editor.useModal": "all"` to keep the modal overlay.
* Fixed a bug with accidentally triggering editor keybindings from the agent chat.
* The old "Plugins" section for IDE extension marketplaces has been renamed to "Extensions".
* Hide Cascade-specific configuration and customization options when Cascade is disabled for your team.
* Visual polish for the Agent Command Center: left-aligned titlebar, unsaved-changes indicator on file tabs, no more Cmd+P open/close flicker, aligned PR icons in Quick Open, full-width sidebar title renaming, and dragged session tabs that pick up their session name.
* Starting an agent in a new worktree that fails now surfaces the git error instead of quietly running in your workspace.
* **Terminal: Create New Terminal in Editor Area** now works inside worktrees.
* Codemaps and MCP configuration files now open from the remote machine when connected over WSL, SSH, or a dev container.
* Teams plan members no longer see quota warning banners they cannot act on.
**Devin Local**
* Devin Local conversations can be shared: **Share Conversation** uploads a sanitized transcript (system prompts and tool definitions dropped, secrets redacted, paths normalized) and copies a team-visible link. Share directly from the actions menu below a completed turn.
* Reverting is reliable mid-turn: revert buttons appear as soon as a prompt is sent and reverting while the agent is working cancels the turn first.
* The Customizations panel has search across every section (skills, subagents, rules, hooks, plugins, MCP servers), a new **Subagents** section, a refresh action for plugins, and an info indicator explaining why an enterprise-required plugin can't be removed.
* Plugins installed from Customizations are added to your personal plugins by default, so they are available in Devin Cloud and on your other devices; choose **Install locally** for a device-only install.
* Permission rules from different levels (enterprise, mode, user, project, subagent) now compose predictably — an explicit `deny:` always wins, "always allow" options only appear when the grant would actually take effect, and denials say which layer denied them.
* Fixed rendering of commands whose output contains non-UTF-8 bytes.
* Ensured `sudo` password prompts can't hang a command.
* Separate each MCP server's logs into its own `MCP: ` output channel.
* Large-file reads through ACP are bounded and paginated instead of repeatedly rereading overflow files. Late terminal flushes now preserve complete output and cannot reopen completed command cards.
**Devin Cloud**
* Session size chips use the same enterprise ACU thresholds as the web app, and auto-continuation billing notices appear inline in the transcript.
* Queued messages can be edited: click the edit button or press ⬆ in an empty input to pull the last queued message back.
* The `+X −Y` diff summary on a collapsed agent group is now clickable and opens a multi-diff editor with just that group's files.
* "Duplicate session" and "send as fork" open the fork in a new tab, keeping the original conversation open.
* "Grant access" on a network access request is disabled with an explanation when an admin owns the session's network policy.
**Fixed**
* Devin Desktop for Windows loads root and intermediate certificates from the Windows certificate store again, so sign-in and other HTTPS requests no longer fail with `self signed certificate in certificate chain` behind a TLS-inspecting proxy or a corporate root CA.
* The `edit`, `write`, `apply_patch`, and `notebook_edit` tools in Devin Local now refuse to write through a symlink, so an approved edit can no longer be redirected to an unexpected file.
**Fixed**
* Product analytics are no longer started before your account status resolves, so telemetry is never collected for accounts that have it turned off.
**Devin Desktop**
* Added a unified notifications setting that posts native OS notifications when any agent session finishes or needs your input.
* Codemaps now open in their own editor tabs in agent window mode (home, generation, and individual codemaps), and codemap @-mentions now work in Devin Local. The Codemaps icon is also back in the activity bar in Agent Command Center mode.
* Select text inside a message transcript and add it to the chat input with the "Add to chat" button or ⌘L / Ctrl+L.
* Added keyboard shortcuts for permission requests (always-allow and reject), with the shortcut hints shown on the buttons and dropdown entries.
* Refreshed the agent window UI: Inter font by default, web-app icon set at web-app sizing, rounded pill session tabs (with state/PR icons), and smarter pane placement so files no longer cover your session tabs.
* Pull request editor tabs now show a state-specific icon (open, draft, merged, or closed), and session-create cards show a Devin mode badge (Fast, Ultra, Fusion).
* Faster syntax highlighting for streaming diffs, and typing in the input no longer lags while other background sessions stream.
* Agent sidebar improvements: right-click context menus, double-click to rename, per-workspace filters/sort/grouping, greyed-out locked (read-only) sessions, a new-session shortcut hint, and sticky grouped spaces that keep their header.
* Signed-out session tabs now show a "You are signed out" sign-in prompt instead of an endless spinner, and logging out cleans up stale session tabs.
* Editing a past message keeps consistent typography, and the edited prompt stays visible at the bottom after a revert.
* Cascade, Devin Local, and every other ACP agent are now unavailable while a workspace is open in Restricted Mode, and hooks no longer load or run there.
* Devin Local customizations has a new Plugins section listing the plugins it loads and the ones your repository, organization, or account offers.
* Remote agent (ACP) sessions can now open a browser preview, the same workflow Cascade has: the agent proxies your local dev server, and the elements and console output you capture land in the agent's message box as pending context. In Devin Desktop the preview opens in the built-in browser pane next to the agent.
* "Open customizations" is now available from the new-tab menu in an agent space and from a Devin Local session's sidebar context menu, and the Cascade panel's `...` menu now only offers the customization surfaces that apply to the agent you have open.
* MCP servers reporting "Needs auth" now show an **Authenticate** button in the Devin Local MCP list, marketplace card, and detail page, which clears the stored OAuth credentials and reruns the browser authorization flow.
* Models marked "Devin Local only" (including every GPT-5.6 variant) now appear disabled in Cascade's model picker with a tooltip pointing you to Devin Local, rather than running degraded in Cascade.
* Closing the last tab in the agent panel with the tab "x" now closes the panel instead of reopening a blank tab, matching Cmd/Ctrl+W.
* Updated the base IDE to VS Code 1.126
**Devin Local**
* New "Devin: Open Cascade Migration Wizard" command opens a guided wizard that chains hooks → skills → memories migration in one flow, with per-item opt-in and dry-run previews.
* Plan mode now works like Cascade's: the agent researches with read-only commands, keeps a persistent Markdown plan file at `~/.devin/plans/plan-.md`, and asks for approval before implementing.
* Worktree sessions now show a **Merge** button to bring their changes back into the workspace, and you can pick an existing worktree from the agent location selector's Local submenu.
* New tabs now default to Devin Local when you haven't chosen a preferred agent (falling back to Cascade if it isn't available), and Local is selectable in the agent selector while it's still connecting.
* `Megaplan` now work in Devin Local, switching the session into Plan mode and prompting the agent to plan first.
* Editable command approvals: click a command in a permission card to edit it before approving, or use the wand action to describe a change in plain language and have a fast model rewrite it for review.
* Queued messages can now be edited before they send, and editing or reverting a prompt preserves file, directory, skill, and terminal @-mentions.
* Added Rules to the @-mention menu so you can pull a manual-trigger rule into a conversation.
* Added a "Duplicate session" action to the response footer to branch off a conversation, and a "Subagents (Preview)" toggle in Devin settings.
* Custom subagents can now be defined as flat `agents/.md` files, and per-agent directories also accept `AGENTS.md`, `agent.md`, and `agents.md`.
* Response statistics now appear reliably after every turn.
* With "Agent Diff Zones" turned off, Devin Local no longer opens edited files in the background, and closing the last Devin Local tab now opens a fresh session instead of closing the panel.
* Fixed streamed `write`/`edit` previews creating stray fragment files when a filename contains underscores.
* Fixed permission rules written with relative globs (e.g. `Read(**/*.pem)`) being pinned to the directory the CLI was launched from, so they now apply under every workspace directory and pick up directories added mid-session.
* Session permission grants and mode switches answered on a subagent's prompt now apply to the whole session, so the root agent and sibling subagents no longer re-prompt for a scope you already granted.
**Devin Cloud**
* Improved performance for loading Devin Cloud sessions.
* Devin Cloud sessions now show the server-side send queue, kept in sync with the web app; Cmd/Ctrl+Enter queues the next message on the server.
* Multi-user (Slack) sessions now show each participant's name above their messages.
* A "Copy link" action was added to cloud session menus.
* A "Remote ACP is disconnected" banner with a Reconnect action now appears when the Cloud connection drops.
**Devin Desktop**
* `@`-mention pills in Cascade now show type-specific icons.
* Restyled the command palette in the Agent Command Center.
* Hiding the status bar by default in the Agent Command Center (set `"workbench.statusBar.visible": true` in user settings to restore it).
* New worktree-backed sessions now open instantly and stay interactive while the worktree is created in the background.
* "View usage" now opens eligible Devin users' personal analytics page directly.
* The `devin.*` settings for gitignore access, completion mode, and auto-continue are now honored.
* Resuming an agent session now uses its original working directory, so Claude sessions started in another folder can be reloaded.
* Fixed a crash when opening the Recent Chat History modal in Cascade.
* On Windows, the auto-updater now clears stale `Devin.exe` processes before applying updates.
**Devin Cloud**
* Long Devin Cloud sessions render, scroll, and type faster and stay responsive while streaming.
* A brief remote-connection drop no longer flashes a "disconnected" banner.
* You can now configure a session's network policy and grant or deny network access requests inline from the chat, without switching to the web app.
**Devin Local**
* Devin Local customizations and the sidebar skills count now span all open workspace folders.
* The Hooks tab in Devin Local Customizations now lists configured hooks with their source and trigger events.
* Added a command to migrate Windsurf hooks into Devin hooks across every workspace folder.
* Added a subtle timeline navigator for Devin Local sessions.
* Added Fast Context support in Devin Local sessions.
Fixes issues with diff viewing in autonomous mode.
**Devin Desktop**
* Added "New session in space" to the session kebab menu.
* Devin Cloud sessions now auto-reconnect when the network returns.
* Images can now be copied from chat via the context menu.
* New users now default to agent mode.
* The agent sidebar now stays visible when sending problems or explain-and-fix to Cascade in agent window mode.
* Fixed branch checkout silently failing to open a worktree.
* Very large sessions no longer crash the window when reading or writing the session event cache.
* The "Scroll to top" button in long sessions now has a solid background so it stays visible in dark themes.
* Orphaned Devin ACP agent processes are now detected and cleaned up on startup, including on Windows.
* Fixed analytics connection failures under TLS-intercepting proxies.
**Devin Local**
* Edits produced in autonomous mode now produce reviewable diffs.
* ACU usage is now shown in the `/usage` command.
* Skill `permissions:` frontmatter now applies to auto-approvals.
* Enterprise login policies are now enforced in the CLI.
* Added a `sandbox.excluded` allow/ask/deny config (user and team settings) to run specific commands outside the sandbox; excluded commands also skip the sandbox proxy environment.
* Fixed command approval parsing for PowerShell `$variable` assignment prefixes.
**Devin Desktop**
* Devin ACU usage is now displayed in the client.
* Fixed settings and extensions migration for Windows system-wide installs.
**CLI and Devin Local**
* On Windows, `bash` now resolves to Git Bash instead of the WSL launcher stub.
* Subagents can now be configured with a default model.
* The MCP registry cache is now warmed during startup, so MCP servers are ready sooner.
* Injected context is no longer included in auto-generated session titles.
* Fixed agent messages over-merging in Claude ACP sessions.
* Added an `attribution` option to the Devin Local [config file](/cli/reference/configuration/config-file); set it to `false` to suppress Devin mentions in commit messages.
Various bug fixes and improvements.
**Fixed**
* Made MCP registry parsing more tolerant of old and inconsistent schemas.
**Fixed**
* Fixed a bug with loading skill files that use alternative fields.
The 3.2 series brings Devin Local enhancements and continued Devin Desktop polish.
**Devin Local**
* Added a [`devin plugin`](/cli/extensibility/plugins/overview) system for extending Devin Local — in preview and opt-in for enterprises.
* Subagents can now call MCP tools directly.
* Teams can enforce terminal allow/deny lists through CLI permission scopes.
**Agent and Editor modes**
* Enabled the `Cmd+.` mode-toggle shortcut from the empty editor welcome panel.
**Other improvements**
* Improved handling for less common MCP server features.
* Removed the Explain sparkle button from the editor breadcrumbs.
The 3.1 series builds on the Devin Desktop rebrand with a smoother Agent/Editor experience, Devin Local improvements, and continued polish.
**Agent and Editor modes**
* Added the Agent/Editor switch to the collapsed-sidebar titlebar, and unified the search icon to open agent search.
* Kept the sidebar toggle in place when opening and closing the drawer.
* Smoothed switching between Agent and Editor modes so auxiliary windows no longer close and restore.
**Devin Local**
* Renamed the "Devin CLI" settings section to "Devin Local".
* Added a notification when Devin Local agent sign-in fails.
* Updated the bundled Devin Local agent to [v2026.5.26-8](/cli/changelog/stable#2026-5-26-8).
**Other improvements**
* Added `.devinignore` support alongside `.windsurfignore` and `.codeiumignore`.
* Settings and MCP marketplace pages now scroll across the full panel width and keep content centered on wide panels.
* Hardened migration from Windsurf on Windows to preserve shortcut icon.
* Improved handling of file context in Devin Local agent
* Increased proxy authentication timeout
* Fixed issues with some stdio MCP servers on Windows
### Enterprise
* Simplified model picker pricing view for select enterprise customers
Added a new command for Devin Desktop to rerun the migration from Windsurf. This will reset Devin Desktop settings and give you a second chance to import extensions and other settings from Windsurf. The "Reset migration from Windsurf" command can be found in the command palette.
If you are logged out of your account after migrating from Windsurf, we recommend opening the command palette via ctrl+shift+p (cmd+shift+p on macOS) and running the reset migration command.
Windsurf is now [Devin Desktop](https://devin.ai/blog/windsurf-is-now-devin-desktop).
# Bug fixes and improvements
## General
* Increased remote server startup timeout from 2.5s to 6s.
## Devin Local
This release updates the bundled Devin Local agent to 2026.5.26. See the [changelog](https://cli.devin.ai/docs/changelog/stable#2026-5-26-0) for the full list of changes.
* Devin Local is now aware of the files you have open in the editor as part of its context.
* When prompted for an MCP tool permission in Devin Local, two additional server-level options are now offered: approve all tools on the server for the current session, or permanently.
* Repaired hooks for Devin Local to allow blocking user prompts.
* Improved plan mode in Devin Local to work in the OS sandbox.
* "Always Allow" permission grants in Devin Local now persist across sessions.
* Image attachments in Devin Local now show the correct warning when the selected model does not support images.
# Bug Fixes and Improvements
* Fixed availability issues with swe-check model for some users.
* Improved terminal processing performance
* Restored conversation sharing
* Repaired path resolution for the Devin local agent on WSL
## Devin Review & Quick Review
All Windsurf IDE users now have access to [Devin Review](https://app.devin.ai/review) and [Quick Review](https://docs.windsurf.com/windsurf/quick-review) with your existing subscription.
* Devin Review is available for all self-serve users, with a 2 week free trial.
* Enterprise users can only use Devin Review with a Cognition platform agreement.
## Agent Command Center
* Added list display option for the agent inbox
* Improved sessions sidebar sorting and filtering
* Performance improvements for loading and switching sessions
## Windows updates
We have fixed a bug preventing updates for some users on Windows. To upgrade to this version, you may need to:
* Wait for the update to download.
* Once it is downloaded, open Windows Task Manager and close all `devin.exe` processes
* Proceed with installing the update and restarting Windsurf
## Bug fixes and improvements
* Fixed bugs with some MCP servers
* Improved reliability of Devin Local agent
# Bug Fixes & Improvements
## Bug Fixes
* Fixed a crash that could occur when switching between Cascade conversations
* Fixed an authentication issue that could prevent Devin Cloud sessions from starting
* Fixed an issue where responses to agent questions were not sent correctly
# Devin for Terminal
Devin is now available [for Terminal](https://devin.ai/terminal). All Windsurf users can use this new CLI agent with your existing subscription.
* **Runs on your machine** — Optimized for interactive work, with full access to your codebase, tools, and environment.
* **Hand off to the cloud** — Seamless hand off to Devin in the cloud, with its own VM, testing, video recordings, autofix and more. Come back to a finished PR.
* **Multi-model** — All of your favorite frontier models in one place, including Opus 4.7, GPT-5.5, and SWE-1.6.
* **Fast** — Written in Rust and so performant that the binary can run on an original VT100.
## Devin Agent in Windsurf
You can also enable the new Devin Local agent in Windsurf. This is the same agent harness used on the terminal and sessions can be accessed from both Windsurf and the CLI.
In our testing, it's up to 30% more token-efficient than the existing Cascade agent.
## Additional Changes
* Improved search subtitle layout during streaming
* Fixed file drag-and-drop in agent window Cascade tabs
* Fixed Go to Line/Column keybinding on Windows/Linux (Ctrl+Shift+G)
* Added support for server-driven extension deny lists
* Stability and performance improvements
# Bug Fixes and Improvements
* Fixed OAuth authentication issues for some MCP servers
# Bug Fixes and Improvements
* Fixed a regression with OAuth integration for some MCP servers
* Improved reliability of Devin Cloud connections in Windsurf
# Bug Fixes and Improvements
* Various bug fixes and performance improvements
# Bug Fixes and Improvements
* Various bug fixes and performance improvements for improving Windsurf 2.0 auth experience.
* Fixed bug with spawning Terminal sessions on Windows
# Windsurf 2.0
Read the full announcement [here](https://windsurf.com/blog/windsurf-2-0).
## Devin in Windsurf
* Devin cloud agent available directly inside Windsurf, included with every self-serve plan
* Delegate tasks from a local session to Devin with one click; Devin runs on its own VM
* Review Devin changes and test results without leaving the editor
* Billing is based on your existing quota and extra usage, with up to 50 USD in extra usage added for launching your first Devin Cloud session.
**Note:** Access to Devin Cloud is rolling out gradually. If you don't see it yet, try logging out of the website and IDE then logging back in.
Devin Cloud is disabled by default for enterprise accounts. Enterprise admins should enable Devin access in their organization settings if they have already purchased Cognition Platform.
## Agent Command Center
* New Kanban-style view showing all local and cloud agent sessions, organized by status
* Group agent sessions, PRs, files, and context into task-level Spaces
* Switch between Spaces to switch between tasks
## Additional Changes
* Refined Windsurf Browser with toolbar integration and Cascade tool for reading page contents
* Sped up initial load times for the Cascade sidebar
* Improved .gitignore and .codeiumignore handling across the product
* Stability improvements for remote extensions (WSL, SSH, Dev Containers)
* Performance improvements for typing in large active diff zones
## Adaptive Fix
We fixed a bug with the adaptive model router which prevented switching models after the first request.
All users who encountered the bug have had quota reset and overage restored.
## Adaptive Model Visibility
We've improved the visibility of the adaptive model in the model picker.
# Introducing Adaptive
We've made several model packaging changes, with more info [here](http://windsurf.com/blog/windsurf-adaptive).
## Adaptive Model Router
A new **Adaptive** model option is now available in the model picker. Adaptive intelligently selects the best model for each task, helping you make your quota last longer by avoiding overuse of premium models.
* **Availability**: Now available to all self-serve users on Pro, Max, and Teams plans.
* **Dynamic model selection** - Automatically chooses the right underlying model for your task while drawing down quota at a fixed per-token rate.
* **Extra usage promo** - Beyond your quota, extra usage is offered at 0.50 USD per 1M input tokens, 2.00 USD per 1M output tokens, and 0.10 USD per 1M cache read tokens for the next 2 weeks.
## Updated Model Picker with Pricing Context
The model picker now shows token pricing information directly, so you can see the exact rate extra usage is billed at.
* **Token pricing display** - Per-model input, output, and cache read token rates visible in the picker.
* **Prompt cache timer** - A new prompt cache timer is integrated into the context window indicator to help you track caching status.
* **Token counts in response cards** - Response cards after messages now include token counts so you can understand exactly how each message cost was calculated.
# Quota Billing
* Added support for the new quota billing system
* Daily and Weekly quota usage is now displayed directly in the IDE
# Bug Fixes and Improvements
* Fix build for Mac x64
# Bug Fixes and Improvements
* Various bug fixes and performance improvements
# Bug Fixes and Improvements
* Fix for Apple M5
## Cascade
* Fix dangling Diff Zones related to Jupyter Notebooks
* Improve Jupyter Notebook performance when running on WSL
* Improve Cascade UI rendering performance
* Fix Cascade agent panel crashes under certain conditions
* Improve notifications for model price changes
* Add support for loading SKILL.md files from the `.windsurf/skills/` directory
* Fix `AGENTS.md` being ignored by Cascade in specific cases
## MCP
* Add support for [system-level Skill definitions](https://docs.windsurf.com/windsurf/cascade/skills#system-level-skills-enterprise) via MDM-managed configs for Enterprise
* Improve context management for MCP servers
## Stability & Performance
* Improve autocomplete error handling and performance
* Improve SSH & Remote performance
# Bug Fixes and Improvements
* Fix extension installation version selection
## New Model Picker
We introduced a new model picker that groups models by family and adds a hovercard with toggles for
specific variants, like reasoning effort and speed.
Separately, we also added the ability to pin models.
## Cascade Improvements
* Added `POST_CASCADE_RESPONSE_WITH_TRANSCRIPT` cascade hook
* Added Cascade hooks configuration visibility on team settings page
* Reduced the priority of Git commits in @ mention search
* Added a `devin.cascade.readClaudeCodeConfig` flag to disable reading Claude configuration
## MCP Improvements
* Added an MCP Refresh button
* Auto-trigger OAuth login when adding HTTP/SSE MCP servers
* Fix bugs with parsing on Windows and startup
## Platform Improvements
* Merged changes from VS Code 1.108
* Improved startup reliability for Cascade
* Fixed Windows update initialization path that could block updates
* Released binaries for Linux ARM64
# Bug Fixes and Improvements
* Fix compatibility with GitHub Pull Requests extension
# Bug Fixes and Improvements
* Fix for self-updating on Windows
* Fix for macOS UI flickering
# Cascade Improvements
* Plan Mode now supports automatic switching back to Code Mode when you start implementing a plan
* Added support for reading skills from the `.agents/skills` directory
* Tracking triggered rules in the `post_cascade_response` hook via a new `rules_applied` field
* Diff zones will now automatically close on commit
# Linux ARM64 Support
* Full Linux ARM64 client support with deb and rpm packaging
# Enterprise & Team Improvements
* Cloud configuration for Cascade Hooks is now available for enterprise teams via the cloud dashboard
* Support for Devin service key authentication
# Bug Fixes and Improvements
* Fixes for `post_write_code` hooks to handle all code editing tool formats
* Fixes and improvements for MCP server resource loading
* Fixed osascript privilege escalation being incorrectly triggered on Linux for shell command installation
* Addressed multiple memory leaks
* Improved RTL language rendering in todo lists
# New Models
* GPT-5.3-Codex-Spark is now available in Arena Mode's Fast Arena and Hybrid Arena battle groups
# Claude Opus 4.6 (fast mode)
Claude Opus 4.6 (fast mode) is now available in Windsurf in research preview with limited-time promotional pricing for self-serve users until Feb 16:
* **No thinking:** 10x credits
* **With thinking:** 12x credits
Opus 4.6 (fast mode) has the same intelligence as Opus 4.6 but with up to 2.5x higher output speeds.
# Claude Opus 4.6
Claude Opus 4.6 is now available in Windsurf with limited-time promotional pricing for self-serve users:
* **No thinking:** 2x credits
* **With thinking:** 3x credits
Opus 4.6 is available in Arena Mode's Frontier Arena and Hybrid Arena. Try it head-to-head against other frontier models to see how it performs on your real-world tasks.
* Various bug fixes and performance improvements
* Released Tab v2 model selector to all users
# Bug Fixes and Improvements
* Fix issues with Arena Mode Battle Groups
# Bug Fixes and Improvements
* Improve UI styling for announcement popups and notifications
* Close model picker when selecting a battle group
# Wave 14: Arena Mode
Arena Mode brings side-by-side model comparison directly into your IDE, plus Plan Mode for smarter task planning.
## Arena Mode
Run two Cascade agents side-by-side with hidden model identities and vote on which performs better. Arena Mode lets you discover which models actually work best for *your* workflow, codebase, and tasks—not just what benchmarks or influencers say.
* **Battle Groups**: Choose specific models to compare or let Windsurf randomly select from curated groups like "fast models" vs "smart models"
* **Personal & Global Leaderboards**: Your votes contribute to both a personal leaderboard (your preferences) and a global one (across all Windsurf users)
* **Sync or Branch**: Send followup prompts to both agents simultaneously, or branch and explore different paths individually
To get started, select the new **Arena** tab in the model picker. All battle groups are free for the first week for paid users.
## Plan Mode
Plan Mode is a new Cascade mode alongside Code and Ask. Use it to create detailed implementation plans before diving into code.
**Pro tip**: Type `megaplan` in the Cascade input box to trigger an advanced form that asks clarifying questions to create a more aligned, comprehensive plan.
# Bug Fixes and Improvements
* Admins can now set a default model that applies to all team members when they first open Windsurf
* Various bug fixes and performance improvements
# Bug Fixes and Improvements
* Fix bug with permanently disconnected cascades
# Bug Fixes
* Fixes commit message generation and codemaps suggestions
# Enterprise Features
* Enterprise admins can now specify organization-wide allow and deny lists for command auto-execution. [Learn more](https://docs.windsurf.com/windsurf/terminal#team-wide-command-lists-teams-&-enterprise)
# Bug Fixes and Improvements
* Bug fixes and performance improvements for diff zones
* Improved overall stability and reliability
* Added [`post_setup_worktree`](https://docs.windsurf.com/windsurf/cascade/worktrees#setup-hook) hook for initializing worktrees in Cascade
# Bug Fixes and Improvements
* Improvements to GPT-5.2-Codex harness
* Admins can now manage Windsurf restrictions via Windows Group Policy
# GPT-5.2-Codex
Adds support for GPT-5.2-Codex with four reasoning efforts (low, medium, high, and xhigh).
GPT-5.2-Codex is OpenAI's latest model designed for agentic coding. It excels at working in large codebases over long sessions.
For most tasks, we recommend using the medium reasoning effort.
# Bug Fixes and Improvements
* Various bug fixes and performance improvements
* Improved stability and reliability
# New Features and Improvements
* Windsurf now supports [Agent Skills](https://docs.windsurf.com/windsurf/cascade/skills) for Cascade.
# Bug Fixes and Improvements
* Various bug fixes and performance improvements
* Improved stability and reliability
# Gemini 3 Flash
Gemini 3 Flash is now available for all users. This model combines Gemini 3 Pro-grade reasoning with Flash-level speed and efficiency, making it ideal for agentic workflows and coding tasks.
* **Blazing Fast Responses**: Experience near-instant feedback with 3x faster performance than previous generations, perfect for iterative development compared to Gemini 3 Pro
* **Superior Coding Intelligence**: Outperforms even Pro-tier models on key coding benchmarks (78% on SWE-bench Verified), providing more accurate code generation and debugging
* **Deep Multimodal Understanding**: Easily process complex video, data extraction, and visual Q\&A tasks with frontier-level reasoning
# Bug Fixes and Improvements
* Various bug fixes and performance improvements
* Tab fixes and improvements
# Wave 13: Merry Shipmas
Wave 13 brings first-class support for parallel, multi-agent sessions in Windsurf, along with Git worktrees, side-by-side Cascade panes, and a dedicated terminal profile for more reliable agent execution.
## SWE-1.5 Free
Our near-frontier model, SWE-1.5, is now available for free to all users for the next 3 months. SWE-1.5 Free has the full intelligence of SWE-1.5, with the same coding performance on SWE-Bench-Pro, but delivered at standard throughput speeds. The original variant of SWE-1.5 hosted on Cerebras will continue to be available for paid users. SWE-1.5 Free will replace SWE-1 as the default model in Windsurf starting today.
## Git Worktree Support
Windsurf now supports Git worktrees, letting you spawn multiple Cascade sessions in the same repository without conflicts. Git worktrees check out different branches into separate directories while sharing the same Git history.
## Multi-Cascade Panes & Tabs
You can already run multiple Cascade sessions in Windsurf at the same time. Now, you can view and interact with them in separate panes and tabs within the same window. This lets you monitor progress and compare outputs of sessions side-by-side, or even turn Windsurf into a big Cascade dashboard.
## Cascade Dedicated Terminal (Beta)
Windsurf introduces a new approach for letting agents execute terminal commands. Instead of your default shell, Cascade will now run commands in a dedicated zsh shell specifically configured for reliability. The Cascade Dedicated Terminal can use the environment variables you set in your .zshrc configuration and is interactive, which means you can answer any prompts from shell scripts without having to break your flow. This should improve the reliability and speed of shell commands, especially for users with complicated prompts (e.g., powerlevel10k).
In this version, the Cascade Dedicated Terminal will be opt-in for Windsurf Stable on macOS. If you are experiencing issues with the older legacy terminal, we recommend switching to the new terminal early. We expect to make this feature the default in the future, while maintaining the legacy terminal extension for backwards compatibility purposes. You can opt-in in the Windsurf User Settings -> Disable Windsurf Legacy Terminal Profile.
## Context Window Indicator
When a model's context window grows too long, earlier context can be dropped without warning and performance can degrade. Cascade already extends the window by occasionally summarizing messages and clearing history. This release adds a visual indicator to see how much of your context window is currently in use, helping you anticipate limits and decide when to start a new session.
## Cascade Hooks
Execute custom commands at key points during Cascade's workflow, including on model response for auditing purposes.
## System-level Rules & Workflows
Enterprises can deploy rules and workflows via MDM policies, allowing organizations to place rules and workflows files on users' machines.
# Bug Fixes and Improvements
* Enhanced diff zone behavior with configurable scroll-to-next-hunk settings (default off)
* Preserved colors and styling in Cascade terminal output
* Multiple fixes to the Model Context Protocol implementation
* Supports lowering permissions for Cascade's Web Fetch tool
* Fix race condition in the dedicated terminal implementation
* Support force killing commands in the dedicated terminal
* Improved markdown completion
* Fix opening old Cascade diffs
# Features
Added a new "Promo" label to LLM models that are newly available or have special discount pricing
# Bug fixes and improvements
## Agents & Tool Execution
* Fixed Command-I functionality
* Fixed Ctrl+C during tool execution not working properly
* Fixed Go (fallback) processes not being killed properly
* Fixed handling of parallel tool call errors
* Improved MCP tool call visibility (show tool name, args, etc)
* Fixed fallback diff handling for nonexistent files in code actions
## UI & Rendering
* Fixed incorrect indentation from code blocks in terminal rendering
* Fixed nested lists not rendering on new line in terminal markdown
* Fixed content spacing issues
* Fixed streaming flashes
* Enhanced code block file path display to hide line numbers for whole files
* Improved citation and language parsing in code blocks with a more robust regex pattern
* Updated the UI for code block title bars to properly handle long paths with truncation
* Improved the auto-run command menu interface and its display logic
* Added loading indicators when thinking or during long running operations
* Fix opening old Cascade diffs
## Platform & Messaging
* Fixed rate limit error message to say "no credits were used" instead of "credits have been refunded"
* Fixed continuously rechecking for updates on macOS
* Added a user-facing message when API providers are exhausted
## Workspace & Onboarding
* Allowed clicking items in the Windsurf onboarding pane
* Respect gitignore patterns in the workspace directory tree
# Patch Fixes and Improvements
* Reduce occurrence of "prompt is too long" errors
* Request all supported scopes if no scopes are provided in MCP OAuth config
# GPT-5.2
GPT-5.2 is now available in Windsurf. This model will be available for 0x credits in Windsurf (to paid users) for a limited time.
GPT-5.2 represents the biggest leap for GPT models in agentic coding since GPT-5 and is a SOTA coding model in its price range. The version bump undersells the jump in intelligence. We\`re excited to make it the default across Windsurf and several core Devin workloads. - Jeff Wang, CEO of Windsurf
Download the [latest version on Windsurf](https://windsurf.com/download/editor) to try it out!
# Bug fixes and improvements
* General Windsurf stability and performance improvements
* General Tab (Supercomplete) improvements and stability
* Fixes issues with Cascade running commands that could not be cancelled during certain long-running processes
# Features & Tools
## Cascade Hooks on User Prompts
Users can now configure Cascade Hooks on user prompts for logging all user prompts and blocking policy-violating prompts.
## MCP Servers
* Added support for GitLab remote MCP.
* Added OAuth support for GitHub remote MCP.
* Fixed an issue where every MCP would reauth on opening Windsurf.
* Added support for [MCP prompts](https://modelcontextprotocol.io/docs/concepts/prompts)
* Added toggles to enable/disable MCPs in the Cascade header
# Diff Zones
* Fixes issues with diff zones not rendering correctly or jumping to the end of a file when editing
# Tab (Supercomplete)
* Improves reliability of Tab autocomplete
* Makes Tab more responsive and faster in the appropiate circumstances
# Bug fixes and improvements
* General stability and performance improvements
* Fixes issues with login timing out too quickly during onboarding
# GPT-5.1-Codex Max
Introducing GPT-5.1-Codex Max in three reasoning tiers (Low, Medium, High). Low variant available at no cost to paid users for a limited time.
# Patch Fixes and Improvements
* General bug fixes and improvements.
# Claude Opus 4.5
You can now use Claude Opus 4.5 in Windsurf!
Opus 4.5 is the most capable model in Windsurf yet and is now available at Sonnet pricing for a limited time (2x credits compared to 20x for Opus 4.1).
This model is available to all paid Windsurf subscribers.
# AI Models
## Gemini 3 Pro
* Resolved an issue where Gemini 3 Pro caused internal Cascade errors for some users.
## SWE-1.5
* Fixed notebook tool functionality for SWE-1.5.
* Addressed an issue where SWE-1.5 would unexpectedly stop or return "No response requested".
## Sonnet 4.5
* Added support for Sonnet 4.5 with a 1M token context window.
* Reduced the frequency of unnecessary Markdown file creation by Sonnet 4.5.
## GPT-5.1 Codex and Codex Mini
* Added support for GPT-5.1 Codex and Codex Mini with low reasoning effort configuration.
# Features & Tools
## Codemaps
* Improved reliability of saving and retrieving Codemaps.
* Fixed Codemap sorting and increased the limit of visible open Codemaps.
* Resolved issues with mentioning Codemaps in Cascade.
## MCP Servers
* Fixed scope handling and OAuth authentication flows for various MCP servers.
* Resolved issues preventing installation of new MCP servers.
* Added support for handling embedded resource content in tool call responses.
## Tab Completion
* Improved latency, responsiveness, and accuracy of autocomplete.
Note: The Autocomplete setting has been removed as it was a legacy option that had no effect. Windsurf's Tab autocomplete feature is powered by Supercomplete.
## Vibe and Replace
* Fixed reliability issues with Vibe and Replace.
## Fast Context
* Added support for `.codeiumignore` and `.gitignore` for Fast Context.
# General Improvements
* Fixed various UI alignment issues with icons and styles.
* General performance and stability improvements.
* Fixed issues with the file search tool.
# Gemini 3 Pro Preview
* You can now use Gemini 3 Pro (Low and High) in Windsurf! This is a preview release that is available to paid Trial, Pro, and Teams subscribers and will soon be extended to Enterprise users as well.
# GPT-5.1 Priority Mode
* Added priority processing support for GPT-5.1 models, providing guaranteed low-latency responses for faster (\~50 tokens/sec), more reliable AI assistance.
* Priority processing costs 2x the standard rate, which will be reflected in the Windsurf credit system.
# Patch Fixes and Improvements
* Fixed tool call calling issues for GPT-5.1-Codex and GPT-5.1-Codex Mini models
# GPT-5.1 and GPT-5.1-Codex
GPT-5.1 and GPT-5.1-Codex are now available in Windsurf. GPT-5.1 will become the default model in Windsurf for one week, and paid users get free access during this period.
GPT-5.1 and GPT-5.1-Codex deliver a solid upgrade from GPT-5 for agentic coding workflows. They're noticeably better at understanding what you're asking for and working with you to get it done. The new variable thinking feature dynamically adjusts reasoning depth—providing quick responses for simple tasks and more thoughtful analysis when complexity demands it.
# Patch Fixes and Improvements
## MCP Improvements
* **Loading state indicators**: Show loading state per installed MCP to improve visibility during initialization.
* **Refresh only edited MCPs**: When `mcp_config.json` is modified, only the affected MCP server instance is initialized/refreshed; no other instances are refreshed.
* **Increased initialization timeout**: MCP initialization timeout increased to 60s.
* **Refresh button for error states**: Show refresh button for MCPs in error state to allow manual recovery.
## Cascade Hooks
* **Cascade Hooks feature**: New Cascade Hooks feature available to all tiers.
* **Documentation**: See [Cascade Hooks docs](https://docs.windsurf.com/windsurf/cascade/hooks) for available hooks and usage examples.
## SWE 1.5 Image Support
* **Image understanding**: SWE 1.5 now supports image understanding, enabling visual content analysis.
## Removed Features
* **Knowledge Base**: Removed the Knowledge Base feature.
## Bug Fixes
* **Vim extension typing lag**: Fixed bug causing typing lag when Vim extension is enabled.
* **PowerShell + Turbo Mode**: Fixed an issue where PowerShell was not running commands when Turbo Mode is enabled.
## Shortcuts
* **Attach current file to Cascade**: New shortcut `Option/Alt+Cmd+L` when in an editor to attach the current file to Cascade.
# Features
## Expanded Codemaps
Codemaps now include powerful new capabilities:
* **Chat with map** - Interact directly with your codebase visualizations
* **Mermaid diagrams** - Generate visual diagrams within maps for better code understanding
* **Cascade suggestions** - Get AI-powered suggestions directly in your maps
* **Map option in chat/edit nudges** - Easily create maps from chat and edit interactions
* **Smart mode option** - Enhanced intelligent assistance when working with maps
## Cascade Summarization Fix
Improved Cascade summarization to better handle longer conversations. Previously, summaries could be too aggressive and drop important context. Now maintains better continuity across long sessions with multiple file changes and user messages.
## MCP Enhancements
* **Path component handling** - Improved support for MCP URLs with path components (e.g., Smithery MCPs)
* **OAuth flow improvements** - Better OAuth flow for streamable HTTP MCPs
# Bug fixes and improvements
## Performance Improvements
* **Sticky scroll lag fixes** - Resolved lag spikes when using sticky scroll with Vim bindings
* **General slowness fixes** - Addressed performance issues caused by VSCode OSS update
* **Terminal rendering optimization** - Fixed rendering loop that caused 500ms+ delays on first terminal open
## Terminal Fixes
* **PowerShell improvements** - Fixed Windows terminal integration edge cases where commands would appear stuck
* **Shell theme compatibility** - Resolved edge cases with custom shell themes (zsh, fish, powerlevel10k, etc.) that could cause Windsurf to break or show stuck commands
## Editor Stability
* **Terminal freeze fix** - Fixed an issue where the editor would freeze when opening the terminal
* **CMD+J fix** - Resolved layout thrashing issue when opening terminal pane with CMD+J
# Falcon Alpha
You can now try a new stealth model in Windsurf: Falcon Alpha. Falcon Alpha is a powerful agentic model designed for speed. We're excited to hear what you build with it!
# Patch Fixes and Improvements
* Various performance improvements and bug fixes.
# Patch Fixes and Improvements
* Support and fixes for AGENTS.md
* Improvements and bug fixes for Codemaps.
* Improvements to Fast Context. Enterprises can opt in using the Windsurf Team Settings. Users can toggle Fast Context automatically using "CMD/Ctrl + Enter" on the first message in a chat.
* New auto-linting behavior that speeds up Cascade.
* Fix for MCP Marketplace not respecting team allowlist options.
* Fixes for Jupyter Notebook tool.
* Fixes for Memories, Rules, and Workflows.
* General bug fixes and improvements.
* Performance optimizations and stability enhancements.
# Dependencies
* Updated Code OSS to version 1.105.0 (Electron: 37.6.0, Chromium: 138.0.7204.251)
# Patch Fixes
* Resolved issues affecting SSH remote connections with high resource usage.
* Fix certain models seeing increased error rates on editing files.
* Improved diagnostics for third party extensions.
# New Features
* **Fast Context**: Introduced Fast Context subagent powered by SWE-grep, enabling agents to find relevant code context up to 20x faster with >2,800 tokens per second throughput.
Learn more on our [blog](https://cognition.com/blog/swe-grep).
# Bug Fixes
* Fixed issues with WSL compatibility.
* Fixed bugs in Workflows and Rules UI.
* Various stability improvements and minor bug fixes.
# Patch Fixes
* Fixes issue with custom MCP servers not being displayed correctly in the new MCP panel.
* Improvements and bug fixes for the beta Codemaps feature.
* Fixes issue where some bash commands would get stuck.
* Fixes issue where certain models couldn't create or edit Jupyter notebooks.
* General bug fixes and improvements.
# Codemaps
* Codemaps is a beta feature for codebase understanding and navigation. Open the codemaps pane to try it out!
# Patch Fixes
* Fixes to Cascade to reduce internal errors.
* Fixes to Cascade not seeing terminal output.
* Various other bug fixes and stability improvements.
# Claude Sonnet 4.5
* Claude Sonnet 4.5 is now available
# Patch Fixes
* Fix using MCP tools with certain models.
* Fixes to terminal issues on Windows.
# Patch Fixes
* Fix to Cascade slowness issues
# GPT-5-Codex is now in Windsurf!
GPT-5-Codex is now available for free (0x credits) for a limited time for paid users!
Free users can use GPT-5-Codex as well for 0.5x credits.
# Cascade Improvements
## Queued messages
* Users can now add follow-up messages to Cascade while it is working, and Cascade will process them in order after the current task is complete.
## Mermaid diagram support
* Cascade now renders mermaid diagrams in the conversation.
# Deprecation
* Windsurf Browser is now deprecated. We plan to refactor and release a replacement feature in the coming months. Please use [Previews](https://docs.windsurf.com/windsurf/previews) instead.
# Patch Fixes
* Made improvements to the sign up onboarding flow.
* Various bug fixes and stability improvements.
# Patch Fixes
* Minor improvements and bug fixes
# Patch Fixes
* Minor improvements and bug fixes
# Patch Fixes
* Minor improvements and bug fixes
* Memory improvements
# Patch Fixes
* Minor improvements and bug fixes
# Devin features in Windsurf, stability improvements, and a brand new UI
* **Stability & Performance**: Over 100 bug fixes and reliability improvements.
* **DeepWiki in Windsurf**: Hover over code symbols for intelligent DeepWiki-powered documentation.
* **Vibe and Replace**: AI-powered find and replace functionality. Apply intelligent transformations to multiple code matches.
* **Cascade Agent Improvements**: Automatic planning mode with no manual toggles required. Revamped tools with more accurate edits. Enhanced code exploration leveraging long context models.
* **Tab Autocomplete**: New system with more frequent and smarter suggestions.
* **UI Redesign**: All-new Chat, Cascade, and home screen panels.
* **Dev Containers**: Support for development containers via remote SSH access.
# GPT-5 Available
Windsurf now supports the GPT-5 suite of models including GPT-5 (low reasoning), GPT-5 (medium reasoning), and GPT-5 (high reasoning). They are available for free for a limited time for paying users!
# Patch Fixes
* Minor improvements and bug fixes
# Patch Fixes
* Minor improvements and bug fixes
# Patch Fixes
* Minor improvements and bug fixes
# Kimi K2 Available
Windsurf now supports Kimi K2 model which costs 0.5 credits per prompt.
# Speak to Cascade
## Voice
* Users can now speak into the chat rather than having to type things out.
## @-mentioning conversations
* @-mention the first conversation so Cascade has full context of it as it goes to write tests for you.
## Deeper Browser integration
* Chat with Cascade about tabs that are open in the Browser using @-mentions
## JetBrains improvements
* Planning Mode, Workflows, and file-based Rules are now available for Cascade on JetBrains
## Improvements
* Now you can @-mention terminal in Cascade.
* You can turn on the Auto-Continue setting to have Cascade automatically continue its response if it hits a limit.
* Support for more MCP servers with easier and more secure authentication by integrating the new Streamable HTTP transport (replaces SSE) and MCP authentication (replaces access tokens or API keys in the config).
* Important for enterprise customers who use Windsurf across lots of repos. Now, you can enforce ignore rules across all repositories by placing .codeiumignore in the \~/.codeium/ folder
# Linux Fixes
* Fixes to RHEL 8 Support
# Cascade Improvements
* Improvements to Cascade reliability
# Patch Fixes
* Minor improvements and bug fixes
# Browser Fixes
* Fixed unauthenticated missing CSRF token
# Patch Fixes
* Fixed API Pricing labels in the model selector
* Fixed bugs related to planning mode
* Fixed some behavior around conversation button dropdown
# Windsurf Browser
* Ability to share browser context with Windsurf
* Share code blocks, selected text, web page elements, screenshots, and console logs
* Send blocks directly to Cascade
## Fixes
* Fixed writing to plan.md files for Enterprise users
# Planning Mode
* Send messages to Cascade in Planning Mode, a setting that will let Cascade plan before making edits
* Cascade will create a plan.md file of the actions it plans to take before taking action
* The plan is user-editable, and Cascade will pick up on user changes
## Terminal Improvements
* Native terminal in Cascade panel
* Terminal now accepts user inputs in the Cascade panel
## Legacy Mode Removal
* Legacy mode has been removed, leaving Write and Chat mode
## Improvements
* Icons in @-mentions
* Theme-aware codeblocks with refreshed design
* Improvements to `.codeiumignore`
* New menu to open previous conversations to quickly switch conversations
# Patch Fixes
* Fixed Cascade and terminal integration issues for Mac and Linux users
* Merged upstream changes from VS Code 1.99.3
* Improvements to import behavior during onboarding
* Fixed shadow with the App Icon on Mac
# Bring your Own Anthropic Key
## BYOK (Anthropic Key)
* You can now bring your own API Key from Anthropic to use the Claude 4 Sonnet, Claude 4 Sonnet (Thinking), Claude 4 Opus, and Claude 4 Opus (Thinking) models in Cascade
* To use BYOK, go to [provide API keys](https://windsurf.com/subscription/provider-api-keys) and input your key
* Once entered, go back to Windsurf and reload the window. You should now be able to use the new models
* This is only available for Free and Pro users at this time
# SWE-1 Improvements
* Adds multi-modal (image) support to SWE-1
# New Family of SWE-1 Models
## SWE-1
* New SWE-1 Model made by Windsurf is available in Cascade
* SWE-1 is a new model with frontier model-level capabilities
* Free for a limited time for Pro Users
## SWE-1-lite
* SWE-1-lite is a new, far more capable model replacing Cascade Base
* Free to use for all plans and tiers
## SWE-1-mini
* SWE-1-Mini is our revamped model for tab completion in Windsurf
## Misc
* Few memory leak bug fixes
* Various fixes to Cascade Plugin Panel
# Cascade Customization
## Cascade UX Improvements
* Redesigned Model Selector
* Continue button when reaching individual tool call limit
* Opening conversations will now open the associated workspace
* Hunk accept/reject widget now has a compact mode to cover less code
* Improvements to commit message generation quality
* Commit message generation reads from global rules as context
* Ability to edit proposed terminal command
## Custom Workflows
* You can create “workflows”, saved prompts that Cascade can follow
* Workflows can be invoked via slash command
* Cascade can help create and edit workflows
* Workflow files are saved in the workspace, under .windsurf/workflows
## File-Based Rules
* You can create granular rules files that are always on, @mention-able, requested by Cascade, or attached to file globs
* Rules files are saved in the workspace, under .windsurf/rules
## Simultaneous Cascades
* Allow Cascade to keep running when switching to another conversation
* Add support for switching between conversations via a dropdown menu or keyboard shortcuts
## Cascade Plugins
* New panel in Cascade for managing MCP Servers
* Easier one-click uninstall and install
* Easier search
* MCP now has MCP resources and multimodel responses
* More MCP Server options coming soon
## Fixes
* Fixed tool call errors for users with disabled telemetry
* Fixed crashes around workspace conversation
# Teams Features
## Teams: Windsurf Reviews
* Team admins can install a Github app for code review and PR title/description edits
* Available to Teams and Enterprise SAAS for 500 reviews/month
## Teams: Conversation Sharing
* Team users can generate a shareable URL to a Cascade conversation
* Only fellow team members can access this URL
* Available to Teams and Enterprise SaaS
## Teams: Knowledge
* Team admins can connect their Google account and curate relevant Google Docs
* Team members will be able to @mention these docs, and Cascade can retrieve them
* Available to Teams and Enterprise SaaS
## Teams Deploys
* Teams users can connect their Netlify account via Windsurf settings
* Deploy apps through Cascade directly to your Netlify team for full control
* Supports team-specific settings like SSO, custom domains, and more through the Netlify dashboard
* Team admins can manage Deploy permissions and settings for their team.
## Teams Analytics
* Teams users get a refreshed analytics dashboard for their team
* Includes new Cascade analytics such as messages sent, total tool calls, model usage, and more
## Misc
* Upgrade to VS Code 1.99.1
# Patch Fixes
* Reduced errors for edit tool calls for Windows
* Fixed model selection and loading bugs on Command
# New App Icon & Upgraded Free Tier
## New App Icon
* Windsurf is now refreshed with a new app icon
* Windsurf.com has been updated with the new wordmark
* (Mac) Customizable app icons now use the new logo
## Upgraded Free Tier
* Free tier now has new, higher limits
* Ability to use Cascade in write mode
* Cascade prompt credits: 5 to 25 Cascade prompt credits per month
* Unlimited Fast Tab
* Unlimited Cascade Base
* Access to Previews
* 1 Deploy
## Performance Improvements
* Performance and reliability improvements when deploying an app using Deploys
* Allow users to create a new deployment even if they have an existing deployment config yaml
* Deploy web app tool now has a check deploy status tool call
* Stability improvements for remote extensions (WSL, SSH, Dev Containers)
* Performance improvements when typing in a large active diff zone
## Misc
* Adds GPT-4.1 to Command
* Upgraded to VSCode base version 1.98
# Patch Fixes
* Updates IDE marketplace link by mirroring Open VSX
# Updated & Simplified Pricing
## We're getting rid of Flow Action Credits
* We're simplifying our pricing model by removing Flow Action Credits
* Change takes effect April 21st, 2025
* Plans now come with prompt credits with add-on credits available for purchase
## User Prompt Credits
* Plans now come with prompt credits, which are consumed per every message sent and not via every tool call
* Add-on credits are available for purchase
* Auto-top off (with max limits) can be enabled via profile
## Existing Plans
* Existing plans are migrating over to the new pricing model
* For more information, please visit the Pricing page
# o4-mini Available
## New o4-mini models available and Free (Limited Time)
* Windsurf now supports the o4-mini medium and o4-mini high models, which are free for all users
* Usage in Windsurf is free for a limited time from April 16th to April 21st
# GPT 4.1 Available
## New GPT 4.1 Model available and Free (Limited Time)
* Windsurf now supports the new GPT 4.1 model, which is free for all users
* Usage in Windsurf is free for a limited time from April 14th to April 21st
# Patch Fixes
* Fixes to Commit Generation parsing on Windows
* UI Fixes to Rules
* Allow empty files on website deploy
* Better Deploys error visibility
* Ability to edit subdomain on website deploy
* Increased stability around MCP SSE connections
* Cascade bug fixes
# Patch Fixes
* Fixes to "Remote - WSL" extension
* Minor UX fixes
# Deploys
## Deploys (Beta)
* Deploy your application with one prompt to Netlify under a windsurf.build domain
* Claim your application's URL via Netlify
* Once claimed, continue deploying to the same project as you make updates
* To deploy a new site or change your subdomain, just ask Cascade to deploy to a new subdomain
* Available to all users for all tiers, with more for paid plans
## Commit Message Generation (Beta)
* Generate commit messages with a click in the Source Control Panel
* Available to users on paid plans with no additional credit cost per use
## Improvements to Memories
* New memories tab in Cascade
* New ability to edit Cascade's generated memories, including the memory's title, content and tags
* New ability to search Cascade's generated memories
* User setting toggle for Auto-Generate Memories
* When enabled, Cascade will autonomously generate memories to remember important context
* When disabled, Cascade will only create memories when you explicitly ask in your prompt
## Improvements to Long Conversations
* Introduced Cascade table of contents of all past user messages, which appears on conversation scroll
* Table of contents enables the ability to revert or scroll to any past message
* Improved performance when interacting with long conversations
## Improvements to Windsurf Tab
* Jupyter Notebook Support for Windsurf Tab
* Additional context signals for Windsurf Tab, including in-IDE search
# New Mac Icons
* Two new application icons (Retro and Pixel Surf) are available for users on paid plans
# Misc
* Cascade new conversation screen now has a new toolbar for tools like MCP, Preview and Deployments.
* Cascade now supports SSE MCP servers in the JSON configuration
* Fixed "Open Cascade on Reload" setting so Cascade will be closed upon opening a new window when setting is disabled
* Cascade input is persisted across new conversation screen and an active conversation
* Refreshed terminal UI in Cascade, with increased visibility for the "Open terminal" button, which opens Cascade's terminal instance directly
* Underlined links are now clickable in Cascade and user messages
* New user setting to enable sound when Cascade is done running (beta)
* Fixes to "Remote - SSH" extension, including custom SSH binary path setting
* Merged changes from VS Code 1.97.0
# Changelog (Next)
Source: https://docs.devinenterprise.com/desktop/changelog-next
Release notes for Devin Desktop (Windsurf) Next builds: preview features, improvements, and fixes shipped to the beta channel ahead of stable releases.
Download Next builds from the [Releases (Next)](/desktop/releases-next) page.
**Devin Desktop**
* Faster sidebar for users with thousands of cached sessions: filtering, space grouping, and sorting now only process the sessions actually fetched for display, eliminating multi-second lag after "Reload Window" or while scrolling.
**Devin Local**
* Fixed authentication issues with certain MCP servers, such as self-hosted GitLab servers and older Atlassian MCP instances
**Devin Desktop**
* Fixed a bug with accidentally triggering editor keybindings from the agent chat.
* The old "Plugins" section for IDE extension marketplaces has been renamed to "Extensions".
* Hide Cascade-specific configuration and customization options when Cascade is disabled for your team.
**Devin Local**
* Enabled share directly from the actions menu below a completed Devin Local turn.
* Plugins installed from Customizations are added to your personal plugins by default, so they are available in Devin Cloud and on your other devices; choose **Install locally** for a device-only install.
**Devin Desktop**
* Settings and Keyboard Shortcuts open as regular editor tabs by default; set `"workbench.editor.useModal": "all"` to keep the modal overlay.
* "Restart to Update" now asks for confirmation when local agents are still working and says how many will be stopped; cloud sessions keep running.
* Visual polish for the Agent Command Center: left-aligned titlebar, unsaved-changes indicator on file tabs, no more Cmd+P open/close flicker, aligned PR icons in Quick Open, full-width sidebar title renaming, and dragged session tabs that pick up their session name.
* Starting an agent in a new worktree that fails now surfaces the git error instead of quietly running in your workspace, and **Terminal: Create New Terminal in Editor Area** works again inside worktrees.
* Codemaps and MCP configuration files now open from the remote machine when connected over WSL, SSH, or a dev container.
* Teams plan members no longer see quota warning banners they cannot act on.
**Devin Local**
* Devin Local conversations can be shared: **Share Conversation** uploads a sanitized transcript (system prompts and tool definitions dropped, secrets redacted, paths normalized) and copies a team-visible link.
* Reverting is reliable mid-turn: revert buttons appear as soon as a prompt is sent and reverting while the agent is working cancels the turn first.
* The Customizations panel has search across every section (skills, subagents, rules, hooks, plugins, MCP servers), a new **Subagents** section, a refresh action for plugins, and an info indicator explaining why an enterprise-required plugin can't be removed.
* The transcript shows "Your modified files:" and "Your recent terminal commands:" lists, so you can see what Devin was told about between turns.
* Devin Local now activates for anyone with Windsurf access (no separate CLI permission needed).
* Permission rules from different levels (enterprise, mode, user, project, subagent) now compose predictably — an explicit `deny:` always wins, "always allow" options only appear when the grant would actually take effect, and denials say which layer denied them.
* Fixed rendering of commands whose output contains non-UTF-8 bytes.
* Ensured `sudo` password prompts can't hang a command.
* Session history is now cached in SQLite; sessions cached by an older build show a one-time loading state the first time they are reopened.
**Devin Cloud**
* Devin Cloud stays available in untrusted (Restricted Mode) workspaces, since cloud sessions run nothing on your machine; Cascade and Devin Local still wait until you trust the workspace.
* Session size chips use the same enterprise ACU thresholds as the web app, and auto-continuation billing notices appear inline in the transcript.
* Queued messages can be edited: click the edit button or press ⬆ in an empty input to pull the last queued message back.
* The `+X −Y` diff summary on a collapsed agent group is now clickable and opens a multi-diff editor with just that group's files.
* "Duplicate session" and "send as fork" open the fork in a new tab, keeping the original conversation open.
* "Grant access" on a network access request is disabled with an explanation when an admin owns the session's network policy.
**Fixed**
* Devin Desktop for Windows loads root and intermediate certificates from the Windows certificate store again, so sign-in and other HTTPS requests no longer fail with `self signed certificate in certificate chain` behind a TLS-inspecting proxy or a corporate root CA.
* The `edit`, `write`, `apply_patch`, and `notebook_edit` tools in Devin Local now refuse to write through a symlink, so an approved edit can no longer be redirected to an unexpected file.
**Fixed**
* Product analytics are no longer started before your account status resolves, so telemetry is never collected for accounts that have it turned off.
**Devin Desktop**
* Added a unified notifications setting that posts native OS notifications when any agent session finishes or needs your input.
* Codemaps now open in their own editor tabs in agent window mode (home, generation, and individual codemaps), and codemap @-mentions now work in Devin Local.
* Select text inside a message transcript and add it to the chat input with the "Add to chat" button or ⌘L / Ctrl+L.
* Added keyboard shortcuts for permission requests (always-allow and reject), with the shortcut hints shown on the buttons and dropdown entries.
* Refreshed the agent window UI: Inter font by default, web-app icon set at web-app sizing, rounded pill session tabs (with state/PR icons), and smarter pane placement so files no longer cover your session tabs.
* Pull request editor tabs now show a state-specific icon (open, draft, merged, or closed), and session-create cards show a Devin mode badge (Fast, Ultra, Fusion).
* Faster syntax highlighting for streaming diffs, and typing in the input no longer lags while other background sessions stream.
* Agent sidebar improvements: right-click context menus, double-click to rename, per-workspace filters/sort/grouping, greyed-out locked (read-only) sessions, a new-session shortcut hint, and sticky grouped spaces that keep their header.
* Signed-out session tabs now show a "You are signed out" sign-in prompt instead of an endless spinner, and logging out cleans up stale session tabs.
* Editing a past message keeps consistent typography, and the edited prompt stays visible at the bottom after a revert.
* Updated the base IDE to VS Code 1.126
**Devin Local**
* New "Devin: Open Cascade Migration Wizard" command opens a guided wizard that chains hooks → skills → memories migration in one flow, with per-item opt-in and dry-run previews.
* Worktree sessions now show a **Merge** button to bring their changes back into the workspace, and you can pick an existing worktree from the agent location selector's Local submenu.
* New tabs now default to Devin Local when you haven't chosen a preferred agent (falling back to Cascade if it isn't available), and Local is selectable in the agent selector while it's still connecting.
* `Megaplan` now work in Devin Local, switching the session into Plan mode and prompting the agent to plan first.
* Editable command approvals: click a command in a permission card to edit it before approving, or use the wand action to describe a change in plain language and have a fast model rewrite it for review.
* Queued messages can now be edited before they send, and editing or reverting a prompt preserves file, directory, skill, and terminal @-mentions.
* Added Rules to the @-mention menu so you can pull a manual-trigger rule into a conversation.
* Added a "Duplicate session" action to the response footer to branch off a conversation, and a "Subagents (Preview)" toggle in Devin settings.
* Response statistics now appear reliably after every turn.
* With "Agent Diff Zones" turned off, Devin Local no longer opens edited files in the background, and closing the last Devin Local tab now opens a fresh session instead of closing the panel.
* Fixed streamed `write`/`edit` previews creating stray fragment files when a filename contains underscores.
**Devin Cloud**
* Improved performance for loading Devin Cloud sessions.
* Devin Cloud sessions now show the server-side send queue, kept in sync with the web app; Cmd/Ctrl+Enter queues the next message on the server.
* Multi-user (Slack) sessions now show each participant's name above their messages.
* A "Copy link" action was added to cloud session menus.
* A "Remote ACP is disconnected" banner with a Reconnect action now appears when the Cloud connection drops.
**Devin Desktop**
* `@`-mention pills in Cascade now show type-specific icons.
* Restyled the command palette in the Agent Command Center.
* Hiding the status bar by default in the Agent Command Center (set `"workbench.statusBar.visible": true` in user settings to restore it).
* New worktree-backed sessions now open instantly and stay interactive while the worktree is created in the background.
* "View usage" now opens eligible Devin users' personal analytics page directly.
* The `devin.*` settings for gitignore access, completion mode, and auto-continue are now honored.
* Resuming an agent session now uses its original working directory, so Claude sessions started in another folder can be reloaded.
* Fixed a crash when opening the Recent Chat History modal in Cascade.
* On Windows, the auto-updater now clears stale `Devin.exe` processes before applying updates.
**Devin Cloud**
* Long Devin Cloud sessions render, scroll, and type faster and stay responsive while streaming.
* A brief remote-connection drop no longer flashes a "disconnected" banner.
* You can now configure a session's network policy and grant or deny network access requests inline from the chat, without switching to the web app.
**Devin Local**
* Devin Local customizations and the sidebar skills count now span all open workspace folders.
* The Hooks tab in Devin Local Customizations now lists configured hooks with their source and trigger events.
* Added a command to migrate Windsurf hooks into Devin hooks across every workspace folder.
* Added a subtle timeline navigator for Devin Local sessions.
* Added Fast Context support in Devin Local sessions.
Fixes issues with diff viewing in autonomous mode.
**Devin Desktop**
* Fixed orphaned Devin agent process cleanup on Windows.
* Fixed analytics connection failures under TLS-intercepting proxies.
**Devin Local**
* Edits produced in autonomous mode now produce reviewable diffs.
* Added a `sandbox.excluded` allow/ask/deny config (user and team settings) to run specific commands outside the sandbox; excluded commands also skip the sandbox proxy environment.
**Devin Desktop**
* Added "New session in space" to the session kebab menu.
* Devin Cloud sessions now auto-reconnect when the network returns.
* Images can now be copied from chat via the context menu.
* New users now default to agent mode.
* The agent sidebar now stays visible when sending problems or explain-and-fix to Cascade in agent window mode.
* Fixed branch checkout silently failing to open a worktree.
* Very large sessions no longer crash the window when reading or writing the session event cache.
* The "Scroll to top" button in long sessions now has a solid background so it stays visible in dark themes.
* Orphaned Devin ACP agent processes are now detected and cleaned up on startup.
**Devin Local**
* ACU usage is now shown in the `/usage` command.
* Skill `permissions:` frontmatter now applies to auto-approvals.
* Enterprise login policies are now enforced in the CLI.
* Fixed command approval parsing for PowerShell `$variable` assignment prefixes.
**Devin Desktop**
* Devin ACU usage is now displayed in the client.
* Fixed settings and extensions migration for Windows system-wide installs.
**CLI and Devin Local**
* On Windows, `bash` now resolves to Git Bash instead of the WSL launcher stub.
* Subagents can now be configured with a default model.
* The MCP registry cache is now warmed during startup, so MCP servers are ready sooner.
* Injected context is no longer included in auto-generated session titles.
* Fixed agent messages over-merging in Claude ACP sessions.
* Added an `attribution` option to the Devin Local [config file](/cli/reference/configuration/config-file); set it to `false` to suppress Devin mentions in commit messages.
**Devin Desktop**
* The Windows installer and updater are now branded "Devin".
* Added "Open Agent Kanban View" and "Open Agent List View" commands.
* Added "New file" and "Open file" actions to the agent window tab dropdown.
* The activity bar now stays visible at its default location in agent view.
* Test recording downloads now open in the system browser.
**CLI and Devin Local**
* `!` shell commands now run in your configured `$SHELL`.
* MCP servers support client-defined OAuth scopes.
* Interactive logins are persisted to a shared credential store.
* MCP plugin error cards now surface server error details and a "View logs" button.
* On Windows, Devin now detects GPO-blocked PowerShell and falls back to Git Bash.
Various bug fixes and improvements.
**Fixed**
* Made MCP registry parsing more tolerant of old and inconsistent schemas.
**Fixed**
* Fixed a bug with loading skill files that use alternative fields.
The 3.2 series brings Devin Local enhancements and continued Devin Desktop polish.
**Devin Local**
* Added a [`devin plugin`](/cli/extensibility/plugins/overview) system for extending Devin Local — in preview and opt-in for enterprises.
* Subagents can now call MCP tools directly.
* Teams can enforce terminal allow/deny lists through CLI permission scopes.
**Agent and Editor modes**
* Enabled the `Cmd+.` mode-toggle shortcut from the empty editor welcome panel.
**Other improvements**
* Improved handling for less common MCP server features.
* Removed the Explain sparkle button from the editor breadcrumbs.
The 3.1 series builds on the Devin Desktop rebrand with a smoother Agent/Editor experience, Devin Local improvements, and continued polish.
**Agent and Editor modes**
* Added the Agent/Editor switch to the collapsed-sidebar titlebar, and unified the search icon to open agent search.
* Kept the sidebar toggle in place when opening and closing the drawer.
* Smoothed switching between Agent and Editor modes so auxiliary windows no longer close and restore.
**Devin Local**
* Renamed the "Devin CLI" settings section to "Devin Local".
* Added a notification when Devin Local agent sign-in fails.
* Updated the bundled Devin Local agent to [v2026.5.26-8](/cli/changelog/stable#2026-5-26-8).
**Other improvements**
* Added `.devinignore` support alongside `.windsurfignore` and `.codeiumignore`.
* Settings and MCP marketplace pages now scroll across the full panel width and keep content centered on wide panels.
* Hardened migration from Windsurf on Windows to preserve shortcut icon.
* Improved handling of file context in Devin Local agent
* Increased proxy authentication timeout
* Fixed issues with some stdio MCP servers on Windows
### Enterprise
* Simplified model picker pricing view for select enterprise customers
Fixed intermittent issues with Devin Local connectivity.
Added a new command for Devin Desktop to rerun the migration from Windsurf. This will reset Devin Desktop settings and give you a second chance to import extensions and other settings from Windsurf. The "Reset migration from Windsurf" command can be found in the command palette.
A release was made.
Windsurf is now [Devin Desktop](https://devin.ai/blog/windsurf-is-now-devin-desktop).
This release updates the bundled Devin Local agent to 2026.5.26. Highlights are below — see the [changelog](https://cli.devin.ai/docs/changelog/stable#2026-5-26-0) for the full list of changes.
# New features
* Devin Local is now aware of the files you have open in the editor as part of its context.
* When prompted for an MCP tool permission in Devin Local, two additional server-level options are now offered: approve all tools on the server for the current session, or permanently.
# Bug fixes
* "Always Allow" permission grants in Devin Local now persist across sessions.
* Image attachments in Devin Local now show the correct warning when the selected model does not support images.
# Fixes for Devin Local
* Repaired hooks for Devin Local to allow blocking user prompts
* Improved plan mode in Devin Local to work in the OS sandbox
# Bug fixes and improvements
* Increased remote server startup timeout from 2.5s to 6s
# Bug Fixes and Improvements
* Fixed availability issues with swe-check model for some users.
* Improved terminal processing performance
* Restored conversation sharing
## Devin Review & Quick Review
All Windsurf IDE users now have access to [Devin Review](https://app.devin.ai/review) and [Quick Review](https://docs.windsurf.com/windsurf/quick-review) with your existing subscription.
## Agent Command Center
* Added list display option for the agent inbox
* Improved sessions sidebar sorting and filtering
* Performance improvements for loading and switching sessions
## Windows updates
We have fixed a bug preventing updates for some users on Windows. To upgrade to this version, you may need to:
* Wait for the update to download.
* Once it is downloaded, open Windows Task Manager and close all `devin.exe` processes
* Proceed with installing the update and restarting Windsurf
## Bug fixes and improvements
* Fixed bugs with some MCP servers
* Improved reliability of Devin Local agent
# Settings Improvements
* Settings now open in a dedicated tab instead of a modal, making it easier to navigate and find what you need
* Added a searchable sidebar to quickly locate settings across all categories
* Consolidated the settings gear into the global activity dropdown for a cleaner titlebar
# Agent Command Center Improvements
* Added button to rename agent sessions directly from the sidebar
* Added space @-mentions — you can now reference entire spaces in Cascade conversations
* Added automatic context sharing across sessions in a space
* Model picker search now surfaces the best-matching variant per model family
* Improved at-mention loading with incremental results instead of waiting for all categories
* Tab completions now respect your `files.exclude` settings
* The toolbar footer now works like the Cascade footer with accept/reject buttons tied to diff zones
* File paths and selection ranges are now included in @-mentions
* Session PRs are now rendered in the Devin Cloud sidebar item
* Fixed UI freeze that could occur when pasting large text into Cascade
# Bug Fixes
* Fixed scroll position not being preserved when switching between editor tabs
* Fixed sign-in / sign-out state showing contradictory status after a failed authentication
* Fixed titlebar items disappearing in narrow windows
* Fixed stale session data showing in the sidebar
# Bug Fixes & Improvements
## Bug Fixes
* Fixed a crash that could occur when switching between Cascade conversations
* Fixed an authentication issue that could prevent Devin Cloud sessions from starting
* Fixed an issue where responses to agent questions were not sent correctly
# Devin for Terminal
* Updated Devin Local agent to respect existing Windsurf proxy settings
* Added context window indicator for Devin Local agent
* Improved revert support for Devin Local agent
* Enabled mentioning terminal content in Devin Local sessions
* Added new keyboard shortcuts for accepting permission requests from Devin Local agent
# Bug Fixes and Improvements
* Added support for server-driven extension deny lists
* Simplified file drag & drop support in Agent Command Center
# Devin for Terminal
Devin is now available [for Terminal](https://devin.ai/terminal). All Windsurf users can use this new CLI agent with your existing subscription.
* **Runs on your machine** — Optimized for interactive work, with full access to your codebase, tools, and environment.
* **Hand off to the cloud** — Seamless hand off to Devin in the cloud, with its own VM, testing, video recordings, autofix and more. Come back to a finished PR.
* **Multi-model** — All of your favorite frontier models in one place, including Opus 4.7, GPT-5.5, and SWE-1.6.
* **Fast** — Written in Rust and so performant that the binary can run on an original VT100.
## Devin Agent in Windsurf
You can also enable the new Devin Local agent in Windsurf. This is the same agent harness used on the terminal and sessions can be accessed from both Windsurf and the CLI.
In our testing, it's up to 30% more token-efficient than the existing Cascade agent.
## Additional Changes
* Improved search subtitle layout during streaming
* Fixed file drag-and-drop in agent window Cascade tabs
* Fixed edit rendering issues in Devin Local on Windows
* Fixed Go to Line/Column keybinding on Windows/Linux (Ctrl+Shift+G)
* Stability and performance improvements
# Agent Command Center
* Added workspace and session filters to the spaces sidebar
* Improved unread indicators for sessions with mark read/unread functionality
* You can now drag sessions onto kanban cards to create Spaces
* Added "Put Devin to sleep" tab context menu action
* Improved Cmd+F find-in-chat for agent sessions
* Hand off plans from Cascade to Devin Cloud with one click
# Bug Fixes
* Fixed Cmd+P flicker when focused on cascade in agent mode
* Fixed Cmd+N to open untitled file when editor surface is focused in agent window
* Fixed Ctrl+Shift+M microphone keybinding in agent window mode
* Fixed agent sidebar highlight when focus moves to related panes
* Skip button now skips one question at a time in Devin Cloud sessions
* MCP registry now paginates instead of requesting limit=1000
* Honor HTTP\_PROXY for Windsurf Remote-SSH language server
* Stop Devin for Terminal from spawning console windows on Windows
* Prevent Cascade input re-renders causing typing lag
# Bug Fixes and Improvements
* Fixed OAuth authentication issues for some MCP servers
# Bug Fixes and Improvements
* Fixed a regression with OAuth integration for some MCP servers
* Improved reliability of Devin Cloud connections in Windsurf
# Bug Fixes and Improvements
* Various bug fixes and performance improvements
# Bug Fixes and Improvements
* Various bug fixes and performance improvements for improving Windsurf 2.0 auth experience.
* Fixed bug with spawning Terminal sessions on Windows
# Windsurf 2.0
Read the full announcement [here](https://windsurf.com/blog/windsurf-2-0).
## Devin in Windsurf
* Devin cloud agent available directly inside Windsurf, included with every self-serve plan
* Delegate tasks from a local session to Devin with one click; Devin runs on its own VM
* Review Devin changes and test results without leaving the editor
* Billing is based on your existing quota and extra usage, with up to 50 USD in extra usage added for launching your first Devin Cloud session.
**Note:** Access to Devin Cloud is rolling out gradually. If you don't see it yet, try logging out of the website and IDE then logging back in.
Devin Cloud is disabled by default for enterprise accounts. Enterprise admins should enable Devin access in their organization settings if they have already purchased Cognition Platform.
## Agent Command Center
* New Kanban-style view showing all local and cloud agent sessions, organized by status
* Group agent sessions, PRs, files, and context into task-level Spaces
* Switch between Spaces to switch between tasks
## Additional Changes
* Refined Windsurf Browser with toolbar integration and Cascade tool for reading page contents
* Sped up initial load times for the Cascade sidebar
* Improved .gitignore and .codeiumignore handling across the product
* Stability improvements for remote extensions (WSL, SSH, Dev Containers)
* Performance improvements for typing in large active diff zones
# Bug Fixes and Improvements
* Fixed resource parameter support for OAuth connections to MCP servers
* Enhanced MCP registry support
## Adaptive Fix
We fixed a bug with the adaptive model router which prevented switching models after the first request.
All users who encountered the bug have had quota reset and overage restored.
## Adaptive Model Visibility
We've improved the visibility of the adaptive model in the model picker.
# Introducing Adaptive
We've made several model packaging changes, with more info [here](http://windsurf.com/blog/windsurf-adaptive).
## Adaptive Model Router
A new **Adaptive** model option is now available in the model picker. Adaptive intelligently selects the best model for each task, helping you make your quota last longer by avoiding overuse of premium models.
* **Availability**: Now available to all self-serve users on Pro, Max, and Teams plans.
* **Dynamic model selection** - Automatically chooses the right underlying model for your task while drawing down quota at a fixed per-token rate.
* **Extra usage promo** - Beyond your quota, extra usage is offered at 0.50 USD per 1M input tokens, 2.00 USD per 1M output tokens, and 0.10 USD per 1M cache read tokens for the next 2 weeks.
# Token Tracking in Response Card
* Added token usage tracking to the response card. You can now see a breakdown of input tokens, output tokens, and cached input tokens for each response directly in the chat panel.
* Enhanced the context window indicator to show when the prompt cache expires, giving you better visibility into cache utilization.
# Bug Fixes and Improvements
* Fixed keyboard input issues with the built-in terminal on Windows
* Improved cost sorting for token-based plans in the model picker
* Clarified which models are available only on pro plans
* Repaired devcontainer support on RHEL 8
A release was made.
A release was made.
A release was made.
# Model & Cost Visibility
Replaced dollar signs with granular cost metrics for quota-based billing plans.
# Additional fixes
* Improved performance for large repos
* Upgraded to VSCode base version 1.110
* Fixed issues with diff zones reappearing after acceptance
# Quota Billing
* Added support for the new quota billing system
* Daily and Weekly quota usage is now displayed directly in the IDE
# Bug Fixes and Improvements
* Fix build for Mac x64
# Bug Fixes and Improvements
* Various bug fixes and performance improvements
# Bug Fixes and Improvements
* Fix for Apple M5
## Cascade
* Fix dangling Diff Zones related to Jupyter Notebooks
* Improve Jupyter Notebook performance when running on WSL
## Cascade
* Improve Cascade UI rendering performance
* Fix Cascade agent crashes under certain conditions
* Improve notifications for model price changes
* Add support for loading SKILL.md files from the `.windsurf/skills/` directory
* Fix `AGENTS.md` being ignored by Cascade in specific cases
## MCP
* Add support for [system-level Skill definitions](https://docs.windsurf.com/windsurf/cascade/skills#system-level-skills-enterprise) via MDM-managed configs for Enterprise
* Improve context management for MCP servers
## Stability & Performance
* Improve autocomplete error handling and performance
* Improve SSH & Remote performance
# Phoenix Alpha
Phoenix Alpha is now available in Next.
# Bug Fixes and Improvements
* Fix extension installation version selection
## New Model Picker
We introduced a new model picker that groups models by family and adds a hovercard with toggles for
specific variants, like reasoning effort and speed.
Separately, we also added the ability to pin models.
## Cascade Improvements
* Added `POST_CASCADE_RESPONSE_WITH_TRANSCRIPT` cascade hook
* Added Cascade hooks configuration visibility on team settings page
* Reduced the priority of Git commits in @ mention search
* Added a `devin.cascade.readClaudeCodeConfig` flag to disable reading Claude configuration
## MCP Improvements
* Added an MCP Refresh button
* Auto-trigger OAuth login when adding HTTP/SSE MCP servers
* Fix bugs with parsing on Windows and startup
## Platform Improvements
* Merged changes from VS Code 1.108
* Improved startup reliability for Cascade
* Fixed Windows update initialization path that could block updates
* Released binaries for Linux ARM64
A release was made.
# Bug Fixes and Improvements
* Fix compatibility with GitHub Pull Requests extension
# Bug Fixes and Improvements
* Fix for self-updating on Windows
* Fix for macOS UI flickering
# Cascade Improvements
* Plan Mode now supports automatic switching back to Code Mode when you start implementing a plan
* Added support for reading skills from the `.agents/skills` directory
* Tracking triggered rules in the `post_cascade_response` hook via a new `rules_applied` field
* Diff zones will now automatically close on commit
# Linux ARM64 Support
* Full Linux ARM64 client support with deb and rpm packaging
# Enterprise & Team Improvements
* Cloud configuration for Cascade Hooks is now available for enterprise teams via the cloud dashboard
* Support for Devin service key authentication
# Bug Fixes and Improvements
* Fixes for `post_write_code` hooks to handle all code editing tool formats
* Fixes and improvements for MCP server resource loading
* Fixed osascript privilege escalation being incorrectly triggered on Linux for shell command installation
* Addressed multiple memory leaks
* Improved RTL language rendering in todo lists
A release was made.
# New Models
* GPT-5.3-Codex-Spark is now available in Arena Mode's Fast Arena and Hybrid Arena battle groups
# Claude Opus 4.6 (fast mode)
Claude Opus 4.6 (fast mode) is now available in Windsurf in research preview with limited-time promotional pricing for self-serve users until Feb 16:
* **No thinking:** 10x credits
* **With thinking:** 12x credits
Opus 4.6 (fast mode) has the same intelligence as Opus 4.6 but with up to 2.5x higher output speeds.
# Bug Fixes and Improvements
* Fix issues with Arena Mode Battle Groups
# Bug Fixes and Improvements
* Improve UI styling for announcement popups and notifications
* Close model picker when selecting a battle group
# Bug Fixes and Improvements
* Various bug fixes and performance improvements
# Wave 14: Arena Mode
Arena Mode brings side-by-side model comparison directly into your IDE, plus Plan Mode for smarter task planning.
## Arena Mode
Run two Cascade agents side-by-side with hidden model identities and vote on which performs better. Arena Mode lets you discover which models actually work best for *your* workflow, codebase, and tasks—not just what benchmarks or influencers say.
* **Battle Groups**: Choose specific models to compare or let Windsurf randomly select from curated groups like "fast models" vs "smart models"
* **Personal & Global Leaderboards**: Your votes contribute to both a personal leaderboard (your preferences) and a global one (across all Windsurf users)
* **Sync or Branch**: Send followup prompts to both agents simultaneously, or branch and explore different paths individually
To get started, select the new **Arena** tab in the model picker. All battle groups are free for the first week for paid users.
## Plan Mode
Plan Mode is a new Cascade mode alongside Code and Ask. Use it to create detailed implementation plans before diving into code.
**Pro tip**: Type `megaplan` in the Cascade input box to trigger an advanced form that asks clarifying questions to create a more aligned, comprehensive plan.
# Bug Fixes and Improvements
* Admins can now set a default model that applies to all team members when they first open Windsurf
* Various bug fixes and performance improvements
A release was made.
# Bug Fixes and Improvements
* Fix bug with permanently disconnected cascades
# Bug Fixes
* Fixes commit message generation and codemaps suggestions
# Enterprise Features
* Enterprise admins can now specify organization-wide allow and deny lists for command auto-execution. [Learn more](https://docs.windsurf.com/windsurf/terminal#team-wide-command-lists-teams-&-enterprise)
# Bug Fixes and Improvements
* Bug fixes and performance improvements for diff zones
* Improved overall stability and reliability
* Added [`post_setup_worktree`](https://docs.windsurf.com/windsurf/cascade/worktrees#setup-hook) hook for initializing worktrees in Cascade
# Bug Fixes and Improvements
* Improvements to GPT-5.2-Codex harness
* Admins can now manage Windsurf restrictions via Windows Group Policy
# GPT-5.2-Codex
Adds support for GPT-5.2-Codex with four reasoning efforts (low, medium, high, and xhigh).
GPT-5.2-Codex is OpenAI's latest model designed for agentic coding. It excels at working in large codebases over long sessions.
For most tasks, we recommend using the medium reasoning effort.
# Bug Fixes and Improvements
* Various bug fixes and performance improvements
* Improved stability and reliability
# Bug Fixes and Improvements
* Various bug fixes and performance improvements
* Improved stability and reliability
# New Features and Improvements
* Plan Mode Update
* Support for Skills
# Bug Fixes and Improvements
* Various bug fixes and performance improvements
# Gemini 3 Flash
Gemini 3 Flash is now available for all users. This model combines Gemini 3 Pro-grade reasoning with Flash-level speed and efficiency, making it ideal for agentic workflows and coding tasks.
* **Blazing Fast Responses**: Experience near-instant feedback with 3x faster performance than previous generations, perfect for iterative development compared to Gemini 3 Pro
* **Superior Coding Intelligence**: Outperforms even Pro-tier models on key coding benchmarks (78% on SWE-bench Verified), providing more accurate code generation and debugging
* **Deep Multimodal Understanding**: Easily process complex video, data extraction, and visual Q\&A tasks with frontier-level reasoning
# Bug Fixes and Improvements
* Various bug fixes and performance improvements
* Tab fixes and improvements
# Wave 13: Merry Shipmas
Wave 13 brings first-class support for parallel, multi-agent sessions in Windsurf, along with Git worktrees, side-by-side Cascade panes, and a dedicated terminal profile for more reliable agent execution.
## SWE-1.5 Free
Our near-frontier model, SWE-1.5, is now available for free to all users for the next 3 months. SWE-1.5 Free has the full intelligence of SWE-1.5, with the same coding performance on SWE-Bench-Pro, but delivered at standard throughput speeds. The original variant of SWE-1.5 hosted on Cerebras will continue to be available for paid users. SWE-1.5 Free will replace SWE-1 as the default model in Windsurf starting today.
## Git Worktree Support
Windsurf now supports Git worktrees, letting you spawn multiple Cascade sessions in the same repository without conflicts. Git worktrees check out different branches into separate directories while sharing the same Git history.
## Multi-Cascade Panes & Tabs
You can already run multiple Cascade sessions in Windsurf at the same time. Now, you can view and interact with them in separate panes and tabs within the same window. This lets you monitor progress and compare outputs of sessions side-by-side, or even turn Windsurf into a big Cascade dashboard.
## Cascade Dedicated Terminal (Beta)
Windsurf introduces a new approach for letting agents execute terminal commands. Instead of your default shell, Cascade will now run commands in a dedicated zsh shell specifically configured for reliability. The Cascade Dedicated Terminal can use the environment variables you set in your .zshrc configuration and is interactive, which means you can answer any prompts from shell scripts without having to break your flow. This should improve the reliability and speed of shell commands, especially for users with complicated prompts (e.g., powerlevel10k).
In this version, the Cascade Dedicated Terminal will be opt-in for Windsurf Stable on macOS. If you are experiencing issues with the older legacy terminal, we recommend switching to the new terminal early. We expect to make this feature the default in the future, while maintaining the legacy terminal extension for backwards compatibility purposes. You can opt-in in the Windsurf User Settings -> Disable Windsurf Legacy Terminal Profile.
## Context Window Indicator
When a model's context window grows too long, earlier context can be dropped without warning and performance can degrade. Cascade already extends the window by occasionally summarizing messages and clearing history. This release adds a visual indicator to see how much of your context window is currently in use, helping you anticipate limits and decide when to start a new session.
## Cascade Hooks
Execute custom commands at key points during Cascade's workflow, including on model response for auditing purposes.
## System-level Rules & Workflows
Enterprises can deploy rules and workflows via MDM policies, allowing organizations to place rules and workflows files on users' machines.
# Bug Fixes and Improvements
* Enhanced diff zone behavior with configurable scroll-to-next-hunk settings (default off)
* Preserved colors and styling in Cascade terminal output
* Multiple fixes to the Model Context Protocol implementation
* Supports lowering permissions for Cascade's Web Fetch tool
* Fix race condition in the dedicated terminal implementation
* Support force killing commands in the dedicated terminal
* Improved markdown completion
* Fix opening old Cascade diffs
# Bug Fixes and Performance Improvements
* Fix race condition in the new dedicated terminal implementation
* MCP fixes
* Added setting to control scroll-to-next-hunk behavior in diff zones (default off)
* Improve markdown completion
* Preserve terminal colors and styling in the Cascade terminal output pane
* Diff zone fixes and improvements
* Support turbo mode for web fetch requests made by Cascade's Web Fetch tool
* Support force killing commands in the new dedicated terminal
# New Features
## Windsurf Dedicated Terminal
* Introduces a new terminal for Cascade that improves command execution reliability (OS X only)
## Multi Cascade Panels and Tabs
* Adds support for multiple Cascade panels and tabs, allowing users to work with multiple Cascade sessions simultaneously
## Cascade Hooks on Cascade Response
* Allows users to configure Cascade Hooks on model response, specifically for logging all Cascade responses for auditing purposes
## System-level Rules + Workflows
* Allows enterprises to place rules and workflows files on users' machines with MDM policies
# Bug Fixes
* Fix opening old Cascade diffs
* Fix various stability issues with the new terminal implementation
# Patch Fixes and Improvements
* Fix opening old Cascade diffs
# Features
Added a new "Promo" label to LLM models that are newly available or have special discount pricing
# Patch Fixes and Improvements
* Enhances code block file path display to hide line numbers for whole files
* Improves citation and language parsing in code blocks with a more robust regex pattern
* Updates the UI for code block title bars to properly handle long paths with truncation
* Fixes fallback diff handling for nonexistent files in code actions
* Improves the auto-run command menu interface and its display logic
# Patch Fixes and Improvements
## Agents & Tool Execution
* Fixed Command-I functionality
* Fixed Ctrl+C during tool execution not working properly
* Fixed Go (fallback) processes not being killed properly
* Fixed handling of parallel tool call errors
## UI & Rendering
* Fixed incorrect indentation from code blocks in terminal rendering
* Fixed nested lists not rendering on new line in terminal markdown
* Fixed content spacing issues
* Fixed streaming flashes
## Messaging & Platform
* Fixed rate limit error message to say "no credits were used" instead of "credits have been refunded"
* Fixed continuously rechecking for updates on macOS
* Added a user-facing message when API providers are exhausted
## Tooling & Onboarding
* Improved MCP tool call visibility (show tool name, args, etc)
* Added loading indicators when thinking or during long running operations
* Allowed clicking items in the Windsurf onboarding pane
* Respected gitignore patterns in the workspace directory tree
# Patch Fixes and Improvements
* Reduce occurrence of "prompt is too long" errors
* Request all supported scopes if no scopes are provided in MCP OAuth config
# GPT-5.2
GPT-5.2 is now available in Windsurf. This model will be available for 0x credits in Windsurf (to paid users) for a limited time.
GPT-5.2 represents the biggest leap for GPT models in agentic coding since GPT-5 and is a SOTA coding model in its price range. The version bump undersells the jump in intelligence. We\`re excited to make it the default across Windsurf and several core Devin workloads. - Jeff Wang, CEO of Windsurf
Download the [latest version on Windsurf](https://windsurf.com/download/editor) to try it out!
# Bug fixes and improvements
* General Windsurf stability and performance improvements
* General Tab (Supercomplete) improvements and stability
* Fixes issues with Cascade running commands that could not be cancelled during certain long-running processes
# Diff Zones
* Fixes issues with diff zones not rendering correctly or jumping to the end of a file when editing
# Lifeguard
* Fixes various Lifeguard bugs and stability issues
# Tab (Supercomplete)
* Improves reliability of Tab autocomplete
* Makes Tab more responsive and faster in the appropiate circumstances
# MCP Servers
* Added support for [MCP prompts](https://modelcontextprotocol.io/docs/concepts/prompts)
* Added toggles to enable/disable MCPs in the Cascade header
# Bug fixes and improvements
* General stability and performance improvements
* Fixes issues with login timing out too quickly during onboarding
# Features & Tools
## Cascade Hooks on User Prompts
* Users can now configure Cascade Hooks on user prompts for logging all user prompts and blocking policy-violating prompts.
## Worktree / Arena Mode
* Added support for Worktree and Arena Mode.
## MCP Servers
* Added support for GitLab remote MCP.
* Added OAuth support for GitHub remote MCP.
* Fixed an issue where every MCP would reauth on opening Windsurf.
# General Improvements
* General performance and stability improvements.
* Improvements for Tab (Supercomplete) autocomplete reliability.
# GPT-5.1-Codex Max
Introducing GPT-5.1-Codex Max in three reasoning tiers (Low, Medium, High). Low variant available at no cost to paid users for a limited time.
# Claude Opus 4.5
You can now use Claude Opus 4.5 in Windsurf!
Opus 4.5 is the most capable model in Windsurf yet and is now available at Sonnet pricing for a limited time (2x credits compared to 20x for Opus 4.1).
This model is available to all paid Windsurf subscribers.
# AI Models
## Gemini 3 Pro
* You can now use Gemini 3 Pro (Low and High) in Windsurf! This is a preview release that is available to paid Trial, Pro, and Teams subscribers and will soon be extended to Enterprise users as well.
* Resolved an issue where Gemini 3 Pro caused internal Cascade errors for some users.
## SWE-1.5
* Fixed notebook tool functionality for SWE-1.5.
* Addressed an issue where SWE-1.5 would unexpectedly stop or return "No response requested".
## Sonnet 4.5
* Added support for Sonnet 4.5 with a 1M token context window.
* Reduced the frequency of unnecessary Markdown file creation by Sonnet 4.5.
## GPT-5.1 Codex and Codex Mini
* Added support for GPT-5.1 Codex and Codex Mini with low reasoning effort configuration.
# Features & Tools
## Codemaps
* Improved reliability of saving and retrieving Codemaps.
* Fixed Codemap sorting and increased the limit of visible open Codemaps.
* Resolved issues with mentioning Codemaps in Cascade.
## MCP Servers
* Fixed scope handling and OAuth authentication flows for various MCP servers.
* Resolved issues preventing installation of new MCP servers.
* Added support for handling embedded resource content in tool call responses.
## Tab Completion
* Improved latency, responsiveness, and accuracy of autocomplete.
Note: The Autocomplete setting has been removed as it was a legacy option that had no effect. Windsurf's Tab autocomplete feature is powered by Supercomplete.
## Vibe and Replace
* Fixed reliability issues with Vibe and Replace.
## Fast Context
* Added support for `.codeiumignore` and `.gitignore` for Fast Context.
# General Improvements
* Fixed various UI alignment issues with icons and styles.
* General performance and stability improvements.
* Fixed issues with the file search tool.
# Worktree Preview
You can now use Windsurf's AI agent with worktrees to explore and modify code across multiple branches simultaneously.
# MCP Server Improvements
* Fixes issues with scopes and OAuth authentication flows for multiple MCP servers
# Tab Completion
* Improved latency, responsiveness, and accuracy of autocomplete.
# Context Window Indicator Beta
* Context window indicator now shows the current context window used by the Cascade AI agent.
# GPT-5.1 Priority Mode
* Added priority processing support for GPT-5.1 models, providing guaranteed low-latency responses for faster (\~50 tokens/sec), more reliable AI assistance.
* Priority processing costs 2x the standard rate, which will be reflected in the Windsurf credit system.
# Patch Fixes and Improvements
* Fixed tool call calling issues for GPT-5.1-Codex and GPT-5.1-Codex Mini models
# GPT-5.1 and GPT-5.1-Codex
GPT-5.1 and GPT-5.1-Codex are now available in Windsurf. GPT-5.1 will become the default model in Windsurf for one week, and paid users get free access during this period.
GPT-5.1 and GPT-5.1-Codex deliver a solid upgrade from GPT-5 for agentic coding workflows. They're noticeably better at understanding what you're asking for and working with you to get it done. The new variable thinking feature dynamically adjusts reasoning depth—providing quick responses for simple tasks and more thoughtful analysis when complexity demands it.
# Patch Fixes and Improvements
## Removed Features
* **Knowledge Base**: Removed the Knowledge Base feature
## Bug Fixes
* **PowerShell + Turbo Mode**: Fixed an issue where PowerShell was not running commands when Turbo Mode is enabled
## Shortcuts
* **Attach current file to Cascade**: New shortcut `Option/Alt+Cmd+L` when in an editor to attach the current file to Cascade
# Features
## MCP Improvements
* **Loading state indicators**: Show loading state per installed MCP to improve visibility during initialization
* **Refresh only edited MCPs**: When `mcp_config.json` is modified, only the affected MCP server instance is initialized/refreshed - no other instances are refreshed
* **Increased initialization timeout**: MCP initialization timeout increased to 60s
* **Refresh button for error states**: Show refresh button for MCPs in error state to allow manual recovery
## Cascade Hooks
* **Enterprise feature**: New Cascade Hooks feature available
* **Public documentation**: [Draft documentation](https://docs.windsurf.com/windsurf/cascade/hooks) with details and descriptions of hooks available in Windsurf Docs
## Bug Fixes
* **Vim extension typing lag**: Fixed bug causing typing lag when Vim extension is enabled
## SWE 1.5 Image Support
* **Image understanding**: Images are now supported in SWE 1.5, enabling visual content analysis
# Features
## Improvements to SWE-1.5 + Claude Sonnet 4.5 Mode
Enhanced the SWE-1.5 + Claude Sonnet 4.5 mode with improved performance and reliability for better coding assistance.
# Features
## Expanded Codemaps
Codemaps now include powerful new capabilities:
* **Chat with map** - Interact directly with your codebase visualizations
* **Mermaid diagrams** - Generate visual diagrams within maps for better code understanding
* **Cascade suggestions** - Get AI-powered suggestions directly in your maps
* **Map option in chat/edit nudges** - Easily create maps from chat and edit interactions
* **Smart mode option** - Enhanced intelligent assistance when working with maps
## Cascade Summarization Fix
Improved Cascade summarization to better handle longer conversations. Previously, summaries could be too aggressive and drop important context. Now maintains better continuity across long sessions with multiple file changes and user messages.
## Sonnet 4.5 Support for SWE 1.5 Planning
You can now enable beta Sonnet 4.5 planning when using SWE 1.5. To enable, select SWE 1.5 first, then select the Sonnet 4.5 addon.
## MCP Enhancements
* **Path component handling** - Improved support for MCP URLs with path components (e.g., Smithery MCPs)
* **OAuth flow improvements** - Better OAuth flow for streamable HTTP MCPs (e.g., Canva, ServiceNow's internal MCP)
# Bug fixes and improvements
## Performance Improvements
* **Sticky scroll lag fixes** - Resolved lag spikes when using sticky scroll with Vim bindings
* **General slowness fixes** - Addressed performance issues caused by VSCode OSS update
* **Terminal rendering optimization** - Fixed rendering loop that caused 500ms+ delays on first terminal open
## Terminal Fixes
* **PowerShell improvements** - Fixed Windows terminal integration issues where commands would appear stuck
* **Shell theme compatibility** - Resolved edge cases with custom shell themes (zsh, fish, powerlevel10k, etc.) that could cause Windsurf to break or show stuck commands
## Editor Stability
* **Terminal freeze fix** - Fixed an issue where the editor would freeze when opening the terminal
* **CMD+J fix** - Resolved layout thrashing issue when opening terminal pane with CMD+J
# Features
New beta plan mode (type /plan in the Cascade chat input to activate it).
Expanded Codemaps:
* Chat with map
* Mermaid diagrams in maps
* Cascade suggestions for maps
* Chat / edit nudge includes “map option”
* Smart mode option
# Bug fixes and improvements
* Fixes for lag spikes when using sticky scroll
* Fixes for general slowness caused by VSCode OSS update
* Powershell fixes for Windows terminal integration / commands appearing stuck.
* Fixes for certain edge cases around shells with custom themes.
* Fixed an issue where the editor would freeze when opening the terminal
# Falcon Alpha
You can now try a new stealth model in Windsurf: Falcon Alpha. Falcon Alpha is a powerful agentic model designed for speed. We're excited to hear what you build with it!
# Patch Fixes and Improvements
* Various performance improvements and bug fixes.
# Patch Fixes and Improvements
* Support and fixes for AGENTS.md
* Improvements and bug fixes for Codemaps.
* Improvements to Fast Context. Enterprises can opt in using the Windsurf Team Settings. Users can toggle Fast Context automatically using "CMD/Ctrl + Enter" on the first message in a chat.
* New auto-linting behavior that speeds up Cascade.
* Fix for MCP Marketplace not respecting team allowlist options.
* Fixes for Jupyter Notebook tool.
* Fixes for Memories, Rules, and Workflows.
* General bug fixes and improvements.
* Performance optimizations and stability enhancements.
# Dependencies
* Updated Code OSS to version 1.105.0 (Electron: 37.6.0, Chromium: 138.0.7204.251)
# Patch Fixes
* Bug fixes and improvements.
# Patch Fixes
* Bug fixes and improvements.
# Patch Fixes
* Early preview of Windsurf's new Tab model.
* Bug fixes and improvements.
# Patch Fixes
* Bug fixes and improvements.
# Patch Fixes
* Fixes issues with the experimental Cascade tool for finding context not working properly.
* Improvements and bug fixes for the beta Codemaps feature.
* Improvements to the Lifeguard (Beta) feature.
* Fixes issue with custom MCP servers not being displayed correctly in the new MCP panel.
* Fixes issue where some bash commands would get stuck.
* Fixes issue where certain models couldn't create or edit Jupyter notebooks.
* General bug fixes and improvements.
# Patch Fixes
* Various improvements to the experimental Cascade tool which searches and finds relevant files.
# Experimental Cascade Tool
* Experimental Cascade tool to quickly search for files and find relevant context.
# Lifeguard (Beta) Updates
* Try out Lifeguard by clicking the Lifeguard icon at the top right corner of your editor.
# Patch Fixes
* Minor improvements and bug fixes.
# Lifeguard
* Beta preview of lifeguard, a tool to help you find and resolve bugs inside your IDE.
# Codemaps
* Beta preview of codemaps: open the codemaps pane to try it out!
# Claude Sonnet 4.5
* Claude Sonnet 4.5 is now available
# Patch Fixes
* Fix using MCP tools with certain models.
* Fixes to terminal issues on Windows.
# Patch Fixes
* Fix to Cascade slowness issues
# GPT-5-Codex is now in Windsurf!
GPT-5-Codex is now available for free (0x credits) for a limited time for paid users!
Free users can use GPT-5-Codex as well for 0.5x credits.
# Patch Fixes
* Minor improvements and bug fixes
# Cascade Improvements
* Queued messages in Cascade
# Patch Fixes
* Various improvements and bug fixes
# Patch Fixes
* Minor improvements and bug fixes
# Patch Fixes
* Minor improvements and bug fixes
# Patch Fixes
* Minor improvements and bug fixes
# Patch Fixes
* Minor improvements and bug fixes
# Improvements
* Early access to Wave 12 features.
# Patch Fixes
* Performance fixes, especially relating to long chats
# Patch Fixes
* Miscellaneous fixes
# Patch fixes
* Miscellaneous fixes
# Patch Fixes
* Based on the latest release of the Windsurf Editor, v1.11.1
# Patch Fixes
* Based on the latest release of the Windsurf Editor, v1.11.0
# Speak to Cascade
## Voice
* Users can now speak into the chat rather than having to type things out.
## @-mentioning conversations
* @-mention the first conversation so Cascade has full context of it as it goes to write tests for you.
## Deeper Browser integration
* Chat with Cascade about tabs that are open in the Browser using @-mentions
## JetBrains improvements
* Planning Mode, Workflows, and file-based Rules are now available for Cascade on JetBrains
## Improvements
* Now you can @-mention terminal in Cascade.
* You can turn on the Auto-Continue setting to have Cascade automatically continue its response if it hits a limit.
* Support for more MCP servers with easier and more secure authentication by integrating the new Streamable HTTP transport (replaces SSE) and MCP authentication (replaces access tokens or API keys in the config).
* Important for enterprise customers who use Windsurf across lots of repos. Now, you can enforce ignore rules across all repositories by placing .codeiumignore in the \~/.codeium/ folder
# Patch fixes
* Miscellaneous fixes
# Cascade Improvements
* Improvements to Cascade reliability
# Patch fixes
* Miscellaneous fixes
# Patch fixes
* Miscellaneous fixes
# Patch Fixes
* Fixes to default model selection for new users
# Patch Fixes
* Based on the latest release of the Windsurf Editor, v1.10.5
# Patch Fixes
* Based on the latest release of the Windsurf Editor, v1.10.4
# Planning Mode
* Based on the latest release of the Windsurf Editor, v1.10.3
# Planning Mode
* Based on the latest release of the Windsurf Editor, v1.10.1
# Patch fixes
* Miscellaneous fixes
# Updates
* Removal of legacy mode
* Icons in @-mentions
* Theme-aware codeblocks with refreshed design
* Native terminal in Cascade panel
# Patch Fixes
* Based on the latest release of the Windsurf Editor, v1.9.4
# BYOK (Anthropic Key)
* Based on the latest release of the Windsurf Editor, v1.9.2
# SWE-1 Improvements
* Adds multi-modal (image) support to SWE-1
# New Family of SWE-1 Models
* Based on the latest release of the Windsurf Editor, v1.9.0
# Patch Fixes
* Fixes on Windows signing to prevent warnings from Windows Defender
# Patch Fixes
Based on the latest release of the Windsurf Editor, v1.8.2
# Teams Features
Based on the latest release of the Windsurf Editor, v1.8.0
# Improvements
Some improvements to app icons, fixes to SSH server connection, and UI Polish for Cascade Plugins.
# New Features
## Cascade Plugin Panel
* New panel in Cascade for managing MCP Servers
* Easier one-click uninstall and install
* Easier search
* MCP now has MCP resources and multimodel responses
* More MCP Server options coming soon
## Cascade Customization Panel
* Revamped Memories panel to include rules, workflows, and memories
## Revamped rules
* Support for workspace-style rules in `.windsurf/rules`
* Custom triggers when to activate a rule
## Workflows
* Support for quick instructions for Cascade to take on mini-tasks
* `.windsurf/workflows` houses workflows that Cascade can do in the current workspace
* Workflows can be found as slash commands (/) in the Cascade input
## Cascade Improvements
* Conversation sharing with a teams-only accessible URL
## Misc
* Redesigned Model Selector
* Continue button when reaching individual tool call limit
* Hunk accept/reject widget now has a compact mode to cover less code
* Tab respects files mentioned in `codeiumignore`
# Patch Fixes
Based on the latest release of the Windsurf Editor, v1.7.3
# New App Icon & Upgraded Free Tier
Based on the latest release of the Windsurf Editor, v1.7.2
## Patch Fixes
* Updates IDE marketplace link by mirroring Open VSX
## Experimental Improvements
* Bug fixes
* Performance optimizations
* VS Code 1.98.0 Updates
## Updated and Simplified Pricing
* We're simplifying our pricing model by removing Flow Action Credits
* Change takes effect April 21st, 2025
* Plans now come with prompt credits with add-on credits available for purchase
## User Prompt Credits
* Plans now come with prompt credits, which are consumed per every message sent and not via every tool call
* Add-on credits are available for purchase
* Auto-top off (with max limits) can be enabled via profile
## Existing Plans
* Existing plans are migrating over to the new pricing model
* For more information, please visit the Pricing page
## New o4-mini models available and Free (Limited Time)
* Windsurf now supports the o4-mini medium and o4-mini high models, which are free for all users
* Usage in Windsurf is free for a limited time from April 16th to April 21st
# Chat Models
Source: https://docs.devinenterprise.com/desktop/chat/models
Available AI models for Devin Desktop Chat including Base Model, Devin Desktop Premier, GPT-4o, and Claude 3.5 Sonnet with different access levels.
While we provide and train our own dedicated models for Chat, we also give you the flexibility to choose your favorites.
It's worth noting that the Devin Desktop models are tightly integrated with our reasoning stack, leading to better quality suggestions than external models for coding-specific tasks.
Model selection can be found directly under the chat.
## Base Model ⚡
**Access:** All users
Available for unlimited use to all users is a fast, high-quality Devin Desktop Chat model based on Meta's [Llama 3.1 70B](https://ai.meta.com/blog/meta-llama-3-1/).
This model is optimized for speed, and is the **fastest** model available in Devin Desktop Chat. This is all while still being extremely accurate.
## Devin Desktop Premier 🚀
**Access:** Any paying users (Pro, Teams, Enterprise, etc.)
Available in our paid tier is unlimited usage of our premier Devin Desktop Chat model based on Meta's [Llama 3.1 405B](https://ai.meta.com/blog/meta-llama-3-1/).
This is the **highest-performing model** available for use in Devin Desktop, due to its size and integration with Devin Desktop's reasoning engine and native workflows.
## Other Models (GPT-4o, Claude 3.5 Sonnet)
**Access:** Any paying users (Pro, Teams, Enterprise, etc.)
Devin Desktop provides access to OpenAI's and Anthropic's flagship models.
# Chat Overview
Source: https://docs.devinenterprise.com/desktop/chat/overview
Chat with your codebase using Devin Desktop Chat in VS Code and JetBrains. Use @-mentions, persistent context, pinned files, and inline citations.
Chat and its related features are only supported in: VS Code, JetBrains IDEs, Eclipse, Xcode, and Visual Studio.
**Devin Desktop Chat** enables you to talk to your codebase from within your editor.
Chat is powered by our [context awareness](/desktop/context-awareness/overview.mdx) engine.
It combines built-in context retrieval with optional user guidance to provide accurate and grounded answers.
In VS Code, Devin Desktop Chat can be found by default on the left sidebar.
If you wish to move it elsewhere, you can click and drag the Devin Desktop icon and relocate it as desired.
You can use `⌘+⇧+A` on Mac or `Ctrl+⇧+A` on Windows/Linux to open the chat panel and toggle focus between it and the editor.
You can also pop the chat window out of the IDE entirely by clicking the page icon at the top of the chat panel.
In JetBrains IDEs, Devin Desktop Chat can be found by default on the right sidebar.
If you wish to move it elsewhere, you can click and drag the Devin Desktop icon and relocate it as desired.
You can use `⌘+⇧+L` on Mac or `Ctrl+⇧+L` on Windows/Linux to open the chat panel while you are typing in the editor.
You can also open the chat in a popped-out browser window by clicking `Tools > Windsurf > Open Windsurf Chat in Browser` in the top menu bar.
## @-Mentions
An @-mention is a deterministic way of bringing in context, and is guaranteed to be part of the context used to respond to a chat.
In any given chat message you send, you can explicitly refer to context items from within the chat input by prefixing a word with `@`.
Context items available to be @-mentioned:
* Functions & classes
* Only functions and classes in the local index
* Also only available for languages we have built AST parsers for (Python, TypeScript, JavaScript, Go, Java, C, C++, PHP, Ruby, C#, Perl, Kotlin, Dart, Bash, COBOL, and more)
* Directories and files in your codebase
* Remote repositories
* The contents of your in-IDE terminal (VS Code only).
You can also try `@diff`, which lets you chat about your repository's current `git diff` state.
The `@diff` feature is currently in beta.
If you want to pull a section of code into the chat and you don't have @-Mentions available, you can: 1. highlight the code -> 2. right click -> 3. select 'Devin Desktop: Explain Selected Code Block'
## Persistent Context
You can instruct the chat model to use certain context throughout a conversation and across different conversations
by clicking on the `Advanced` tab in the chat panel.
In this tab, you can see:
* **Custom Chat Instructions**: a short prompt guideline like "Respond in Kotlin and assume I have little familiarity with it" to orient the model towards a certain type of response.
* **Pinned Contexts**: items from your codebase like files, directories, and code snippets that you would like explicitly for the model to take into account.
See also [Context Pinning](/desktop/context-awareness/overview#context-pinning).
* **Active Document**: a marker for your currently active file, which receives special focus.
* **Local Indexes**: a list of local repositories that the Devin Desktop context engine has indexed.
## Slash Commands
You can prefix a message with `/explain` to ask the model to explain something of your choice.
Currently, `/explain` is the only supported slash command.
[Let us know](https://discord.com/invite/3XFf78nAx5) if there are other common workflows you want wrapped in a slash command.
## Copy and Insert
Sometimes, Chat responses will contain code blocks. You can copy a code block to your clipboard or insert it directly into the editor
at your cursor position by clicking the appropriate button atop the code block.
If you would like the AI to enact a change directly in your editor based on an instruction,
consider using [Devin Desktop Command](/desktop/command/plugins-overview).
## Inline Citations
Chat is aware of code context items, and its responses often contain linked references to snippets of code in your files.
## Regenerate with Context
By default, Devin Desktop makes a judgment call whether any given question is general or if it requires codebase context.
You can force the model to use codebase context by submitting your question with `⌘⏎`.
For a question that has already received a response, you rerun with context by clicking the sparkle icon.
## Stats for Nerds
Lots of things happen under the hood for every chat message. You can click the stats icon to see these statistics for yourself.
## Chat History
To revisit past conversations, click the history icon at the top of the chat panel.
You can click the `+` to create a new conversation, and
you can click the `⋮` button to export your conversation. This applies only for the Devin Desktop Plugins.
## Settings
Click on the gear icon to reach the `Settings` tab. Here, you can view settings that are applicable to your account. For example, you can update your theme preferences (light or dark), change autocomplete speed, view current plan, and change font size.
The settings panel also gives you an option to download diagnostics, which are debug logs that can be helpful for the Devin Desktop team to debug an issue, should you encounter one.
## Telemetry
You may encounter issues with Chat if Telemetry is not enabled.
To enable telemetry, open your VS Code settings and navigate to User > Application > Telemetry. In the following dropdown, select "all".
To enable telemetry in JetBrains IDEs, open your Settings and navigate to Appearance & Behavior > System Settings > Data Sharing.
# Codemaps
Source: https://docs.devinenterprise.com/desktop/codemaps
Create shareable hierarchical maps of your codebase to visualize code execution flow and component relationships. Navigate and share with teammates.
Powered by a specialized agent, Codemaps are shareable artifacts that bridge the gap between human comprehension and AI reasoning, making it possible to navigate, discuss, and modify large codebases with precision and context.
## What are Codemaps?
While [DeepWiki](/desktop/deepwiki) provides symbol-level documentation, Codemaps help with codebase understanding by mapping how everything works together—showing the order in which code and files are executed and how different components relate to each other.
To navigate a Codemap, click on any node to instantly jump to that file and function. Each node in the Codemap links directly to the corresponding location in your code.
## Accessing Codemaps
You can access Codemaps in one of two ways:
* **Activity Bar**: Find the Codemaps interface in the Activity Bar (left side panel)
* **Command Palette**: Press `Cmd+Shift+P` (Mac) or `Ctrl+Shift+P` (Windows/Linux) and search for "Focus on Codemaps View"
In agent window mode, Codemaps open as editor tabs — the home view, a generation in progress, and each individual Codemap each get their own tab.
## Creating a Codemap
To create a new Codemap:
1. Open the Codemaps panel
2. Create a new Codemap by:
* Selecting a suggested topic (suggestions are based on your recent navigation history)
* Typing your own custom prompt
* Generating from a conversation: Create new Codemaps from the bottom of an agent conversation
3. The Codemap agent explores your repository, identifies relevant files and functions, and generates a hierarchical view
## Sharing Codemaps
You can share Codemaps with teammates as links that can be viewed in a browser.
For enterprise customers, sharing Codemaps requires opt-in because they need to be stored on our servers. By default, Codemaps are only available within your Team and require authentication to view.
## Using Codemaps with the agent
You can include Codemap information as context in your agent conversations by using `@-mention` to reference a Codemap. This works in the agent input for both Cascade and the [Devin Local agent](/desktop/devin-local).
# Command Overview
Source: https://docs.devinenterprise.com/desktop/command/plugins-overview
Use Devin Desktop Command for AI-powered inline code edits in VS Code and JetBrains. Generate or edit code with natural language prompts using Cmd/Ctrl+I.
**Devin Desktop Command** generates new or edits existing code via natural language inputs, directly in the editor window.
To invoke Command, press `⌘+I` on Mac or `Ctrl+I` on Windows/Linux.
From there, you can enter a prompt in natural language and hit the Submit button (or `⌘+⏎`/`Ctrl+⏎`) to forward the instruction to the AI.
Devin Desktop will then provide a multiline suggestion that you can accept or reject.
If you highlight a section of code before invoking Command, then the AI will edit the selection spanned by the highlighted lines.
Otherwise, it will generate code at your cursor's location.
You can accept, reject, or follow-up a generation by clicking the corresponding code lens above the generated diff,
or by using the appropriate shortcuts (`⌥+A`/`Alt+A`, `⌥+R`/`Alt+R`, and `⌥+F`/`Alt+F`, respectively).
To invoke Command, press `⌘+I` on Mac or `Ctrl+I` on Windows/Linux.
Some users have reported keyboard conflicts with this shortcut, so `⌘+⇧+I` and `⌘+\`on Mac (`Ctrl+⇧+I` and `Ctrl+\` on Windows/Linux)
will also work.
The Command invocation will open an interactive popup at the appropriate location in the code.
You can enter a prompt in natural language and Devin Desktop will provide a multiline suggestion that you can accept or reject.
If you highlight a section of code before invoking Command, then the AI will edit the selection spanned by the highlighted lines.
Otherwise, it will generate code at your cursor's location.
The Command popup will persist in the editor if you scroll around or focus your cursor elsewhere in the editor.
It will act on your most recently highlighted selection of code or your most recent cursor position.
While it is active, the Command popup gives you the following options:
* **Cancel** (`Esc`): this will close the popup and undo any code changes that may have occured while the popup was open.
* **Accept generation** (`⌘+⏎`): this option appears after submitting an instruction and receiving a generation.
It will write the suggestion into the code editor and close the popup.
* **Undo generation** (`⌘+⌫`): this option appears after submitting an instruction and receiving a generation.
It will restore the code to its pre-Command state without closing the popup, while reinserting your most recent instruction
into the input box.
* **Follow-up**: this option appears after submitting an instruction and receiving a generation.
You can enter a second (and third, fourth, etc.) instruction and submit it,
which will undo the currently shown generation and rerun Command using your comma-concatenated instruction history.
# Best Practices
Devin Desktop Command is great for file-scoped, in-line changes that you can describe as an instruction in natural language.
Here are some pointers to keep in mind:
* The model that powers Command is larger than the one powering autocomplete.
It is slower but more capable, and it is trained to be especially good at instruction-following.
* If you highlight a block of code before invoking Command, it will edit the selection. Otherwise, it will do a pure generation.
* Using Command effectively can be an art. Simple prompts like "Fix this" or "Refactor" will likely work
thanks to Devin Desktop's context awareness.
A specific prompt like "Write a function that takes two inputs of type `Diffable` and implements the Myers diff algorithm"
that contains a clear objective and references to relevant context may help the model even more.
# Refactors, Docstrings, and More
Source: https://docs.devinenterprise.com/desktop/command/related-features
Use Command-powered features like code lenses for refactoring, docstring generation, and Smart Paste for cross-language code translation.
Command enables streamlined experiences for a few common operations.
## Function Refactors and Docstring Generation
Above functions and classes, Devin Desktop renders *code lenses*,
which are small, clickable text labels that invoke Devin Desktop's AI capabilities on the labeled item.
You can disable code lenses by clicking the `✕` to the right of the code lens text.
The `Refactor` and `Docstring` code lenses in particular will invoke Command.
* If you click `Refactor`, Devin Desktop will prompt you with a dropdown of selectable, pre-populated
instructions that you can choose from. You can also write your own. This is equivalent to highlighting the function and invoking Command.
* If you click `Docstring`, Devin Desktop will generate a docstring for you above the function header.
(In Python, the docstring will be correctly generated *underneath* the function header.)
## Smart Paste
This feature allows you to copy code and paste it into a file in your IDE written in a different programming language.
Use `⌘+⌥+V` (Mac) or `Ctrl+Alt+V` (Windows/Linux) to invoke Smart Paste.
Behind the scenes, Devin Desktop will detect the language of the destination file and use Command to translate the code in your clipboard.
Devin Desktop's context awareness will try to write it to fit in your code, for example by referencing proper variable names.
Some possible use cases:
* **Migrating code**: you're rewriting JavaScript into TypeScript, or Java into Kotlin.
* **Pasting from Stack Overflow**: you found a utility function online written in Go, but you're using Rust.
* **Learning a new language**: you're curious about Haskell and want to see what your would look like if written in it.
# Command
Source: https://docs.devinenterprise.com/desktop/command/windsurf-overview
Use Devin Desktop Command (Cmd/Ctrl+I) for inline code generation and edits with natural language. No premium credits required.
**Command** generates new or edits existing code via natural language inputs, directly in the editor window.
Command does NOT consume any premium model credits.
To invoke Command, press `⌘+I` on Mac or `Ctrl+I` on Windows/Linux.
You can enter a prompt in natural language and hit the Submit button (or `⌘+⏎`/`Ctrl+⏎`) to forward the instruction to the AI.
If you highlight a section of code before invoking Command, then the AI will edit the selection spanned by the highlighted lines.
Otherwise, it will generate code at your cursor's location.
You can accept, reject, or follow-up a generation by clicking the corresponding code lens above the generated diff,or by using the appropriate shortcuts (`Cmd/Ctrl+Enter`/`Cmd/Ctrl+Delete`)
# Models
Command comes with its own set of models that are optimized for current-file edits.
Devin Desktop Fast is the fastest, most accurate model available.
# Terminal Command
You can use Command in the terminal (`Cmd/Ctrl+I`) to generate the proper CLI syntax using prompts in natural language.
# Best Practices
Command is great for file-scoped, in-line changes that you can describe as an instruction in natural language.
Here are some pointers to keep in mind:
* The model that powers Command is larger than the one powering autocomplete.
It is slower but more capable, and it is trained to be especially good at instruction-following.
* If you highlight a block of code before invoking Command, it will edit the selection. Otherwise, it will do a pure generation.
* Using Command effectively can be an art. Simple prompts like "Fix this" or "Refactor" will likely work
thanks to Devin Desktop's context awareness.
A specific prompt like "Write a function that takes two inputs of type `Diffable` and implements the Myers diff algorithm"
that contains a clear objective and references to relevant context may help the model even more.
# Code Lenses
Source: https://docs.devinenterprise.com/desktop/command/windsurf-related-features
Use Devin Desktop code lenses for quick Explain, Refactor, and Docstring operations on functions and classes directly in the editor.
## Explain, Refactor, and Add Docstring
At the top of the text editor, Devin Desktop exposes *code lenses* on functions and classes.
The `Explain` code lens will invoke the agent, which will simply explain what the function or class does and how it works.
The `Refactor` and `Docstring` code lenses in particular will invoke Command.
* If you click `Refactor`, Devin Desktop will prompt you with a dropdown of selectable, pre-populated
instructions that you can choose from. You can also write your own. This is equivalent to highlighting the function and invoking Command.
* If you click `Docstring`, Devin Desktop will generate a docstring for you above the function header.
(In Python, the docstring will be correctly generated *underneath* the function header.)
# Fast Context
Source: https://docs.devinenterprise.com/desktop/context-awareness/fast-context
Fast Context is a specialized subagent that retrieves relevant code from your codebase up to 20x faster using SWE-grep models for rapid code retrieval.
Fast Context is a specialized subagent in Devin Desktop that retrieves relevant code from your codebase up to 20x faster than traditional agentic search. It powers Cascade's ability to quickly understand large codebases while maintaining the intelligence of frontier models.
## Using Fast Context
When Cascade receives a query that requires code search, Fast Context will trigger automatically.
You'll notice Fast Context is working when:
* Cascade quickly identifies relevant files across your codebase
* Large codebase queries complete faster than before
* Cascade spends less time reading irrelevant code
## How It Works
Fast Context uses `SWE-grep` and `SWE-grep-mini`, custom models trained specifically for rapid code retrieval. These models combine the speed of traditional embedding search with the intelligence of agentic exploration.
When you make a query to Cascade that requires searching through your codebase, Fast Context automatically activates to:
1. Identify relevant files and code sections using parallel tool calls
2. Execute multiple searches simultaneously
3. Return targeted results in seconds rather than minutes
This approach prevents context pollution and aims to mitigate the traditional speed-accuracy tradeoff. By delegating retrieval to a specialized subagent, Cascade conserves its context budget and intelligence for the actual task at hand.
## SWE-grep Models
Fast Context is powered by the SWE-grep model family:
* **SWE-grep**: High-intelligence variant optimized for complex retrieval tasks
* **SWE-grep-mini**: Ultra-fast variant serving at over 2,800 tokens per second
Both models are trained using reinforcement learning to excel at parallel tool calling and efficient codebase navigation. They execute up to 8 parallel tool calls per turn over a maximum of 4 turns, allowing them to explore different parts of your codebase simultaneously.
The models use a restricted set of cross-platform compatible tools (grep, read, glob) to ensure consistent performance across different operating systems and development environments.
# Context Awareness Overview
Source: https://docs.devinenterprise.com/desktop/context-awareness/overview
Devin Desktop's RAG-based context engine indexes your codebase for intelligent suggestions. Learn about context pinning, knowledge base, and M-Query retrieval.
Devin Desktop's context engine builds a deep understanding of your codebase, past actions, and next intent.
Historically, code-generation approaches focused on fine-tuning large language models (LLMs) on a codebase,
which is difficult to scale to the needs of every individual user.
A more recent and popular approach leverages retrieval-augmented generation (RAG),
which focuses on techniques to construct highly relevant, context-rich prompts
to elicit accurate answers from an LLM.
We've implemented an optimized RAG approach to codebase context,
which produces higher quality suggestions and fewer hallucinations.
Devin Desktop offers full fine-tuning for enterprises, and the best solution
combines fine-tuning with RAG.
## Default Context
Out of the box, Devin Desktop takes multiple relevant sources of context into consideration.
* The current file and other open files in your IDE, which are often very relevant to the code you are currently writing.
* The entire local codebase is then indexed (including files that are not open),
and relevant code snippets are sourced by Devin Desktop's retrieval engine as you write code, ask questions, or invoke commands.
* For Pro users, we offer expanded context lengths, increased indexing limits, and higher limits on custom context and pinned context items.
* For Teams and Enterprise users, Devin Desktop can also index remote repositories.
This is useful for companies whose development organization works across multiple repositories.
## Knowledge Base (Beta)
Only available for Teams and Enterprise customers.
This feature allows teams to pull in Google Docs as shared context or knowledge sources for their entire team.
Currently, only Google Docs are supported. Images are not imported, but charts, tables, and formatted text are fully supported.
Configure knowledge base settings for your team. This page will only be visible with admin privileges.
Admins must manually connect with Google Drive via OAuth, after which they can add up to 50 Google Docs as team knowledge sources.
The agent will have access to the docs specified in the Devin Desktop dashboard. These docs do not obey individual user access controls, meaning if an admin makes a doc available to the team, all users will have access to it regardless of access controls on the Google Drive side.
### Best Practices
Context Pinning is great when your task in your current file depends on information from other files.
Try to pin only what you need. Pinning too much may slow down or negatively impact model performance.
Here are some ideas for effective context pinning:
* Module Definitions: pinning class/struct definition files that are inside your repo but in a module separate from your currently active file.
* Internal Frameworks/Libraries: pinning directories with code examples for using frameworks/libraries.
* Specific Tasks: pinning a file or folder defining a particular interface (e.g., `.proto` files, abstract class files, config templates).
* Current Focus Area: pinning the "lowest common denominator" directory containing the majority of files needed for your current coding session.
* Testing: pinning a particular file with the class you are writing unit tests for.
## Chat-Specific Context Features
When conversing with Devin Desktop Chat, you have various ways of leveraging codebase context,
like [@-mentions](/desktop/chat/overview#mentions) or custom guidelines.
See the [Chat page](/desktop/chat/overview) for more information.
## Frequently Asked Questions (FAQs)
### Does Devin Desktop index my codebase?
Yes, Devin Desktop does index your codebase. It also uses LLMs to perform retrieval-augmented generation (RAG) on your codebase using our own [M-Query](https://youtu.be/DuZXbinJ4Uc?feature=shared\&t=606) techniques.
Indexing performance and features vary based on your workflow and your Devin Desktop plan. For more information, please visit our [context awareness page](https://windsurf.com/context).
# Remote Indexing
Source: https://docs.devinenterprise.com/desktop/context-awareness/remote-indexing
Index remote repositories from GitHub, GitLab, and BitBucket for enterprise teams without storing code locally.
This feature is only available in the Devin Desktop Plugins for Enterprise plans.
While Local Indexing works great, the user may want to index codebases that they do not have stored locally for our models to take in as context.
For this use case, organizations on Teams and Enterprise plans can use Devin Desktop's Indexing Service to globally import all the relevant repositories. The indexing and embedding is then performed by Devin Desktop's servers (on an isolated tenant), and once the index is created, it is available to be queried by any member of the Team.
## Adding a repository
From [https://windsurf.com/indexing](https://windsurf.com/indexing) you can add a repository to index. Currently we support Git repositories from GitHub, GitLab, and BitBucket.
You can choose to index a particular branch and to automatically re-index the repository after some number of days.
## Security Guarantees
We clone the repository in order to create the index, but once we finish creating embeddings for the codebase we delete all the code and code snippets **assuming that the Store Snippets setting is unchecked.** We don't persist anything other than the embeddings themselves, from which you cannot derive the original code.
Furthermore, all indexing and embedding is performed on a single-tenant instance—nothing about the indexing process is shared between multiple Devin Desktop Teams customers.
# Devin Desktop Ignore
Source: https://docs.devinenterprise.com/desktop/context-awareness/windsurf-ignore
Configure which files and directories Devin Desktop should ignore during indexing using .devinignore or .codeiumignore files with gitignore-style syntax.
## WindsurfIgnore
By default, Devin Desktop Indexing will ignore:
* Paths specified in `gitignore`
* Files in `node_modules`
* Hidden pathnames (starting with ".")
When a file is ignored, it will not be indexed, and also does not count against the Indexing Max Workspace Size file counts.
Files included in .gitignore cannot be edited by the agent.
If you want to further configure files that Devin Desktop Indexing ignores, you can add a `.devinignore` file to your repo root, with the same syntax as `.gitignore`. The legacy `.codeiumignore` filename is also supported, and both can be used together. The agent additionally respects `.windsurfignore` files when accessing files.
### 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.
The global `.codeiumignore` file uses the same syntax as `.gitignore` and works in addition to any repository-specific ignore files.
## System Requirements
When first enabled, Devin Desktop will consume a fraction of CPU while it indexes the workspace. Depending on your workspace size, this should take 5-10 minutes, and only needs to happen once per workspace. CPU usage will return to normal automatically. Devin Desktop Indexing also requires RAM (\~300MB for a 5000-file workspace).
The "Max Workspace Size (File Count)" setting determines the largest workspace for which Devin Desktop Indexing will try to index a particular workspace / module. If your workspace does not appear to be indexed, please try adjusting this number higher. For users with \~10GB of RAM, we recommend setting this no higher than 10,000 files.
# Context Awareness for Devin Desktop
Source: https://docs.devinenterprise.com/desktop/context-awareness/windsurf-overview
Devin Desktop's RAG-based context engine indexes your codebase for intelligent code suggestions. Supports remote repositories for Teams and Enterprise.
Devin Desktop's context engine builds a deep understanding of your codebase, past actions, and next intent.
Historically, code-generation approaches focused on fine-tuning large language models (LLMs) on a codebase,
which is difficult to scale to the needs of every individual user.
A more recent and popular approach leverages retrieval-augmented generation (RAG),
which focuses on techniques to construct highly relevant, context-rich prompts
to elicit accurate answers from an LLM.
We've implemented an optimized RAG approach to codebase context,
which produces higher quality suggestions and fewer hallucinations.
Devin Desktop offers full fine-tuning for enterprises, and the best solution
combines fine-tuning with RAG.
## Default Context
Out of the box, Devin Desktop takes multiple relevant sources of context into consideration.
* The current file and other open files in your IDE, which are often very relevant to the code you are currently writing.
* The entire local codebase is then indexed (including files that are not open),
and relevant code snippets are sourced by Devin Desktop's retrieval engine as you write code, ask questions, or invoke commands.
* For Pro users, we offer expanded context lengths, increased indexing limits, and higher limits on custom context and pinned context items.
* For Teams and Enterprise users, Devin Desktop can also index remote repositories.
This is useful for companies whose development organization works across multiple repositories.
## Chat-Specific Context Features
When conversing with Devin Desktop Chat, you have various ways of leveraging codebase context,
like [@-mentions](/desktop/chat/overview#mentions) or custom guidelines.
See the [Chat page](/desktop/chat/overview) for more information.
## Frequently Asked Questions (FAQs)
### Does Devin Desktop index my codebase?
Yes, Devin Desktop does index your codebase. It also uses LLMs to perform retrieval-augmented generation (RAG) on your codebase using our own [M-Query](https://youtu.be/DuZXbinJ4Uc?feature=shared\&t=606) techniques.
Indexing performance and features vary based on your workflow and your Devin Desktop plan. For more information, please visit our [context awareness page](https://windsurf.com/context).
# C#, .NET, and CPP
Source: https://docs.devinenterprise.com/desktop/csharp-cpp
Setup guide for C#, .NET Core, .NET Framework (Mono), and C++ development in Devin Desktop using open-source tooling like OmniSharp, clangd, and LLDB.
# Devin Desktop Development Environment Setup Guide
## Overview
Devin Desktop workspaces rely **exclusively on open‑source tooling** for compiling, linting, and debugging. Microsoft's proprietary Visual Studio components cannot be redistributed, so we integrate community‑maintained language servers, debuggers, and compilers instead.
This guide covers two stacks:
1. **.NET / C#** – targeting both .NET Core and .NET Framework (via Mono)
2. **C / C++** – using clang‑based tooling
You can install either or both in the same workspace.
> ⚠️ **Important**: The examples below are templates that you must customize for your specific project. You'll need to edit file paths, project names, and build commands to match your codebase.
***
## 1. .NET / C# development
> **Choose the flavour that matches your codebase.**
### .NET Core / .NET 6+
**Extensions:**
* **[C#](https://marketplace.windsurf.com/vscode/item?itemName=muhammad-sammy.csharp)** (`muhammad-sammy.csharp`) – bundles **OmniSharp LS** and **NetCoreDbg**, so you can hit F5 immediately
* **[.NET Install Tool](https://marketplace.windsurf.com/vscode/item?itemName=ms-dotnettools.vscode-dotnet-runtime)** (`ms-dotnettools.vscode-dotnet-runtime`) – auto‑installs missing runtimes/SDKs
* **[Solution Explorer](https://marketplace.windsurf.com/vscode/item?itemName=fernandoescolar.vscode-solution-explorer)** (`fernandoescolar.vscode-solution-explorer`) – navigate and manage .NET solutions and projects
**Debugger:** Nothing else is required—the extension already contains the language server and an open‑source debugger suitable for .NET Core.
**Build:** `dotnet build`
### .NET Framework via Mono
**Extensions:**
* **[Mono Debug](https://marketplace.windsurf.com/vscode/item?itemName=ms-vscode.mono-debug)** (`ms-vscode.mono-debug`) – debug adapter for Mono ([Open VSX](https://open-vsx.org/extension/ms-vscode/mono-debug))
* **[C#](https://marketplace.windsurf.com/vscode/item?itemName=muhammad-sammy.csharp)** (`muhammad-sammy.csharp`) for language features
**Debugger:** **You must also install the Mono tool‑chain inside the workspace.** Follow the install guide in the [Mono repo](https://gitlab.winehq.org/mono/mono#compilation-and-installation). The debugger extension connects to that runtime at debug time.
> **⚠️ .NET Framework Configuration**: After installing Mono, to use the C# extension with .NET Framework projects, you need to toggle a specific setting in the IDE Settings. Go to **Settings** (in the C# Extension section) and toggle off **"Omnisharp: Use Modern Net"**. This setting uses the OmniSharp build for .NET 6, which provides significant performance improvements for SDK-style Framework, .NET Core, and .NET 5+ projects. Note that this version *does not* support non-SDK-style .NET Framework projects, including Unity.
**Build:** `mcs Program.cs`
### Configure `tasks.json` for Your Project
**You must create/edit `.vscode/tasks.json` in your workspace root** and customize these templates:
```jsonc theme={null}
{
"version": "2.0.0",
"tasks": [
{
"label": "build-dotnet",
"type": "shell",
"command": "dotnet",
"args": ["build", "YourProject.csproj"], // ← Edit this
"group": "build",
"problemMatcher": "$msCompile"
},
{
"label": "build-mono",
"type": "shell",
"command": "mcs",
"args": ["YourProgram.cs"], // ← Edit this
"group": "build"
}
]
}
```
### Configure `launch.json` for Debugging
**You must create/edit `.vscode/launch.json` in your workspace root** and update the paths:
```jsonc theme={null}
{
"version": "0.2.0",
"configurations": [
{
"name": ".NET Core Launch",
"type": "coreclr",
"request": "launch",
"preLaunchTask": "build-dotnet",
"program": "${workspaceFolder}/bin/Debug/net6.0/YourApp.dll", // ← Edit this path
"cwd": "${workspaceFolder}",
"args": [] // Add command line arguments if needed
},
{
"name": "Mono Launch",
"type": "mono",
"request": "launch",
"preLaunchTask": "build-mono",
"program": "${workspaceFolder}/YourProgram.exe", // ← Edit this path
"cwd": "${workspaceFolder}"
}
]
}
```
### CLI equivalents
```bash theme={null}
# .NET Core
$ dotnet build
$ dotnet run
# Mono / .NET Framework
$ mcs Program.cs
$ mono Program.exe
```
### .NET Framework Limitations
⚠️ **Important**: .NET Framework codebases with mixed assemblies (C++/CLI) or complex Visual Studio dependencies have significant limitations in Devin Desktop. These codebases typically require Visual Studio's proprietary build system and cannot be fully compiled or debugged in Devin Desktop due to dependencies on Microsoft-specific tooling and assembly reference resolution.
**Recommended approaches for .NET Framework projects:**
* Use Devin Desktop alongside Visual Studio for code generation and editing
* Migrate compatible portions to .NET Core where possible
***
## 2. C / C++ development
**Required Extensions:**
| Extension | Purpose |
| ---------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **[Windsurf C++ Tools](https://open-vsx.org/extension/Codeium/windsurf-cpptools)** (`Codeium.windsurf-cpptools`) | This is a bundle of the three extensions we recommend using to get started. Package that contains C/C++ LSP support, debugging support, and CMake support. |
> **Note:** Installing the Windsurf C++ Tools bundle will automatically install the individual extensions listed below, so you only need to install the bundle.
| Extension | Purpose |
| --------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| **[clangd](https://marketplace.windsurf.com/vscode/item?itemName=llvm-vs-code-extensions.vscode-clangd)** (`llvm-vs-code-extensions.vscode-clangd`) | **clangd** language‑server integration. If `clangd` is missing it will offer to download the correct binary for your platform. |
| **[CodeLLDB](https://marketplace.windsurf.com/extension/vadimcn/vscode-lldb)** (`vadimcn.vscode-lldb`) | Native debugger based on LLDB for C/C++ and Rust code. |
| **[CMake Tools](https://marketplace.windsurf.com/vscode/item?itemName=ms-vscode.cmake-tools)** (`ms-vscode.cmake-tools`) | Project configuration, build, test, and debug integration for **CMake**‑based projects. |
For non‑CMake workflows you can still invoke `make`, `ninja`, etc. via custom `tasks.json` targets.
### Configure C/C++ Build Tasks
**Create/edit `.vscode/tasks.json`** for your C/C++ project:
```jsonc theme={null}
{
"version": "2.0.0",
"tasks": [
{
"label": "build-cpp",
"type": "shell",
"command": "clang++",
"args": ["-g", "main.cpp", "-o", "main"], // ← Edit for your files
"group": "build",
"problemMatcher": "$gcc"
}
]
}
```
***
## 3. Notes & Gotchas
* **Open‑source only** – decline any prompt to install proprietary Microsoft tooling; Devin Desktop containers cannot ship it.
* **Container vs Host** – SDKs/compilers must be present **inside** the Devin Desktop workspace container.
* **Keyboard shortcuts**
* Ctrl/⌘ + Shift + B → compile using the active build task
* F5 → debug using the selected `launch.json` config
***
## 4. Setup Checklist
* Install the required extensions for your language stack
* **Create and customize** `.vscode/tasks.json` with your project's build commands
* **Create and customize** `.vscode/launch.json` with correct paths to your executables
* For Mono: install the runtime and verify `mono --version`
* Update file paths, project names, and build arguments to match your codebase
* Test your setup: Press Ctrl/⌘ + Shift + B to build, then F5 to debug
> 💡 **Tip**: The configuration files are project-specific. You'll need to adapt the examples above for each workspace.
# DeepWiki
Source: https://docs.devinenterprise.com/desktop/deepwiki
Get AI-powered explanations of code symbols with DeepWiki. Hover over functions, variables, and classes to understand unfamiliar code in your codebase.
We've implemented [Devin's DeepWiki feature](/work-with-devin/deepwiki) inside of the Devin Desktop Editor. Use it to get up to speed on unfamiliar parts of your codebase.
You can find the DeepWiki interface in the Primary Side Bar / Activity Bar.
To use DeepWiki, hover over a symbol in your codebase and press `Cmd+Shift+Click` to open detailed explanations of code symbols.
Unlike classical hover cards that just show basic type information, DeepWiki-powered hover explains functions, variables, and classes as you read through code.
You can send the DeepWiki explanation to Cascade as an `@-mention` by clicking the `⋮` button in the top right of the DeepWiki panel and selecting `Add to Cascade`.
# Devin in Devin Desktop
Source: https://docs.devinenterprise.com/desktop/devin
Delegate work to Devin, an autonomous cloud agent, directly from Devin Desktop — and review its PRs without leaving your editor.
[Devin](https://devin.ai/) is an autonomous software engineering agent that runs in the cloud. With Devin Desktop 2.0, Devin is built directly into Devin Desktop so you can delegate work to the cloud and review the results without leaving your editor.
Devin is included with every self-serve Devin Desktop plan (Pro, Max, Teams). Enterprise users should reach out to their admin for help.
Access to Devin Cloud is rolling out gradually. If you don't see Devin Cloud, try logging out and logging in to Devin Desktop.
## What Devin does
Devin handles complex tasks end to end — debugging, deployment, testing, and more. Each Devin session runs on its own VM with a desktop, browser, and computer use, so it can keep working after you close your laptop.
## Devin pricing
For self-serve users, Devin is included with your existing Devin Desktop plan and will directly consume the shared quota and extra usage balance from Devin Desktop.
When you first [connect your GitHub to Devin](/integrations/gh), you will be granted up to \$50 in extra usage credits to try out Devin. The exact amount depends on the maturity of your GitHub account.
## Delegating work to Devin
You can work on a plan with a local agent and, with a single click, send it to Devin for implementation. Devin spins up its own machine and gets to work while you keep coding locally — or close your laptop and come back later.
## Working in a Devin session
Devin sessions in Devin Desktop stay in sync with the [web app](https://app.devin.ai):
* **Send queue** — press `Cmd/Ctrl+Enter` to queue your next message on the server rather than sending it immediately. Because the queue lives server-side, it survives reloads and shows up in the web app too.
* **Participant names** — in multi-user (Slack) sessions, each message shows the name of the participant who sent it.
* **Copy link** — grab a link to the session from the session menu to share it or open it in the web app.
If the connection to Devin Cloud drops, the session shows a **Remote ACP is disconnected** banner with a **Reconnect** button.
## Where Devin shows up
Devin sessions appear alongside your local agent sessions in the [Agent Command Center](/desktop/agent-command-center), and can be organized into [Spaces](/desktop/spaces) along with everything else related to a task.
Manage every agent — local and cloud — in one Kanban view.
Group sessions, PRs, files, and context for a task.
## Admin Controls
Enterprise admins need to turn on access to Devin for their enterprise to use Devin. Admins can enable Devin for their enterprise from the Admin Portal. See the [Guide for Admins](/desktop/guide-for-admins#3-1-admin-portal-overview) for more details.
# Devin Desktop FAQ
Source: https://docs.devinenterprise.com/desktop/devin-desktop-faq
Frequently asked questions about the transition from Windsurf to Devin Desktop.
On June 2, 2026, Windsurf is becoming Devin Desktop. This FAQ covers what's changing, what's not, and what it means for your team.
## What is Devin Desktop?
Devin Desktop is the new name for Windsurf. It's the same IDE, same editor, and has the same features, but **unified under the Devin brand**. If you've been using Windsurf 2.0, you've already been using what will become Devin Desktop.
The Agent Command Center (Spaces, Kanban view, multi-agent management) is now front and center. The classic Windsurf experience (editor, extensions, keybindings, workflows, LSPs) is still there and fully accessible. Nothing is getting removed.
## When is this happening?
June 2, 2026. Devin Desktop will be delivered as a regular over-the-air update. You'll receive a heads up that the experience is changing.
## What's changing?
Windsurf becomes Devin Desktop, with the Agent Command Center as the primary view. The full Windsurf IDE is still available, with all the features you know and love - and all your existing work and progress will remain intact. No ongoing work will have any interruptions, and after a quick orientation, the interface will feel immediately familiar.
## Why is this happening?
We're unifying all of our products under the Devin brand: Devin Cloud, Devin Desktop, Devin CLI, and Devin Review. We believe the future of software engineering is managing teams of agents (local and cloud) working alongside you. Devin Desktop is the command center for that and where we expect developers to spend 90%+ of their days.
## Does my plan or pricing change?
No. Your current plan continues to work exactly as it does today. Pricing is unchanged. This applies to all plan types, including legacy Windsurf Enterprise plans.
## How do I get Devin Desktop on the Teams plan?
Devin Desktop is available to users with full seats. On the Teams plan, add a full seat to unlock Devin Desktop and \$40/month of usage that works across all Devin products (Devin Cloud, Devin Desktop, Devin CLI, and Devin Review).
## Do I need to use Devin to use Devin Desktop?
No - you can continue using Devin Desktop with local-only agents.
## Do I need to upgrade to the Cognition Platform Plan, or switch my billing to ACUs?
No. Devin Desktop works out of the box for all existing Windsurf users, including legacy Enterprise customers. Devin Cloud remains a separate SKU. If you're interested in Devin Cloud, talk to your account team.
## What happens to my settings and configuration?
All of your Windsurf settings will be ported to Devin Desktop automatically. Devin Local also inherits your Windsurf settings. If you're on a legacy Windsurf plan, you can still use windsurf.com to manage your settings.
## Will I lose access to anything?
No. The Windsurf IDE, your extensions, your workflows and everything is still there. Your plan, pricing, and access remain the same. Only the name and branding are changing.
For details on how the new [Devin Local](/desktop/devin-local) agent handles features like memories and workflows, see its [limitations](/desktop/devin-local#limitations).
## Are my Windsurf rules still supported? What about Devin rules?
Yes. Devin Desktop continues to read all of your existing Windsurf rules, and adds support for the new `.devin/` equivalents. Nothing you have today needs to change.
Both rule formats are supported side by side:
* **Single-file rules:** the legacy `.windsurfrules` file at your workspace root is still read. (There is no `.devinrules` single-file equivalent — use the directory format below for new rules.)
* **Directory rules:** individual `.md` rule files under a `rules/` directory. `.devin/rules/` is the preferred location and **takes precedence**, with `.windsurf/rules/` kept as a fallback for backward compatibility.
In addition, Devin Desktop reads rules from `AGENTS.md` / `agents.md` files, and can import `.cursor/rules` (`.mdc`) into `.devin/rules/`. Directory-based rules support activation triggers in their frontmatter (always-on, model-decision, glob-based, and manual), so a rule can apply to every request, only when the model decides it's relevant, only for files matching a glob, or only when invoked manually.
Enterprise admins can also deploy rules system-wide; see [System-level configuration](#system-level-configuration-admin-managed-per-machine) below.
## What is Devin Local?
[Devin Local](/desktop/devin-local) is a new local agent available in Devin Desktop. It's more efficient than Cascade, supports subagents, and runs the same architecture as Devin CLI. Devin Local inherits your existing Windsurf settings.
## What happens to Cascade?
The local agent is also being brought under the Devin brand and will be called [Devin Local](/desktop/devin-local), and comes with an improved harness, up to 30% better token efficiency, subagent support, and sandboxing. The existing Cascade agent remains available through July.
Enterprise customers should work with their account team for the transition to Devin Local.
## Will my pricing change when switching to Devin Local?
No, Devin Local inside Windsurf or Devin Desktop uses the exact same pricing model as Cascade: if you are currently using prompt-based credits, you will continue to do so.
## What about Windsurf JetBrains?
The Windsurf JetBrains plugin is not affected by this change and will continue to work as expected (and will keep its name).
## What happened to the `surf` command? How do I open a file from the terminal?
The `surf` shell command has been replaced by the `devin-desktop` command. To install it, open the command palette in Devin Desktop and run **Shell Command: Install 'devin-desktop' command in PATH**. You can then open a file or folder from your terminal the same way you used `surf`:
```bash theme={null}
devin-desktop path/to/file
devin-desktop .
```
The legacy `surf` (and `windsurf`) commands still ship in `~/.codeium/windsurf/bin/` for backward compatibility. If you have scripts or muscle memory tied to `surf`, you can keep using it by aliasing it to the new command:
```bash theme={null}
alias surf="devin-desktop"
```
## What happens with previous Windsurf releases?
As a general rule, we consider every release but the latest to be deprecated, although we do our best to maintain compatibility and not break previous versions. This follows the same model as Microsoft's VSCode. You will be able to continue to download previous Windsurf releases, although we don't recommend it.
## Can our admins test this before the rollout?
Yes. We're happy to share an early build with your admins in the week before June 2 so they can validate the change in your environment ahead of the org-wide rollout. Reach out to your account team to coordinate.
## Will we need to update our network allowlist?
No network changes are required.
For **Cognition Platform** users who log in via devinenterprise.com, all authentication and settings will be managed from the Devin website.
For **Legacy Windsurf Enterprises**, no changes are strictly required. Updates and binaries will continue to be stored on [`codeiumdata.com`](http://codeiumdata.com) and login will continue to happen on `windsurf.com/enterprise`. The only change is that **user-facing website content** (the changelog and documentation) will be moving to a Devin subdomain (`docs.devin.ai`). If you want your team to keep access to the changelog and docs, add `docs.devin.ai` or [`docs.devinenterprise.com`](http://docs.devinenterprise.com) to your allowlist (or `.devin.ai` / `.devinenterprise.com` if you use wildcard rules).
## What is the full list of hostnames we should allow?
No allowlist changes are required before launch.
If you prefer to allowlist proactively, these are the relevant hostnames:
**For all customers, Devin Desktop requires (backend domains):**
* `.codeiumdata.com`
* `update.windsurf.com`
* `.windsurf.com`
* `.codeium.com`
* `.googleapis.com` (authentication)
* `apis.google.com` (authentication)
* `static.devin.ai`
**Cognition Platform customers additionally require (backend domains):**
* `app.devin.ai` (webapp, session URLs, and resource downloads)
* `api.devin.ai` (API backend and the ACP live WebSocket)
If you use wildcard rules, `.devin.ai` covers both. Cognition Platform customers on a `devinenterprise.com` domain should allowlist the equivalent hosts (or `.devinenterprise.com`).
**User-accessible domains (changelog, documentation, and support):**
* `docs.devin.ai` or `docs.devinenterprise.com` (changelog and documentation, after June 2, 2026)
* `decagon.ai` (support)
## What hostnames does the desktop application use for automatic updates?
The desktop application checks for and downloads OTA (over-the-air) updates automatically. The update system uses two types of requests:
1. **Update check API:** the application periodically contacts the update server to see if a new version is available.
1. **Some users disable this feature**
2. **Binary download:** when an update is found, the application downloads the new installer or archive from a CDN.
The relevant hostnames are used by **all customers** (both Legacy Windsurf and Cognition Platform):
* `update.windsurf.com` — update check API
* `windsurf-stable.codeiumdata.com` — binary downloads for the stable and next channels
If your firewall or proxy rules are domain-based, ensure these hostnames are reachable on port 443 (HTTPS). Blocking them will prevent the application from detecting or installing updates.
## What hostnames are used for remote development (SSH, Dev Containers)?
When connecting to a remote machine via SSH or Dev Containers, the desktop application downloads the Remote Extension Host (REH) and CLI binaries to the remote machine. These hostnames are required for **all customers** (both Legacy Windsurf and Cognition Platform):
* `windsurf-stable.codeiumdata.com` — REH and CLI archives (stable/next channels)
* `windsurf-nightly.codeiumdata.com` — REH and CLI archives (insiders channel)
The remote machine must be able to reach these hostnames on port 443. If your remote servers are behind a corporate proxy or airgapped network, ensure these domains are reachable or pre-stage the REH bundle manually.
## Will the app name change affect our device management (MDM) policies?
Yes - this is the most important item for IT and endpoint security teams. The desktop application name is changing from **Windsurf** to **Devin** (appearing as `Devin.app` on macOS, `Devin.exe` on Windows, and `Devin` / `devin` on Linux). Many organizations use central device management (MDM / endpoint management) policies that flag or block any application that isn't explicitly approved, so a policy that only allows "Windsurf" today may flag or block the renamed application after the June 2 update.
**Action required:** Before June 2, 2026, add **Devin** to the allowlist in your device management / endpoint management policies, and confirm with your endpoint security team that the renamed application is approved. Please make sure this reaches the team that actually owns these policies - in many enterprises that team is separate from the one managing the IDE rollout.
## What local file paths does the application read from and write to?
Devin Desktop reads from both legacy (Windsurf/Codeium) and new (Devin) file paths during the transition period, and writes new data to the Devin paths. Enterprise admins managing endpoint policies, file integrity monitoring, or data-loss-prevention rules should be aware of the following directories.
All data from legacy paths will be copied over to new paths when Devin Desktop runs for the first time.
### Per-user IDE data (settings, extensions, workspaces)
This is the VS Code-derived user data directory. If the new path exists, we will read from it:
| OS | Legacy path (read) | New path (read + write) |
| ------- | ----------------------------------------- | -------------------------------------- |
| macOS | `~/Library/Application Support/Windsurf/` | `~/Library/Application Support/Devin/` |
| Windows | `%APPDATA%\Windsurf\` | `%APPDATA%\Devin\` |
| Linux | `~/.config/Windsurf/` | `~/.config/Devin/` |
Contains: `User/settings.json`, `User/keybindings.json`, `User/snippets/`, `globalStorage/`, `Workspaces/`, `argv.json`
### Per-user extensions directory
Extensions are stored in the dot-folder derived from the product name. Legacy paths will remain read-only:
| Legacy path (read) | New path (read + write) |
| ------------------------- | ----------------------- |
| `~/.windsurf/extensions/` | `~/.devin/extensions/` |
### Per-user configuration directory
The primary user-level configuration directory stores user settings, MCP config, global skills, and workflows:
| Purpose | Path |
| ---------------- | --------------------------------------- |
| User settings | `~/.codeium/user_settings.pb` |
| MCP config | `~/.codeium/mcp_config.json` |
| Global workflows | `~/.codeium/windsurf/global_workflows/` |
| Global skills | `~/.codeium/windsurf/skills/` |
| CLI binaries | `~/.codeium/windsurf/bin/` |
The `~/.codeium/` directory structure is not changing in this release. These paths remain the same.
### System-level configuration (admin-managed, per-machine)
Enterprise admins can deploy rules, workflows, and skills system-wide in these directories:
| OS | Legacy path (read) | New path (read + write) |
| ------- | ---------------------------------------- | ------------------------------------- |
| macOS | `/Library/Application Support/Windsurf/` | `/Library/Application Support/Devin/` |
| Windows | `C:\ProgramData\Windsurf\` | `C:\ProgramData\Devin\` |
| Linux | `/etc/windsurf/` | `/etc/devin/` |
Contains subdirectories: `rules/`, `workflows/`, `skills/`
### CLI / shell command binaries
| OS | Path | Binary names |
| ------------- | --------------------------- | ----------------------------------------------------- |
| macOS / Linux | `~/.codeium/windsurf/bin/` | `devin-desktop`, `surf` (legacy), `windsurf` (legacy) |
| macOS / Linux | `~/.local/bin/` | `devin` |
| Windows | `%LOCALAPPDATA%\devin\bin\` | `devin.exe` |
### Workspace-level directories (inside repositories)
The application already supports `.devin/` as the primary workspace directory and falls back to `.windsurf/` for backward compatibility. No admin action is needed for these:
| Legacy (read, fallback) | New (read + write, preferred) | Contents |
| ------------------------------------ | ------------------------------------------------ | ----------------------------------------- |
| `.windsurfrules` (root file) | `.devin/rules/` (directory) | Project rules (single-file legacy format) |
| `.windsurf/rules/` | `.devin/rules/` | Project rules |
| `.windsurf/workflows/` | `.devin/workflows/` | Workflows |
| `.windsurf/skills/` | `.devin/skills/` | Skills |
| `.windsurf/plans/` | `.devin/plans/` | Plans |
| `.codeiumignore` / `.windsurfignore` | `.codeiumignore` (unchanged) / `.windsurfignore` | Ignore patterns |
## What should endpoint security / DLP policies allow?
If your organization uses endpoint security tools that restrict which directories applications can read from or write to, ensure the following paths are permitted for the Devin Desktop application:
* **macOS:** `~/Library/Application Support/Devin/`, `~/.devin/`, `~/.codeium/`, `~/.windsurf/`, `~/.local/bin/devin`
* **Windows:** `%APPDATA%\Devin\`, `%LOCALAPPDATA%\devin\`, `~\.codeium\`, `~\.windsurf\`
* **Linux:** `~/.config/Devin/`, `~/.devin/`, `~/.codeium/`, `~/.windsurf/`, `/etc/devin/`, `~/.local/bin/devin`
The application also uses the system temp directory (`$TMPDIR` / `%TEMP%`) for ephemeral data.
## What hostnames does Devin CLI use for updates?
The Devin CLI has its own update mechanism, separate from the desktop application. This change will have no impact to Devin CLI.
## I have more questions. Who should I contact?
Reach out to your account team or customer support.
# Devin Local Agent
Source: https://docs.devinenterprise.com/desktop/devin-local
Use the same agent harness as Devin CLI directly inside Devin Desktop.
Devin Local is our next-generation agent harness shared with [Devin CLI](https://cli.devin.ai).
It operates on your machine with access to your local files, tools, and environment and is the primary local agent for Devin Desktop.
Previously using Cascade? Run the **Devin: Open Cascade Migration Wizard** command from the command palette to bring your workflows and memories over in one guided flow.
## Key improvements
In the time since Cascade first launched, model capabilities have evolved significantly. Devin Local is built from the ground up to efficiently leverage these advancements.
### Token efficiency
The Devin Local agent is significantly more token-efficient, with a greater focus on prompt caching. Most tasks take up to 30% fewer tokens than Cascade to accomplish the same result.
### Subagents
The Devin Local agent can spawn independent [subagents](/cli/subagents) to handle subtasks — either in the foreground or background. Subagents share tools and codebase context with the parent agent but operate in their own conversation chain.
Subagents are controlled by the **Subagents (Preview)** toggle in `Devin Settings`.
Beyond the built-in profiles, you can define your own subagents as markdown files under `agents/` using either layout:
* **Flat file** — `agents/.md`, where the file name becomes the profile's identifier.
* **Directory** — `agents//AGENT.md`, where the directory name becomes the profile's identifier.
See the [subagents documentation](/cli/subagents) for where these directories are discovered and how to configure a profile.
### Sandboxing
The Devin Local agent supports OS-level sandboxing. When enabled, the sandbox enforces:
* **Filesystem isolation** — writable paths are derived from your permission scopes, and `Read(...)` deny rules hide paths from sandboxed commands
* **Network filtering** — domain allowlists and denylists control what the agent can reach
Enterprise admins can enforce sandbox behavior across the organization through [team settings](https://cli.devin.ai/docs/enterprise/team-settings#sandbox-enforcement), including requiring sandbox mode for all users and configuring organization-wide domain filtering rules.
### Quick Review
[Quick Review](/desktop/quick-review) is a dedicated subagent available with the Devin Local agent to get rapid feedback on changes.
## Switching your agent
New tabs start with Devin Local when you haven't chosen a preferred agent (falling back to Cascade if Devin Local isn't available to you). You can change the agent for *new* conversations at any time via the agent selector in the bottom right corner of Devin Desktop — Devin Local is selectable even while it is still connecting.
### Agent settings
If Devin Local doesn't appear in the agent selector, you might need to enable it from `Devin Settings`:
1. Open the Command Palette with `Cmd+Shift+P` (macOS) or `Ctrl+Shift+P` (Windows/Linux)
2. Open `Devin User Settings`
3. Click the "Agents" tab
4. Toggle the "Devin Local" agent on
5. Restart Devin Desktop
You can also choose to disable Cascade entirely with the `devin.cascade.enabled` setting.
### Enterprise admins
Devin Local is a bundled agent that Devin Desktop fetches from the server. Whether it appears in the agent selector is controlled by the **Devin Local Agent** team setting:
* On **Team** and other non-enterprise plans it is available by default (unless an individual member has this access disabled).
* On **Enterprise** plans it is gated, so an admin must turn it on for members.
Enterprise admins manage this from the team settings dashboard:
* **Devin Enterprise admins** — **Settings → Enterprise → Windsurf** (`app.devin.ai/org/{orgName}/settings/windsurf`). Under **Features**, enable **Devin Local Agent** ("Allow members to use the Devin Local agent in Devin Desktop and delegate tasks to Devin's terminal agent via ACP").
* **Windsurf Enterprise admins** — the [Windsurf dashboard](https://windsurf.com/team/settings).
Once enabled, Devin Local appears in the agent selector for all members after they restart Devin Desktop — no per-user setup or custom [ACP registry config](/desktop/acp#team-registry-configuration) is required.
## Modes
Devin Local has its own modes, separate from [Cascade's modes](/desktop/cascade/modes). Because it shares the agent harness with Devin CLI, it uses the same agent modes (Normal, Plan, and Ask) and the same [permission modes](/cli/reference/permissions). See [essential commands](/cli/essential-commands) for the full mode set and the slash commands that switch between them.
### Plan mode
Plan mode is read-only research: the agent investigates your codebase, writes up an approach, and asks for your approval before implementing anything.
The plan is written to a persistent Markdown file at `~/.devin/plans/plan-.md`, so you can edit it, come back to it later, or hand it to a fresh session.
Include the keyword `megaplan` (`ultraplan` and `masterplan` also work) in your prompt to switch the session into Plan mode and have the agent plan much more thoroughly — it asks at least one clarifying question before writing the plan.
## Worktree sessions
You can run a Devin Local session inside a git worktree, so the agent can edit, build, and test without touching your main workspace.
Pick the location from the agent location selector when starting a session:
* **New worktree** — Devin Desktop creates a fresh worktree for the session.
* **Existing worktree** — choose one you already have from the selector's **Local** submenu.
Once the agent is done, click **Merge** on the session to bring the worktree's changes back into your workspace.
Worktrees are shared with Cascade sessions, including their on-disk location and cleanup behavior — see [worktrees](/desktop/cascade/worktrees).
## Customizations
The customizations surface lists everything a Devin Local session has loaded — rules, skills, hooks, MCP servers, and plugins — along with what your repository, organization, and account offer.
You can open it with **Open customizations** from the new-tab menu in an agent space, or from the right-click menu on a Devin Local session in the agent sidebar.
**Plugins** here means Devin *agent* plugins: installable bundles that contribute skills, rules, hooks, MCP servers, and subagents to the agent. See [plugins](/cli/extensibility/plugins/overview).
They are unrelated to [Windsurf Plugins](/windsurf/plugins/getting-started), which bring Devin to JetBrains, VS Code, and other editors, or to the [editor extensions](/desktop/recommended-extensions) you install inside Devin Desktop — both of those extend the IDE rather than the agent.
## Restricted Mode
When a workspace is open in **Restricted Mode**, agents are unavailable in it: Cascade, Devin Local, and every [ACP agent](/desktop/acp) are disabled, and [hooks](/cli/extensibility/hooks/overview) neither load nor run.
Agents become available again once the workspace is no longer in Restricted Mode.
## Differences
### Permissions model
Devin Local replaces [auto-execution levels](/desktop/terminal#auto-execution-levels) with a more fine-grained permissions system to control which actions the agent can take:
* **Deny** rules block actions entirely (highest priority)
* **Ask** rules always prompt for approval
* **Allow** rules auto-approve actions without prompting
Permissions can be scoped to file reads, file writes, command execution, HTTP fetches, and MCP tools. They can be configured at the project, user, or organization level. See [permissions](/cli/reference/permissions) for the rule syntax.
Permission rules written with globs (for example `Read(**/*.pem)`) match against every workspace directory in the session, including directories added after it started.
#### Responding to permission requests
When the agent asks for approval, the request card offers a few ways to answer:
* **Edit the command** — click the command in the card to change it before approving. The wand action lets you describe the change you want in plain language and has a fast model rewrite the command for you to review.
* **Keyboard shortcuts** — approve, always-allow, or reject a request without reaching for the mouse. The shortcut hints are shown on the buttons and dropdown entries.
* **Session-wide grants** — an approval you grant for the session applies to every later request in that session, so the root agent and its subagents don't re-prompt for a scope you already granted.
### MCP permissions
Unlike Cascade, the default configuration of the Devin Local agent prompts for approval before calling any MCP tool. When the agent wants to invoke an MCP tool, you can allow the specific tool or every tool on that MCP server, either for the current session or permanently.
Enterprise admins can default-allow specific MCP servers or tools so that trusted integrations don't prompt every time. See [tool-based permissions](/cli/reference/permissions#tool-based-permissions) for how to configure these rules.
### MCP re-authentication
When a server's stored OAuth credentials expire, it shows a **Needs auth** state in the Devin Local MCP list, on its marketplace card, and on the server detail page.
Click **Authenticate** to clear the stored credentials and re-run the browser authorization flow.
### MCP server configuration
With the Devin Local agent, MCP servers are configured via [config files](https://cli.devin.ai/docs/extensibility/mcp/configuration) on your local machine.
The file location is determined by the scope:
| Scope | Location | Shared with team? |
| -------------- | ----------------------------- | ---------------------------------- |
| Project | `.devin/config.json` | Yes (checked into version control) |
| Local override | `.devin/config.local.json` | No (gitignored) |
| User | `~/.config/devin/config.json` | No |
## Skills
Skills are reusable, model-invoked bundles of instructions (and optional scripts) that extend what the Devin Local agent can do. Because Devin Local shares the same agent harness as [Devin CLI](https://cli.devin.ai), it uses the same skills format and discovery mechanism.
Skills are also the recommended way to migrate Cascade memories and workflows, which aren't supported by the Devin Local agent (see [Limitations](#limitations)) — capture a repeatable procedure once and the agent invokes it automatically when relevant.
See the [Devin CLI skills documentation](/cli/extensibility/skills/overview) for details on how to create, configure, and scope skills.
## Limitations
The gap runs both ways: [plugins](/cli/extensibility/plugins/overview) and [subagents](/cli/subagents) have no Cascade equivalent at all, and recent releases brought [plan mode](/desktop/devin-local#plan-mode) and [merging worktree sessions](/desktop/devin-local#worktree-sessions) to parity with Cascade. The list below covers the Cascade features this agent does not have yet.
The following features are not currently supported with the Devin Local agent:
* **Memories** — The Devin Local agent does not persist memories between sessions. Migrate your critical memories to [skills](/desktop/cascade/skills) with the **Devin: Open Cascade Migration Wizard** command.
* **Workflows** — Workflows are not available with the Devin Local agent. Migrate your workflows to [skills](/desktop/cascade/skills) with the **Devin: Open Cascade Migration Wizard** command.
* **Code Lenses** - Currently [code lenses](/desktop/command/windsurf-related-features) do not yet trigger the Devin Local agent.
* **App Deploys** - The Devin Local agent does not support app deploys.
* **Conversation Sharing** - Conversation sharing is not yet available with the Devin Local agent.
* **Arena Mode** - [Arena mode](/desktop/cascade/arena) is not available with the Devin Local agent.
The Devin Local agent does support [rules and AGENTS.md files](https://cli.devin.ai/docs/extensibility/rules) as well as [skills](https://cli.devin.ai/docs/extensibility/skills/overview) for providing persistent context and reusable workflows.
### Analytics
Devin Local activity is reported in the [`cascade_runs`](/desktop/accounts/api-reference/cascade-analytics) data source (model usage, messages sent, and credit consumption), the [`cascade_tool_usage`](/desktop/accounts/api-reference/cascade-analytics) data source (per-tool call counts such as Code Edit, Run Command, Search Web, and MCP Tool), the [`cascade_lines`](/desktop/accounts/api-reference/cascade-analytics) data source (daily lines of code written by the agent), and the [Cascade Data source](/desktop/accounts/analytics-api#cascade-data) of the Custom Analytics API.
Unlike Cascade, Devin Local does not track specific suggested lines or "modes" when operating: an edit only runs after you approve it, so accepted lines equal suggested lines, and the `mode` field in `cascade_runs` is not populated.
The Devin CLI does not report analytics for [hybrid deployments](https://devin.ai/blog/self-hosted-deployment-maintenance-mode).
### Enterprise controls
Enterprise admins can configure the Devin Local agent through [team settings](https://windsurf.com/team/settings), including [new controls only available with the Devin Local agent](https://cli.devin.ai/docs/enterprise/team-settings):
* **Sandbox enforcement** - Require sandbox mode for all users and configure organization-wide domain filtering rules
* **Granular permissions** - Control which actions the agent can take with more fine-grained permissions
* **Network enforcement** - Control network access with allowed and denied domains
Additionally, the "Enable Cascade" control can be used to disable the legacy Cascade agent entirely to ensure your team follows the new controls available with Devin CLI.
#### Unsupported enterprise controls
The following legacy enterprise controls are not available with the Devin Local agent:
* **Restrict Tool Calls to Workspace** - by default, the Devin Local agent can only read/edit files within the workspace.
Custom [permissions](https://cli.devin.ai/docs/reference/permissions) are a more flexible replacement that can be used to replicate the same rules.
* **App Deploys** - App deploys are not yet supported with the Devin Local agent.
* **Conversation Sharing** - Conversation sharing is not yet supported with the Devin Local agent.
* **Global tool calling disabled** - If you previously disabled tool calling entirely, write an equivalent [permission policy](https://cli.devin.ai/docs/reference/permissions) for Devin CLI instead.
The following legacy controls will still be enforced as a fallback if you haven't yet implemented an enterprise CLI permission config:
* **Auto Run Terminal Commands** - The Devin Local agent uses its own [permissions model](https://cli.devin.ai/docs/reference/permissions) instead of auto-execution levels; we recommend using this instead, but the old control will still be enforced as a fallback.
* **Terminal allow lists** - Implement an equivalent [permission policy](https://cli.devin.ai/docs/reference/permissions) for Devin CLI to allow specific terminal commands.
* **Terminal deny lists** - Implement an equivalent [permission policy](https://cli.devin.ai/docs/reference/permissions) for Devin CLI to deny specific terminal commands.
## Further reading
* [Devin CLI quickstart](https://cli.devin.ai/docs)
* [Essential commands](https://cli.devin.ai/docs/essential-commands)
* [Extensibility overview](https://cli.devin.ai/docs/extensibility)
* [Team settings](https://cli.devin.ai/docs/enterprise/team-settings)
# Welcome to Devin Desktop
Source: https://docs.devinenterprise.com/desktop/getting-started
Download and install Devin Desktop IDE for Mac, Windows, or Linux. Import VS Code or Cursor settings, configure themes, and start coding with AI-powered assistance.
Devin Desktop is a next-generation AI IDE built to keep you in the flow. On this page, you'll find instructions on how to install Devin Desktop on your computer, navigate the onboarding flow, and get started with your first AI-powered project.
Our next-generation agent harness, shared with Devin CLI. Runs on your machine as the primary local agent.
Credits and usage.
An upgraded Terminal experience.
MCP servers extend the agent's capabilities.
Memories and rules help customize behavior.
Instantly understands your codebase.
Advanced configuration options.
Automate repetitive trajectories.
Deploy applications in one click.
See what's new with Devin Desktop in our [changelog](https://windsurf.com/changelog)!
Join our [Discord](https://discord.gg/GjCYNGChrw) for support, feature requests, and bug reports!
## Set Up
Minimum OS Version: OS X Yosemite