# Billing
Source: https://docs.devin.ai/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.devin.ai/admin/billing/enterprise
How Devin Enterprise contracts are billed, how admins track ACU consumption, and how to set organization and per-user ACU limits.
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.
Organization limits apply to cloud Devin sessions, Devin Review, Devin Desktop, Windsurf JetBrains, and Devin CLI usage billed to the organization. See [Organization-level ACU limits](/admin/billing/org-acu-limits) for API examples and billing attribution.
To open an organization's settings, click its row in the table, or click the pencil icon (**Update name and limits**) at the end of the row.
When an organization reaches its limit, new work billed to it is blocked. An enterprise admin can raise or remove the limit, or users can wait until usage resets in the next monthly billing window. Per-user limits remain in effect independently.
## Setting per-user ACU limits
Beyond per-Organization limits, Enterprise admins can cap each member's monthly ACU consumption with usage tiers, IdP group mappings, and per-member overrides. See [Usage policies](/enterprise/features/usage-policies).
## 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.devin.ai/admin/billing/self-serve
Compare Devin's Free, Pro, Max, and Teams self-serve plans, including seat types, the Teams minimum, 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 | Up to 200 |
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 up to 200 users. Key properties:
* **Up to 200 members**: invite teammates until your organization reaches 200 users. Larger teams should [contact sales](https://cognition.com/contact) about Enterprise.
* **\$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**. There is no separate limit on flex seats, but every member (full or flex) counts toward the 200-user cap.
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 & limits](https://app.devin.ai/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.devin.ai/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.
### macOS sessions
[macOS sessions](/onboard-devin/environment/macos-support) currently consume the **same** usage as equivalent Linux (Ubuntu) sessions — there is no macOS surcharge.
This is **promotional launch pricing** and is subject to change.
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 sleeps automatically after 30 minutes of inactivity by default. Enterprise customers can ask their Cognition account team to adjust this timeout (between 5 and 120 minutes).
## 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. [Devin Coach](/enterprise/features/devin-coach) reinforces them automatically by flagging inefficient prompts in the input box before they're sent.
Enterprise admins can additionally cap each member's monthly consumption with [usage policies](/enterprise/features/usage-policies).
## Frequently asked questions
No, Devin does not consume any usage while sleeping.
Devin sleeps automatically after 30 minutes of inactivity by default, 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 > Usage & limits](https://app.devin.ai/settings/usage).
* **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.devin.ai/admin/common-issues
Fix common Devin setup issues: disconnect existing GitHub or Slack connections from another Devin account, and allowlist Devin IP addresses.
## 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 Connections page at [https://app.devin.ai/settings/connections](https://app.devin.ai/settings/connections)
3. Select **GitHub** and click the connection to open its detail panel
4. Click "Disconnect connection" under **Danger zone**
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 Connections page at [https://app.devin.ai/settings/connections](https://app.devin.ai/settings/connections)
3. Select **Slack**
4. Open the **Manage** menu on the connection and click "Disconnect"
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.devin.ai/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.devin.ai/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).
**Coming from the Windsurf JetBrains plugin?** The
[Windsurf JetBrains plugin](/windsurf/plugins/getting-started#jetbrains-local) is in
maintenance mode, Cascade is being deprecated, and newer JetBrains
IDE releases can break the legacy plugin. Devin over ACP is the recommended way to use
Devin in JetBrains IDEs going forward; follow the setup steps below.
## 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.devin.ai/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.devin.ai/cli/acp/zed
Run Devin CLI inside the Zed editor as a custom ACP agent in the Agent Panel, including install, authentication, and model selection.
[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 "Log in with browser". 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! New threads start on the model set in `agent.model` in your [Devin CLI config](/cli/models#setting-the-model), or on your organization's or plan's default model if none is set. To use [Adaptive](/cli/adaptive), which automatically chooses the best model for each task, or any other specific model, pick it 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.devin.ai/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.
For most users we recommend Fusion — it pairs a frontier lead model with a cost-efficient sidekick. See [Fusion in Devin CLI](/cli/fusion) and [Fusion in Devin Desktop](/desktop/fusion).
## 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.
| 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.
# Devin Cloud in the Devin CLI
Source: https://docs.devin.ai/cli/cloud
Create, steer, resume, and watch Devin Cloud sessions from your terminal with devin --cloud, /cloud, /open, /model, and /archive.
`devin --cloud` runs a Devin Cloud session instead of a local agent. Devin works on its own VM with a shell, browser, and repository clones; the CLI streams the session into your terminal.
## Start a cloud session
```bash theme={null}
devin --cloud # interactive
devin --cloud -p "fix flaky CI tests" # one prompt, print the response, exit
```
Or run `/cloud` in a fresh local session (before the first message; run `/clear` first otherwise).
Requires a Devin account. Run `devin auth login` (or `/login`) if you are not signed in.
Before the first message, `/repo`, `/platform`, and `/model` choose the repositories, OS, and model. Then type a task as usual. The session runs on the VM, so closing the terminal does not stop it.
To move an in-progress local session to the cloud, use [`/handoff`](/cli/handoff).
## Resume a cloud session
`--resume` (`-r`) reopens any cloud session, whether it was started from the CLI, the web app, or Desktop:
```bash theme={null}
devin --cloud -r https://app.devin.ai/sessions/… # by URL
devin --cloud -r devin-0123456789abcdef0123456789abcdef # by ID
devin --cloud -r # pick from recent sessions
```
## Run non-interactively
`--cloud -p` starts a session, sends one prompt, prints Devin's response to stdout, and exits. The session persists; resume it with `devin --cloud -r`.
```bash theme={null}
devin --cloud -p "fix the failing test in auth.rs" # inline prompt
devin --cloud -p -- fix the failing test in auth.rs # trailing arguments
devin --cloud -p --prompt-file prompt.txt # from a file
```
## Continue the work locally
`/pickup` (or `/handoff`) checks out the session's pull request branch and starts a local session on it. See [Hand off back to local](/cli/handoff#hand-off-back-to-local).
`/ssh` opens a shell on the session's VM. See [SSH](/cli/ssh).
## Cloud slash commands
Available in cloud sessions alongside the usual [slash commands](/cli/essential-commands#slash-commands):
| Command | Description |
| ---------------------- | -------------------------------------------------------------------------------------- |
| `/cloud` | Switch a fresh local session to Devin Cloud |
| `/repo` | Choose the repositories to clone |
| `/platform` | Choose the OS, when your organization offers more than one |
| `/model` | Choose the model. [SWE-2](https://cognition.com/blog/swe-2) is recommended. |
| `/open [web\|desktop]` | Open the session in the web app (default) or [Devin Desktop](https://devin.ai/desktop) |
| `/ssh` | SSH into the session's VM |
| `/pickup`, `/handoff` | Check out the pull request branch and continue locally |
| `/rename ` | Rename the session |
| `/archive` | Archive the session |
## Related resources
Connect to a cloud session's VM and forward ports
Move a task between local and cloud with /handoff
Full reference for `--cloud` and the cloud slash commands
# Essential Commands
Source: https://docs.devin.ai/cli/essential-commands
The must-know Devin CLI commands: starting and resuming sessions, cloud sessions, slash commands, and keyboard shortcuts.
## 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
```
## Devin Cloud
Run Devin in the cloud instead of on your machine, and steer it from the same terminal. See [Cloud CLI](/cli/cloud) and [SSH](/cli/ssh).
```bash theme={null}
devin --cloud # Start a cloud session
devin --cloud -r https://app.devin.ai/sessions/… # Resume a cloud session by URL
devin ssh # SSH into the session's VM
```
Inside a session, `/cloud` switches a fresh local session to the cloud, `/open` opens the cloud session in the web app (`/open desktop` for Devin Desktop), `/handoff` moves work between local and cloud, and `/archive` archives it.
***
## 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 |
# Fusion in Devin CLI
Source: https://docs.devin.ai/cli/fusion
Fusion pairs a frontier lead model with a cost-efficient sidekick, delivering frontier intelligence at a lower cost in Devin CLI.
## Selecting Fusion
Run `/fusion` during a session to open the Fusion model picker and choose your lead, effort, and sidekick.
You can switch away from Fusion to a specific model at any time with `/model`.
Fusion pairs a frontier lead model with a cost-efficient sidekick model, so you get frontier-level intelligence at a lower cost. The lead model owns your task — it plans, reasons through the hard parts, and reviews the work — while the sidekick handles the mechanical implementation. You interact with a single Devin; the pairing happens behind the scenes.
## How it works
When you select **Fusion**, two models work together on every session:
* **Lead**: a frontier model that drives planning, design decisions, investigations, and correctness-critical work.
* **Sidekick**: a smaller, more efficient model that executes the lead's plan — writing code, running builds and tests, and verifying changes.
Because most routine work runs on the cheaper sidekick model, a Fusion session costs meaningfully less than running the frontier model alone — frontier intelligence, for cheaper.
Choose Fusion when you want top-tier quality on a complex task without paying frontier prices for every token.
## Choosing a pairing
Fusion isn't a single model — it's a family of lead + sidekick pairings. In the model picker, select the **Fusion** family, then configure:
* **Lead**: which frontier model drives the session.
* **Effort**: how much compute the lead spends reasoning before responding.
* **Sidekick**: which cost-efficient model executes the work. All leads show a recommended sidekick.
* **Fast Mode**: swaps in faster variants of the same models where available — same intelligence, higher speed, at a higher cost.
Selecting `fusion` directly (for example `/model fusion`) opens the model picker.
## Availability
Fusion is available on paid plans in Devin CLI **3000.10.20+** and Devin Desktop **3.10.0+**. It's not included in free or trial tiers.
Fusion is not available for customers on legacy or credit-based plans, including enterprise customers on legacy credits billing.
## Pricing
Fusion bills each model in the pairing at its own rate: the lead at its frontier rate and the sidekick at its lower rate. You can see both rates in the model picker.
Lead and sidekick tokens draw down your quota at each model's own per-token rate.
For customers on the Cognition platform, Fusion usage is metered in **ACUs** (Agent Compute Units). ACU consumption scales with the tokens used by both the lead and the sidekick at their respective rates.
## Tips for getting the most out of Fusion
* **Start with Fable 5.1 + SWE-2.** This is our recommended pairing for best results. Fusion's instructions are tuned for how each pair works together, including how much detail the lead provides and what exploration it delegates.
* **Check your session's usage.** In Devin CLI, run `/session-stats` (or `/stats`) to see token usage, cost by model, and estimated Fusion savings when pricing data is available. Compare total cost and result quality across similar tasks rather than choosing models by token price alone.
# Hand off to cloud Devins
Source: https://docs.devin.ai/cli/handoff
Hand off a task from the Devin CLI to a cloud Devin session with /handoff, and bring a cloud session's pull request back to your machine.
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.
## Hand off back to local
`/handoff` also works the other way. In a [cloud session](/cli/cloud) — started with `devin --cloud` or resumed with `devin --cloud --resume ` — `/handoff` fetches the session's pull request branch, switches your checkout to it, and starts a local session on that code, so you can finish the last mile on your machine.
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
Create, steer, and resume cloud sessions from the terminal
Hand off from any coding agent, not just the Devin CLI
Source, install guides, and the full script reference
# Quickstart
Source: https://docs.devin.ai/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 **Install Devin CLI in Devin Desktop**.
**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
Create, steer, and resume Devin Cloud sessions from your terminal
Open a shell on a cloud session's VM and forward ports
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.devin.ai/cli/models
Available models in Devin CLI and how to configure them, including Adaptive routing and Fusion pairings.
Devin CLI supports multiple AI models. You can choose the best model for your task to optimize for maximum capability, speed, or cost efficiency.
## Recommended
For most users, we recommend **Fusion** — it delivers frontier intelligence for cheaper by pairing a frontier lead model with a cost-efficient sidekick.
***
## 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.devin.ai/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
# SSH into Devin Cloud sessions
Source: https://docs.devin.ai/cli/ssh
Connect to a Devin Cloud session's VM over SSH with devin ssh, forward ports with devin forward, and copy files with scp from the Devin CLI.
Every [Devin Cloud](/cli/cloud) session runs on a VM with the repository cloned and the environment set up. SSH in to explore or edit the code, run dev servers and forward their ports, or copy files with `scp`.
## Connect
`devin ssh` opens a shell on the VM. It wraps the system `ssh` and approves the connection with your logged-in credentials:
```bash theme={null}
devin ssh # open a shell
devin ssh -L 8080:localhost:8080 # extra options pass through to ssh
devin ssh # pick from recent sessions
```
Inside a cloud session, `/ssh` does the same for the current session.
Plain `ssh` also works, from any SSH client (`scp`, your editor's remote-SSH extension). The gateway prints a URL to approve the connection in your browser:
```bash theme={null}
ssh devin-@ssh.devin.ai
scp devin-@ssh.devin.ai:~/repos/app/report.html .
```
## Forward ports
`devin forward` forwards a VM port to `localhost` until you press Ctrl-C:
```bash theme={null}
devin forward 3000 # http://localhost:3000
devin forward 8080:3000 # local 8080 → VM 3000
```
## Related resources
Create, steer, and resume cloud sessions from the terminal
Full reference for `devin ssh` and `devin forward`
# Subagents
Source: https://docs.devin.ai/cli/subagents
Delegate tasks to independent subagents in the Devin CLI that run in the foreground or background with their own profiles and permissions
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** — chosen by the subagent router at spawn time unless an admin pins a model; not your model picker selection | Depends on the default subagent model, not 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 server-side router at spawn time, and an admin can override it (see below). With the default **Subagent router** setting, the router picks the first eligible model from an ordered list, so the resulting model can vary with your plan tier, model availability, and your organization's model policy. The routing list can change over time, so don't rely on a subagent always landing on a particular model.
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 default subagent model rather than your selected 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 server-side router at spawn time. The selected model depends on your plan tier, model availability, and the models your organization permits. |
| **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 (router-selected unless an admin pins one) |
| `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 (router-selected unless an admin pins one) — **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. The alias `tools` is also accepted. |
| `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.
### 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.devin.ai/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.devin.ai/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.devin.ai/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.
### Starting sessions on an outpost
Pick the outpost under **Configuration → Virtual environment** when starting a session in Devin Cloud (see the [Quickstart](/cloud/outposts/quickstart)), or from [Slack](/integrations/slack) with the `!outpost` bang command:
```
@Devin !outpost gpu-h200 profile the training loop and fix the slowest kernel
```
`!outpost ` accepts the outpost's exact name, a unique prefix of it (`!outpost gpu` when `gpu-h200` is the only match), or its ID. Send `!outpost` on its own to get the list of outposts you can use.
### 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.devin.ai/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.devin.ai/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.devin.ai/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": ...}`). The policy comes from the [security profile](/product-guides/security-profiles#outposts-and-profiles) governing the session; enforcing it on your machines is the outpost operator's responsibility.
#### 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 # list outposts
POST /opbeta/outposts # create an outpost
GET /opbeta/outposts/{outpost_id} # get an outpost
DELETE /opbeta/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`.
### Send an operator message
```
POST /opbeta/outposts/devins/{session_id}/operator-message
```
```json theme={null}
{ "message": "Scheduled maintenance: workers restart at 5pm UTC." }
```
Displays a **Message from Outpost Operator** banner in the target session — useful for announcing infrastructure issues or maintenance windows. Requires the write scope.
```bash theme={null}
curl -X POST "https://api.devin.ai/opbeta/outposts/devins//operator-message" \
-H "Authorization: Bearer $DEVIN_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{"message": "Scheduled maintenance: workers restart at 5pm UTC."}'
```
Behavior:
* Each call **replaces** the previous message — the session only ever shows the latest one.
* Sending an **empty string** (`{"message": ""}`) clears the banner.
* Messages are rendered as plain text (up to 2,000 characters; longer messages are rejected with a `422` validation error) — HTML and Markdown are not interpreted.
* Unknown session IDs, sessions on another account's outpost, and finished sessions return `404`.
* **Rate limit:** one new message per session every 30 seconds (`429` otherwise). Clearing with an empty string is always allowed.
Response:
```json theme={null}
{
"session_id": "devin-...",
"message": "Scheduled maintenance: workers restart at 5pm UTC."
}
```
## 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` | Windows x86\_64 |
On Windows, the binary filename (and its checksum file) ends in `.exe` — `devin-remote_${SHA}_windows_x64.exe` and `devin-remote_${SHA}_windows_x64.exe.sha256` — while the latest pointer is plain `latest_windows_x64`.
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.devin.ai/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.devin.ai/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 can build and test in the iOS Simulator on a [macOS session](/onboard-devin/environment/macos-support).
* **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.devin.ai/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.devin.ai/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.
Comment `/devin ` on any open GitHub pull request to start a Devin session on that PR — for example, `/devin fix the failing test and push a commit`. Comment `/devin review` to trigger a Devin Review. See [Start Devin from a PR comment](/integrations/gh#start-devin-from-a-pr-comment).
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.devin.ai/essential-guidelines/when-to-use-devin
Learn when to use Devin: which tasks suit cloud Devin sessions, Devin CLI in your terminal, and other Devin surfaces for engineering work.
**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 [Automations](/product-guides/automations):**
* Add a [Schedule trigger](/product-guides/automations#schedule-triggers) to run daily or weekly sessions that triage Sentry errors, update dependencies, generate reports, or handle 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`](/cli/handoff) 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.devin.ai/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`](/cli/handoff) 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 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 in the web app by clicking the **Help** (question mark) icon at the bottom of the sidebar and selecting **Contact support**.
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.devin.ai/get-started/first-run
Start your first Devin session: choose Ask or Agent mode, pick a repository and agent, use @ mentions, and try first-time prompt ideas.
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.
* **[Data Analyst](/work-with-devin/data-analyst)** (DANA) — A data analyst agent optimized for querying databases, analyzing data, and creating visualizations. To use it, open the **Mode** submenu in the agent picker and select **Data**.
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
Make a small, focused pull request for the change I describe.
## What's Needed From User
- The repository to change
- A description of the change, plus any metadata to include in the PR (e.g. a Linear or Jira ticket ID)
## Procedure
1. Study the request and the relevant code, and share a short plan before making changes.
2. Make only the requested changes.
3. Run the repository's lint and typecheck commands for the files you changed, and fix any failures.
4. Open a pull request whose description follows the repository's PR template.
5. Fix CI failures and address review feedback by pushing new commits to the same branch.
## Specifications
- PR contains no stray or unrequested changes
- Lint and typecheck pass
- PR description includes any metadata I provided
```
Devin handles branching, PR creation, and CI monitoring with its built-in workflow, so the playbook only needs to describe the task. See [Creating Playbooks](/product-guides/creating-playbooks) to save this prompt as a Playbook, and [Pull Request Templates](/integrations/pr-templates) to control what goes into the PR description.
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.devin.ai/integrations/bitbucket
Connect Devin to Bitbucket Cloud or Bitbucket Data Center to create pull requests, and configure a webhook so Devin responds to PR comments.
## 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), open the dropdown next to the **Connect** button, and select **Connect with Bitbucket Data Center**.
3. Configure the connection by providing:
* **Bitbucket Host**: your Bitbucket Data Center domain (e.g. `bitbucket.mycompany.com`)
* **Bitbucket Username**: the service account's username
* **Bitbucket HTTP Access Token**: an [HTTP access token](https://confluence.atlassian.com/bitbucketserver/http-access-tokens-939515499.html) created for the service account. You can replace it later with **Rotate access token** in the connection's details panel.
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.
### Webhook configuration (Bitbucket Data Center)
Configuring a webhook lets Devin receive pull request events from Bitbucket Data Center in real time, so PR status and comments are delivered to the Devin session working on the PR.
1. In your Devin account, go to **Settings** > **Connections** > **Bitbucket** and click the Bitbucket Data Center connection to open its details panel.
2. On the **General** tab, click **Configure** in the **Webhook** row. The dialog shows the webhook URL and a secret token — copy the token now, it is only shown once (you can regenerate it later from the same dialog).
3. In Bitbucket Data Center, open the repository or project settings and go to **Webhooks**.
4. Create a webhook and paste the webhook URL.
5. Under **Pull request** events, select **Opened**, **Source branch updated**, **Merged**, **Declined**, and **Comment added**.
6. Under **Authentication**, choose **Basic**, enter any username, and paste the secret token as the password.
Webhooks are only available for Bitbucket Data Center connections. Bitbucket Cloud connections do not have a webhook option.
## Using Devin with the Bitbucket Integration
After connecting Bitbucket, set up your repositories on [Devin's Machine](https://app.devin.ai/machine).
**How Devin responds to PR comments.**
* **Bitbucket Cloud**: Devin does not wake up automatically for comments on its pull requests. Devin can still address them if you point them out directly in the session.
* **Bitbucket Data Center**: once the [webhook](#webhook-configuration-bitbucket-data-center) is configured, a comment on a pull request that a Devin session is tracking is delivered to that session and Devin responds. An organization admin can limit this with **Require @Devin to respond** under [**Settings** > **Devin**](https://app.devin.ai/settings/devin) > **Pull requests**, so Devin only responds to comments that start with `@Devin` (the `devinai` prefix is also accepted). Comments that contain `(aside)` or `!aside`, or that start with `aside`, are always ignored. Without a webhook, Data Center behaves like Bitbucket Cloud.
## 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
* On Bitbucket Data Center, configure the webhook so Devin receives PR events in real time
# Connect Devin to Databricks
Source: https://docs.devin.ai/integrations/databricks
Connect Devin to Databricks with a service principal, an OAuth client secret or OIDC token federation, the Databricks CLI, and Unity Catalog grants.
Devin can work inside your Databricks workspaces as an asynchronous coworker: exploring catalogs, debugging failed jobs, tuning SQL, writing and testing notebooks, and shipping changes through your normal Git workflow. This guide walks through standing that up with a dedicated Databricks service principal that Devin authenticates as, governed by Unity Catalog.
The integration is built from three pieces you already control: a Databricks service principal, the Databricks CLI installed through an [environment blueprint](/onboard-devin/environment/blueprints), and (optionally) the Databricks skills plugin. Databricks, its workspaces, and every permission stay in your account.
## Choose how Devin authenticates
Devin authenticates to Databricks as the service principal in one of two ways. Both use the same service principal, blueprint-installed CLI, and Unity Catalog grants; they differ only in the credential.
| Path | Best for | Setup |
| ---------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| [**Option A: OAuth client secret**](#option-a-oauth-client-secret) | Getting started quickly. Three Devin Secrets and a short blueprint. | Generate an OAuth secret on the service principal and store it in Devin Secrets. |
| [**Option B: OIDC token federation**](#option-b-oidc-token-federation) | Expanding the integration, or any team that would rather not manage a Databricks secret. Databricks [strongly recommends](https://docs.databricks.com/aws/en/dev-tools/auth/oauth-federation) token federation for automated workloads because there is nothing to rotate. | Trust Devin's OIDC issuer with a federation policy; each session exchanges a short-lived Devin identity token for a Databricks OAuth token. |
Start with Option A if you want Devin running against Databricks today. You can move to Option B later without touching the service principal or its grants.
## Why connect Devin to Databricks?
* **Devin works where your data platform lives.** Most Databricks work is not just editing notebooks in a repo. It is checking why a job failed, reading a table's schema, running a query against a warehouse, or inspecting a pipeline. Giving Devin the CLI turns those from questions for a human into things Devin can do itself.
* **One auditable identity.** Devin acts as a service principal you created, so every API call, query, and job run shows up in Databricks audit logs and Unity Catalog lineage under that identity, not under an engineer's personal token.
* **Unity Catalog decides what Devin can touch.** OAuth decides whether Devin can authenticate. Unity Catalog grants and workspace permissions decide what it can read or change. You can start read-only in production, give Devin a sandbox catalog to build in, and widen scope only after you have seen how it behaves.
* **A path to no stored secret.** With OIDC token federation (Option B), Devin never stores a Databricks token or client secret. Each session exchanges a 60-second Devin identity token for a short-lived Databricks OAuth token.
## Overview
```
Devin session
│ Databricks CLI authenticates as the service principal
│ Option A: client ID + client secret from Devin Secrets
│ Option B: short-lived Devin OIDC token, matched by a federation policy
▼
Databricks issues a short-lived OAuth access token for the service principal
│
▼
Workspace APIs, SQL warehouses, jobs, Unity Catalog
(limited by workspace permissions and Unity Catalog grants)
```
The setup has four parts:
| Part | Where it lives | What it does |
| --------------------- | ------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------- |
| **Service principal** | Databricks account | The identity Devin acts as. Assigned to the workspaces Devin needs. |
| **Authentication** | Databricks account + Devin | **Option A:** OAuth M2M with a client secret stored in Devin Secrets. **Option B:** OIDC token federation, no stored secret. |
| **Databricks CLI** | Devin blueprint | Installed into the snapshot and configured to authenticate as the service principal. |
| **Permissions** | Databricks workspace + Unity Catalog | Workspace entitlements, SQL warehouse and job permissions, and catalog/schema grants. |
The [Databricks skills plugin](#step-4-install-the-databricks-skills-plugin-optional) is a fifth, optional layer: it teaches Devin Databricks-specific workflows (Asset Bundles, jobs, SQL, Unity Catalog) on top of the CLI.
## Prerequisites
**Databricks**
* A Databricks account on AWS, Azure, or GCP with **account admin** access for the person doing setup. Creating service principals, OAuth secrets, and federation policies happens at the account level.
* One or more workspaces with **Unity Catalog** enabled. This guide assumes Unity Catalog governs the data Devin should reach.
* The [Databricks CLI](https://docs.databricks.com/aws/en/dev-tools/cli/) on the admin's own machine for the account-level commands below. Any recent version works for those. Devin's copy is installed separately in Step 2.
**Devin**
* Permission to edit your organization's [environment blueprint](/onboard-devin/environment/blueprints) (**Settings > Environment > Blueprints**).
* For Option A, permission to add [Devin Secrets](/product-guides/secrets).
* For Option B, your Devin **OIDC issuer URL** and **organization ID**. Step 2 shows how to read both from a token inside a Devin session. See [Cloud Authentication with OIDC](/product-guides/oidc) for background.
**Network**
* Devin sessions must reach your workspace host over HTTPS (for example `https://dbc-xxxx.cloud.databricks.com`, `https://adb-xxxx.azuredatabricks.net`, or `https://xxxx.gcp.databricks.com`). If your organization uses a Devin [network policy](/product-guides/security-profiles), add the workspace host and, for account-level commands, the account host (`accounts.cloud.databricks.com`, `accounts.azuredatabricks.net`, or `accounts.gcp.databricks.com`).
* For Option B, Databricks must be able to fetch Devin's JWKS at `https:///.well-known/jwks.json` over the public internet to verify token signatures.
## Step 1: Create a service principal
Create a dedicated service principal for Devin rather than reusing one that other automation depends on. A dedicated principal keeps audit logs and permission reviews clean.
From a machine where you are logged in to the Databricks **account** (not a workspace):
```bash theme={null}
databricks account service-principals create --display-name devin-sessions
```
Record two values from the output:
| Field | Used for |
| --------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| `applicationId` | The OAuth **client ID**. Used in the `DATABRICKS_CLIENT_ID` secret (Option A) or the CLI profile (Option B), and in `GRANT` statements. |
| `id` | The numeric service principal ID. Needed to create an OAuth secret (Option A) or attach a federation policy (Option B). |
Then assign the service principal to each workspace Devin should use. You can do this in the account console under **User management → Service principals**, or with the CLI:
```bash theme={null}
databricks account workspace-assignment update \
--json '{"permissions": ["USER"]}'
```
Use `USER`, not `ADMIN`. Devin does not need workspace admin.
## Step 2: Connect Devin to the service principal
Follow **one** of the two options below. Each is complete on its own: it installs the Databricks CLI through a [blueprint](/onboard-devin/environment/blueprints) under **Settings > Environment > Blueprints** and configures the CLI to authenticate as the service principal from Step 1.
* [**Option A: OAuth client secret**](#option-a-oauth-client-secret). Standard [OAuth M2M](https://docs.databricks.com/aws/en/dev-tools/auth/oauth-m2m): the service principal gets a client secret, which you store in Devin Secrets. Fastest way to get started.
* [**Option B: OIDC token federation**](#option-b-oidc-token-federation). Every Devin session can mint a short-lived OpenID Connect token signed by Devin. Databricks [token federation](https://docs.databricks.com/aws/en/dev-tools/auth/oauth-federation) lets the service principal trust that issuer, so Devin exchanges its own identity token for a Databricks OAuth token. No Databricks secret is ever created or stored, which is why Databricks strongly recommends it for automated workloads.
Personal access tokens (PATs) tied to a human user are not recommended for either option. They bypass the service principal, expire unpredictably, and attribute Devin's actions to a person.
### Option A: OAuth client secret
Prefer not to manage a Databricks secret at all? Skip to [Option B: OIDC token federation](#option-b-oidc-token-federation). You can also start here and switch later: swap in the Option B blueprint, create the federation policy, then delete the OAuth secret and the `DATABRICKS_CLIENT_SECRET` Devin Secret.
#### 1. Generate an OAuth secret
In the account console, open the service principal from Step 1 and generate an **OAuth secret**. Set the shortest lifetime your rotation process supports (the maximum is 730 days) and restrict the secret to the API scopes Devin needs, such as `sql`, `jobs`, and `unity-catalog`. Avoid selecting all scopes.
#### 2. Add the Devin Secrets
In Devin, add the following as [Devin Secrets](/product-guides/secrets) on the **Secrets** tab of the blueprint you will edit next (organization or repository):
| Secret | Value |
| -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `DATABRICKS_HOST` | The **workspace** URL Devin should work in, for example `https://dbc-xxxx.cloud.databricks.com` or `https://adb-xxxx.azuredatabricks.net`, with no `/api` suffix. Not the `accounts.*` host. |
| `DATABRICKS_CLIENT_ID` | The service principal's `applicationId` (a UUID) from Step 1, not the numeric `id` |
| `DATABRICKS_CLIENT_SECRET` | The OAuth secret you generated |
The CLI selects OAuth M2M automatically when a client ID and client secret are present, so `DATABRICKS_AUTH_TYPE` is not required. Set it to `oauth-m2m` only if you want to rule out every other method explicitly.
Secrets are injected as environment variables at the start of every new session, so the CLI needs no profile file. A rotated secret applies to the next new session without a rebuild.
#### 3. Add the blueprint
Installs the CLI only. Authentication comes entirely from the three secrets above.
```yaml theme={null}
initialize:
- name: Install Databricks CLI
run: |
sudo rm -f /usr/local/bin/databricks
curl -fsSL https://raw.githubusercontent.com/databricks/setup-cli/main/install.sh | sudo sh
databricks --version
knowledge:
- name: databricks-auth
contents: |
The `databricks` CLI authenticates as a service principal using the DATABRICKS_HOST,
DATABRICKS_CLIENT_ID, and DATABRICKS_CLIENT_SECRET environment variables, which are
provided as Devin Secrets. Do not run `databricks auth login`, do not set DATABRICKS_TOKEN,
and do not ask for a personal access token. Check auth with `databricks current-user me`.
Write only to the devin_dev catalog; production catalogs are read-only. Ship notebook and
job changes through a pull request.
```
Do not write the secrets into a file during `initialize`; anything written there is baked into the snapshot.
Do not also set `DATABRICKS_TOKEN` or leave a `~/.databrickscfg` profile in the snapshot. Conflicting credentials are the most common reason M2M authentication fails.
#### 4. Build the snapshot
Save the blueprint and wait for the build to show **Success**, then start a new session. Existing sessions keep the old snapshot. Continue to [Step 3](#step-3-grant-permissions).
### Option B: OIDC token federation
Devin sessions mint short-lived identity tokens (`iss`, `sub`, `aud`), and a federation policy on the service principal tells Databricks to trust them. The blueprint installs the `devin-oidc` CLI, wraps `databricks` so every call carries a fresh token, and writes a profile that points at your service principal. Then you read the token's claims from a session and create a policy that matches them.
Want the shortest path first? Start with [Option A](#option-a-oauth-client-secret) and come back here when you are ready to drop the stored secret.
#### 1. Add the blueprint
Two placeholders in the profile must be replaced with your own values:
| Placeholder | Replace with |
| ----------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `` | The **workspace** URL Devin should work in, for example `https://dbc-xxxx.cloud.databricks.com` or `https://adb-xxxx.azuredatabricks.net`, with no `/api` suffix. Not the `accounts.*` host. This is the same value as `DATABRICKS_HOST` in Option A. |
| `` | The service principal's `applicationId` (a UUID) from the `databricks account service-principals create` output in Step 1. Not the numeric `id`, which is only used to attach the federation policy. |
```yaml theme={null}
initialize:
- uses: github.com/CognitionAI/actions/setup-devin-oidc@main
- name: Install Databricks CLI
run: |
sudo rm -f /usr/local/bin/databricks
curl -fsSL https://raw.githubusercontent.com/databricks/setup-cli/main/install.sh | sudo sh
sudo mv /usr/local/bin/databricks /usr/local/bin/databricks-bin
- name: Wrap the CLI so each call carries a fresh Devin OIDC token
run: |
sudo tee /usr/local/bin/databricks > /dev/null <<'EOF'
#!/usr/bin/env bash
set -euo pipefail
DATABRICKS_OIDC_TOKEN="$(devin-oidc token --audience "${DATABRICKS_DEVIN_AUDIENCE:-databricks}")"
export DATABRICKS_OIDC_TOKEN
exec /usr/local/bin/databricks-bin "$@"
EOF
sudo chmod +x /usr/local/bin/databricks
- name: Write Databricks CLI profile
run: |
cat > ~/.databrickscfg <<'EOF'
[DEFAULT]
host =
auth_type = env-oidc
client_id =
audience = databricks
EOF
chmod 600 ~/.databrickscfg
knowledge:
- name: databricks-auth
contents: |
The `databricks` CLI is preconfigured to authenticate as a service principal through
Devin OIDC token federation. Do not run `databricks auth login`, do not set
DATABRICKS_TOKEN, and do not ask for a personal access token. Check auth with
`databricks current-user me`. Write only to the devin_dev catalog; production catalogs
are read-only. Ship notebook and job changes through a pull request.
```
| Piece | Purpose |
| ---------------------- | ------------------------------------------------------------------------------------------------- |
| `setup-devin-oidc` | Installs the `devin-oidc` CLI that mints Devin identity tokens ([details](/product-guides/oidc)). |
| Wrapper | Devin identity tokens expire after 60 seconds, so each CLI call mints its own. |
| `auth_type = env-oidc` | Pins the CLI to token federation so it never falls back to a PAT or interactive login. |
| `host` / `client_id` | The workspace URL and the service principal `applicationId` from the table above. |
| `audience` | The audience the wrapper requests and that you will put in the federation policy below. |
| `knowledge` | Tells Devin the CLI is already authenticated so it does not attempt `databricks auth login`. |
The profile contains no secret, so it is safe to write during `initialize`. If you are switching from Option A, remove the `DATABRICKS_CLIENT_SECRET` Devin Secret once the policy below is in place so the CLI does not see two credentials.
#### 2. Build the snapshot
Save the blueprint and wait for the build to show **Success**. Nothing in the blueprint depends on the federation policy you create next, so you will not need to rebuild afterwards.
#### 3. Create the federation policy
With the blueprint built, Devin sessions can mint identity tokens. Use one to read the exact claims Databricks must trust, then create a federation policy on the service principal that matches them.
Start a new Devin session and ask it to run the following. It prints only the token's identity claims, never the token itself.
```bash theme={null}
devin-oidc token --audience databricks | python3 -c '
import sys, json, base64
p = sys.stdin.read().strip().split(".")[1]
c = json.loads(base64.urlsafe_b64decode(p + "=="))
print(json.dumps({k: c[k] for k in ("iss", "sub", "aud")}, indent=2))'
```
Expected shape:
```json theme={null}
{
"iss": "https://app.devin.ai",
"sub": "org_id:",
"aud": "databricks"
}
```
On enterprise deployments `iss` is your custom Devin URL (for example `https://yourcompany.devinenterprise.com`). Copy `iss` and `sub` exactly as printed. Do not paste the raw token into tickets or documents; it is a bearer credential for the next 60 seconds.
Save this as `devin-federation-policy.json`, substituting the values from the previous step:
```json theme={null}
{
"description": "Allow Devin sessions to authenticate as the devin-sessions service principal",
"oidc_policy": {
"issuer": "https://",
"audiences": ["databricks"],
"subject": "org_id:"
}
}
```
All three fields are exact-match:
* `issuer` must equal the token's `iss`, including the scheme and with no trailing slash.
* `audiences` must include the audience Devin requests (`databricks` in this guide).
* `subject` must equal the token's `sub`. The default subject is your organization ID, so every session in the organization can authenticate as this principal. This is the right granularity for Databricks because federation policies match the subject as a literal string. Per-session claims such as `devin_id` change every session and cannot be matched by a static policy.
Leave `subject_claim`, `jwks_uri`, and `jwks_json` unset. Databricks defaults to the `sub` claim and discovers the JWKS from the issuer's `/.well-known/openid-configuration`.
```bash theme={null}
databricks account service-principal-federation-policy create \
--policy-id devin-sessions \
--json @devin-federation-policy.json
```
Confirm it exists:
```bash theme={null}
databricks account service-principal-federation-policy list
```
The profile the blueprint wrote already points at this service principal, so no rebuild is needed. Continue to [Step 3](#step-3-grant-permissions).
### Rebuilds and version pinning
Both the Databricks install script and `setup-devin-oidc@main` track their upstream `main` branches, so a full build picks up new releases; a [differential build](/onboard-devin/environment/differential-builds) skips `initialize` and keeps the versions already in the snapshot until the blueprint changes. If you need reproducible builds, fetch the installer from a release tag instead of `main` (for example `.../databricks/setup-cli/v1.17.0/install.sh`), which installs exactly that CLI version, and pin the action to a commit SHA (`setup-devin-oidc@`).
## Step 3: Grant permissions
Authentication only proves who Devin is. What Devin can see or change is decided by workspace permissions and Unity Catalog grants, which you can adjust at any time without touching the blueprint. Start with the smallest profile that fits the work and expand deliberately.
### Permission profiles
| Profile | Typical work | Unity Catalog grants | Workspace permissions |
| ------------------------ | --------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------- |
| **Explore** (start here) | Answer questions about data, document schemas, investigate failed jobs, propose query fixes in a PR | `USE CATALOG`, `USE SCHEMA`, `SELECT`, `BROWSE` on production catalogs; `READ VOLUME` where Devin needs files | `CAN USE` on one SQL warehouse; `CAN VIEW` on the jobs and pipelines Devin should investigate |
| **Build** | Prototype tables, functions, and notebooks in a sandbox; run tests against real read-only data | Explore grants on production, plus ownership of (or `ALL PRIVILEGES` on) a dedicated `devin_dev` catalog or schema | Explore permissions, plus `CAN MANAGE RUN` on sandbox jobs and a restrictive cluster policy if Devin may start compute |
| **Operate** | Rerun or repair specific production jobs after Explore and Build are proven | Explore grants, plus `MODIFY` on the specific tables a job writes | `CAN MANAGE RUN` on the specific jobs, granted per job rather than workspace-wide |
Grant statements target the service principal by its application ID:
```sql theme={null}
-- Explore: read-only on the production analytics catalog
GRANT USE CATALOG, BROWSE ON CATALOG analytics TO ``;
GRANT USE SCHEMA, SELECT ON SCHEMA analytics.gold TO ``;
GRANT READ VOLUME ON VOLUME analytics.gold.landing TO ``;
-- Build: a sandbox catalog Devin owns, isolated from production
CREATE CATALOG IF NOT EXISTS devin_dev;
ALTER CATALOG devin_dev OWNER TO ``;
```
If you prefer group-based administration, add the service principal to a group such as `devin-agents` and grant to the group instead.
Code changes should still flow through pull requests. Devin can read production data to understand a problem and validate a fix in the sandbox, but the notebook, job definition, or Asset Bundle change lands through your normal review process, not by editing production directly.
## Step 4: Install the Databricks skills plugin (optional)
Databricks publishes [Agent Skills](https://github.com/databricks/databricks-agent-skills) that teach coding agents Databricks workflows: Asset Bundles, jobs, SQL, Unity Catalog, and Spark. Installing them as a Devin [plugin](/product-guides/plugins) gives Devin that know-how on top of the CLI.
1. Open **Customize → Plugins**, choose **Add plugin → From repository**.
2. Enter the repository `databricks/databricks-agent-skills` and the subdirectory `plugins/databricks/claude`. The plugin manifest lives in that subfolder, so installing from the repository root reports **No plugin manifest found**.
3. Install at the **Organization** scope if you used an organization blueprint in Step 2. If you used a repository blueprint, declare the plugin in that repository's `.devin/config.json` instead (see [inheritance and levels](/cli/extensibility/plugins/overview#inheritance-and-levels)) so only sessions that have the CLI also get the skills.
4. [Pin the plugin to a commit](/product-guides/plugins#pinning-a-plugin) once it is working so upstream changes do not land in your sessions unreviewed.
The plugin's core skill recommends running `databricks auth login` to set up a profile. That interactive browser flow cannot complete in an unattended Devin session and is not needed here; the `knowledge` entry in Step 2 tells Devin the CLI is already authenticated.
## Step 5: Verify
Start a new session (after the blueprint build succeeds) and ask Devin to run:
```bash theme={null}
databricks --version
databricks current-user me
```
`current-user me` should return the service principal, with `userName` equal to its application ID. To confirm which authentication method the CLI chose:
```bash theme={null}
databricks auth describe
```
For Option A this reports `oauth-m2m`; for Option B, `env-oidc`.
Successful authentication does not mean Devin can reach your data. Confirm that the grants from Step 3 apply:
```bash theme={null}
databricks catalogs list
databricks warehouses list
databricks grants get catalog
```
Replace `` with a catalog you granted in Step 3 (the examples there use `analytics`). Then ask Devin to run a small read-only query against a warehouse it has `CAN USE` on, and, if you set up a Build profile, to create and drop a table in `devin_dev`. A query against a production table that Devin has no `SELECT` on should fail; that failure is the permission boundary working.
## Troubleshooting
| Symptom | Applies to | Cause and fix |
| ----------------------------------------------------------------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Errors about conflicting credentials or more than one auth method | Option A | Remove `DATABRICKS_TOKEN`, `DATABRICKS_USERNAME`, and any `~/.databrickscfg` profile. The CLI refuses to guess when more than one auth method is configured. |
| `DATABRICKS_OIDC_TOKEN` not set or empty | Option B | The wrapper was bypassed or not installed. Confirm `which databricks` resolves to the wrapper and that `devin-oidc token --audience databricks` succeeds on its own. |
| `invalid_grant` or an error mentioning the subject | Option B | Policy `subject` does not exactly equal the token `sub`. Rerun the claims script from Step 2 and compare character by character. |
| Error mentioning the audience | Option B | Policy `audiences` does not include the audience the wrapper requests. Both default to `databricks`; keep them identical. |
| Error mentioning the issuer, JWKS, or signature | Option B | `issuer` has a typo (trailing slash, `http`, wrong host) or Databricks cannot reach `https:///.well-known/jwks.json`. Load that URL from outside your network to confirm it is public. |
| Token expired | Option B | Devin identity tokens live for 60 seconds. Use the wrapper rather than minting a token manually. |
| CLI does not recognize `env-oidc` | Option B | The snapshot has an old CLI (or the legacy Python `databricks-cli` package). Remove the old package from the blueprint and rebuild. |
| Authenticated but `catalogs list` is empty or a query is denied | Both | The principal is authenticated but not authorized. Check the workspace assignment (Step 1) and the Unity Catalog grants (Step 3) with `databricks grants get catalog `. |
| Connection timeouts or DNS failures | Both | The workspace host is not reachable from Devin. Add it (and the account host, if needed) to your Devin [network policy](/product-guides/security-profiles). |
## Support
For Databricks-side setup (service principals, OAuth secrets, federation policies, Unity Catalog), see the [Databricks authentication documentation](https://docs.databricks.com/aws/en/dev-tools/auth/) (switch to the Azure or GCP edition as needed). For Devin-side setup (blueprints, OIDC, plugins, network policy), contact [support@cognition.ai](mailto:support@cognition.ai) or your account team.
# Devin GitHub integration
Source: https://docs.devin.ai/integrations/gh
Connect Devin to GitHub to create pull requests, respond to review comments, and control repository access for your organization.
## 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, open [Settings → Connections → GitHub](https://app.devin.ai/settings/connections/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, open [Settings → Connections → GitHub](https://app.devin.ai/settings/connections/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 [**Settings** > **Repositories**](https://app.devin.ai/settings/repositories).
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 comments on PRs its sessions are working on, as long as the session has not been archived. To start a new session from any PR, see [Start Devin from a PR comment](#start-devin-from-a-pr-comment).
### Start Devin from a PR comment
You can hand work to Devin without leaving GitHub. On any open pull request in a repository connected to Devin, leave a comment that starts with `/devin` followed by what you want done:
```
/devin fix the failing lint check and push a commit
```
Devin starts a new session with that repository, uses the PR as context (taking over the PR if appropriate), and replies on the PR with a link to the session.
| Comment | What happens |
| ----------------- | ------------------------------------------------------------------------------------------------------ |
| `/devin ` | Starts a Devin session for the PR with your prompt |
| `/devin review` | Starts a [Devin Review](/work-with-devin/devin-review#triggering-a-review-from-a-pr-comment) of the PR |
| `/devin` | Devin replies with usage instructions |
Requirements:
* **Start of the comment** — the command must begin the comment. It is case-insensitive and works in both PR conversation comments and inline review comments.
* **Open PRs only** — comments on issues, or on closed or merged PRs, are ignored.
* **Write access** — the commenter needs `write` or `admin` permission on the repository.
* **Linked account** — the commenter's GitHub account must be [linked to their Devin account](#user-linking), and they must be a member of a Devin organization with access to the repository and permission to use Devin sessions.
If a Devin session is already working on the PR, `/devin` comments are sent to that session instead of starting a new one.
## User Linking
The GitHub App connection above is organization-wide. On top of it, individual users can link their own GitHub account to Devin so that Devin can act under their identity: pull requests Devin opens in their sessions are authored by them, and comments or reviews they submit through [Devin Review](/work-with-devin/devin-review) appear under their GitHub account.
To link a personal GitHub account:
1. Go to [Settings > **Connections**](https://app.devin.ai/account/connections) in your personal account settings
2. Find the **GitHub** row in the list of accounts
3. Click **Link** and complete the GitHub authorization
To remove the link later, click **Unlink user** on the same row. Devin revokes the OAuth token with GitHub when you unlink.
**The GitHub row only appears if your organization has a GitHub connection.** If it is missing, confirm that you are a member of a Devin organization whose GitHub integration is set up. GitHub Enterprise Server instances appear as separate **GitHub Enterprise** rows labeled with the host, and are linked the same way.
For Devin to open pull requests as the linked user, an admin also needs to set **Open PRs as** under [**Settings** > **Devin**](https://app.devin.ai/settings/devin) > **Pull requests**:
* **Devin**: always opens pull requests as Devin
* **User**: opens as the user when their git account is linked, otherwise as Devin
* **User only**: opens as the user, and fails if their git account is not linked (automations and service users still fall back to Devin)
## 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 *committer*. GitHub verifies signatures against the committer email, but in any **Commit authoring** mode where the committer is the requesting user ("Co-authored (you + Devin)", "You only", "Devin as author, you as committer"), Devin commits with each user's own email as the committer — which won't match a single shared GPG key. Before relying on this setup, have an enterprise admin set **Commit authoring** under [Enterprise Settings > Devin](https://app.devin.ai/settings/enterprise-devin) > **Git commit attribution** to **"Devin only"**, **"Co-authored (Devin + you)"**, or **"You as author, Devin as committer"**. This enterprise-wide setting overrides each user's personal **Git commit author** preference; while it is left at **Per-user (Default)**, each user's own choice under [Settings > Preferences](https://app.devin.ai/settings/preferences) applies. If your organization isn't part of an enterprise, there is no org-wide control: every user who starts Devin sessions must set their personal **Git commit author** under [Settings > Preferences](https://app.devin.ai/settings/preferences) to one of those modes.
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 *committer* 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.devin.ai/integrations/gitlab
Connect Devin to GitLab (versions 15.0 and later) to create merge requests, respond to MR comments, and collaborate in your 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 (version 15.0 and later) for users on our Enterprise plan. Simply click the dropdown on the "Connect" button and select **Connect to self-hosted instance**. See the [GitLab Self-Managed Integration guide](/enterprise/integrations/gitlab-self-managed) for full setup instructions.
The same dropdown also offers **Connect service account**, which connects a GitLab.com service account (or a dedicated user account on the Free tier) with a personal access token that has the `api` scope instead of the OAuth flow below.
## 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** > **GitLab**
2. Click the GitLab connection you want to configure to open its details panel
3. On the **General** tab, click **Configure** in the **Webhook** row
4. Copy the webhook **URL** and **Secret Token** from the dialog
5. Follow the dialog's **Group** (recommended) or **Project** steps to add the webhook in GitLab, selecting the **Comments**, **Merge request events**, **Push events**, **Issues events**, and **Pipeline events** triggers
Adding a webhook in GitLab requires the **Maintainer** role on the project, or the **Owner** role on the group for group webhooks (group webhooks are available on GitLab Premium and Ultimate). When automatic webhook setup is available for your organization, the dialog notes that Devin sets up webhooks on every project and group its GitLab account can administer; use the manual steps only for projects it cannot reach.
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
On top of the organization-wide connection, individual users can link their own GitLab account to Devin so that Devin can act under their identity for GitLab operations, such as opening merge requests as the linked user when **Open PRs as** is set to **User** or **User only** under [**Settings** > **Devin**](https://app.devin.ai/settings/devin) > **Pull requests**.
To link a personal GitLab account:
1. Ensure you are a member of a Devin organization whose GitLab integration is set up
2. Go to [Settings > **Connections**](https://app.devin.ai/account/connections) in your personal account settings
3. Find the **GitLab** row and click **Link**, then complete the GitLab authorization
**Personal Connections only shows integrations for organizations the user belongs to.** The **GitLab** row appears when your organization has a GitLab.com connection. Self-hosted GitLab instances (Enterprise plan) appear as separate **Self-hosted GitLab** rows labeled with the host, and are linked the same way. If no GitLab row appears, confirm that you are a member of a Devin organization with a GitLab connection.
***
## Using Devin with the GitLab Integration
After connecting GitLab, set up your repositories on [Devin's Machine](https://app.devin.ai/machine).
**How Devin responds to MR comments.** Once the [webhook](#webhook-configuration) is configured, a comment on a merge request that a Devin session is tracking is delivered to that session in real time. By default, this wakes a sleeping session and Devin responds to the comment.
To limit this, an organization admin can turn on **Require @Devin to respond** under [**Settings** > **Devin**](https://app.devin.ai/settings/devin) > **Pull requests**. With that setting enabled, Devin only wakes and responds to comments that start with `@Devin` (the `devinai` prefix is also accepted).
Comments that contain `(aside)` or `!aside`, or that start with `aside`, are always ignored regardless of this setting, so you can discuss the MR without waking Devin.
Without a webhook, MR comments are not delivered to the session in real time; Devin can still address them if you point them out directly in the session.
## 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.devin.ai/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.devin.ai/integrations/linear
Assign Linear tickets to Devin and turn them into pull requests with playbook labels, @mentions, and automation triggers.
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.
For a video example of handing Devin work from a backlog, see [Send Linear tickets to Devin](/tutorial-library/pm-linear-backlog).
## 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.devin.ai/integrations/microsoft-teams
Connect Devin to Microsoft Teams to start sessions by tagging @Devin AI in a channel or chat, get replies in context, and control sessions with inline keywords.
Tag **@Devin AI** in Microsoft Teams as soon as bugs, feature requests, and questions come in. Devin responds with updates and questions when it's tagged.
## Get started
### Installation
Setting up Microsoft Teams has two parts: connecting your Microsoft 365 tenant to Devin, then installing the Devin app in the teams where you want to use it.
#### 1. Connect your tenant
1. Go to [Settings > Connections](https://app.devin.ai/settings/connections) and select **Microsoft Teams**
2. Click **Connect** and choose one of the two options:
* **Sign in with Microsoft**: sign in with a Microsoft account that has the **Teams Administrator** or **Global Administrator** role. This connects the tenant without granting tenant-wide admin consent. Team owners then add Devin from the Teams store.
* **Grant admin consent**: a **Microsoft Entra ID Global Administrator** grants tenant-wide admin consent for the [Microsoft Graph application permissions](#tenant-wide-microsoft-graph-application-permissions) once for the whole tenant. This also lets you remove Devin from teams from the Devin settings page.
3. Complete the Microsoft prompts. You're returned to the Microsoft Teams settings page, and your own Microsoft Teams user is linked to your Devin user.
Tenant-wide admin consent is optional. If you connected with **Sign in with Microsoft**, you can grant it later from the **Grant admin consent** link in the **Connected teams** section. With **Sign in with Microsoft**, your tenant must still allow the Devin AI app to receive an application token so Devin can read messages where it's installed; if Microsoft Entra ID blocks it, ask a Cloud Application Administrator (or higher) to allow the app, then connect again.
#### 2. Install Devin in a team
1. On the Microsoft Teams settings page, find the **Connected teams** section
2. Click **Install in team** to open the Devin app in Microsoft Teams, then add it to the team or chat you want. Team owners can also add Devin directly from the Teams store.
3. Once installed, the team appears under **Connected teams**
#### 3. Link each user and start using Devin
1. Every user who wants to use Devin from Teams must link their own Microsoft Teams identity. On the Microsoft Teams settings page, click **Link user profile** and sign in with Microsoft.
2. Mention `@Devin AI` in a Team channel or group chat, or message Devin AI in a 1:1 chat, to start a session
> Note: For Devin to work for each user, every individual must link their own account in the Devin dashboard (Settings > Connections > Microsoft Teams). 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 AI` in any Team channel or group chat, or message Devin AI directly in a 1:1 chat.
In Team channels, Devin replies in the thread of your message. In 1:1 and group chats, which don't have threads, Devin replies directly in the chat. You can communicate back and forth just like in the regular Devin chat interface.
In shared channels, the Devin AI app must also be enabled for the channel (installing it in the host Team is not enough), and Devin only replies in the thread when it's @mentioned. Private channels are not supported.
*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 or chat |
| `unmute` | Reverses the above |
| `(aside)`, `!aside` | Causes Devin to ignore the message (useful for commentary on Devin's run in the conversation) |
| `sleep` | Puts Devin to sleep; to wake Devin up, send any message in the thread or chat |
| `!fast`, `!lite`, `!ultra`, `!fusion` | Starts the session in Fast, Lite, Ultra, or Fusion Mode |
| `!swe`, `!swe2` | Starts the session on the newest SWE model enabled for your organization (both keywords behave the same) |
| `!normal` | Switches an active session back to the default Devin mode |
| `new [prompt]` | Starts a new Devin session, optionally with an initial prompt. Only available in 1:1 and group chats, not in channels |
| `org` | Chooses the default organization for new sessions. Only available in 1:1 and group chats, not in channels |
| `help` | Shows help message with available keywords and functions |
Mode keywords (`!fast`, `!lite`, `!ultra`, `!fusion`, `!swe`, `!swe2`, `!normal`) are recognized anywhere in your message and are stripped from the prompt Devin receives. A keyword inside an inline or fenced code span is treated as literal text. Sending a mode keyword in an active Devin thread or chat switches that session's mode mid-session.
### 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).
### Support
If you run into issues with the Microsoft Teams integration, have questions, or come across any objectionable AI-generated content, contact us and we'll open a support ticket for you:
* **Email:** [support@cognition.ai](mailto:support@cognition.ai) — include your organization name, the Teams tenant, and a description or screenshot of the problem.
* **Enterprise customers:** you can also reach out to your Cognition account team.
### 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
>
> * Microsoft sign-in (delegated `User.Read`): connecting your tenant (Teams Administrator or Global Administrator) and linking individual users.
> * Teams bot RSC (per Team/Chat): scoped access to messages/members/settings only where the bot is installed or present.
> * Graph (Application, tenant-wide): granted only if you choose **Grant admin consent**, to locate the app in your tenant's app catalog and remove the bot from a Team from the Devin dashboard.
#### Tenant-wide Microsoft Graph (Application) Permissions
These are app-only (no user delegation) and are granted through tenant-wide admin consent in Microsoft Entra ID when a Global Administrator chooses **Grant admin consent**. If you connect with **Sign in with Microsoft**, Devin uses a delegated sign-in (`User.Read`) to verify the signed-in admin and link their user, and these tenant-wide permissions are not granted. Without admin consent, remove Devin from teams in Microsoft Teams instead of from the Devin settings page.
| 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 | Remove the bot from 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).
##### Team-scoped (Team/Channel)
| Permission | What it allows | Why we need it |
| --------------------------- | ------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- |
| `ChannelMessage.Read.Group` | Read channel messages where the app is installed | Process channel conversations (summaries, triggers, syncing) |
| `ChannelMessage.Send.Group` | 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` | Read team membership | Map identities, permission checks, mention routing |
| `TeamSettings.Read.Group` | Read Team settings | Respect Team-level policies and tailor behavior |
##### Chat-scoped (1:1 and group chats)
| Permission | What it allows | Why we need it |
| ------------------------ | --------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- |
| `ChatMember.Read.Chat` | Read chat participants | Address/respond correctly and support audit trails |
| `ChatMessage.Read.Chat` | Read messages in chats where the bot participates | Process prompts, context, and follow-ups |
| `ChatMessage.Send.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 chats |
| `ChatSettings.Read.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. **Tenant connection** (choose one)
* **Sign in with Microsoft**: a Teams Administrator or Global Administrator signs in with delegated `User.Read`. No tenant-wide admin consent is granted.
* **Grant admin consent**: an Entra ID Global Administrator grants the Graph Application permissions listed above for the whole tenant.
2. **Targeted Installation**
* From **Connected teams** > **Install in team**, you open the Devin AI app in Microsoft Teams and add it to a specific Team or chat. Team owners can also add it from the Teams store.
* During installation, the RSC scopes are granted only to that Team (or to the specific Chat when invoked in a chat).
3. **Operation**
* Reading/sending messages and reading members/settings rely on RSC within installed surfaces.
* Graph Application permissions are only used if admin consent is granted, to locate the app in the tenant's app catalog and to remove the bot from a Team from the Devin dashboard.
#### Least-Privilege Notes
* Connecting Devin to Teams only requires delegated `User.Read` and the RSC permissions above; no tenant-wide Graph permission is needed.
* 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: If admin consent was granted, 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. With admin consent, you can also disconnect a Team from **Connected teams** in the Devin dashboard; without it, remove the Devin app from the Team in Microsoft Teams.
* Data Handling: On uninstall, our integration stops processing events for that Team/Chat and cleans up related subscriptions/links.
### Extend Devin with Microsoft 365
The Teams integration lets you talk to Devin from Teams. To let Devin also work with your Microsoft 365 content during a session, install the Microsoft 365 plugins from the marketplace. For example, you can ask Devin to read a spec from SharePoint, summarize an email thread, or schedule a follow-up meeting.
| Plugin | What Devin can do |
| ------------------------- | ------------------------------------------------------------------- |
| **OneDrive & SharePoint** | Browse, read, upload, and delete files |
| **Mail & Contacts** | Read, organize, and send Outlook mail, and manage personal contacts |
| **Calendar** | List, create, update, and delete events and meetings |
| **To Do** | List, create, update, complete, and delete tasks |
| **Teams** | List teams, channels, and chats, and send messages |
| **Directory** | Search and read Microsoft Entra users and managers |
Each plugin signs in with your Microsoft account and uses delegated Microsoft Graph permissions, so Devin can only access what the signed-in account can access. Depending on your tenant's settings, an admin may need to grant consent for those permissions. You can install only the plugins you need. See [MCP servers and marketplace](/work-with-devin/mcp) to install and configure them.
### Known issues
**Messages in a 1:1 chat with Devin AI show "Failed to send."** This happens when an older version of the Devin AI app is still installed. To fix it, update the Devin AI app to the latest version everywhere it's installed: your personal app, and every Team and group chat where it was added.
**Some group chat members can't see or @mention Devin AI.** When someone adds an app to a group chat, every other member needs permission to use that app in order to see it in the chat roster or in the @mention picker. If the tenant's app permission policy in the Teams admin center blocks third-party apps (globally or for specific users/groups), only users who are allowed to use the app will see it. For everyone else, the bot is effectively invisible and can't be tagged, even though it's technically in the chat. To fix it, a Teams admin should go to Teams admin center > Teams apps > Manage apps, make sure "Devin AI" is allowed, and check the app permission policies assigned to the affected users so the app is permitted for them. Once that's done, the other members may need to refresh their Teams client for the bot to show up in the @mention picker.
# Devin integrations overview
Source: https://docs.devin.ai/integrations/overview
Connect Devin to your tools with native integrations, plugins, and MCP servers. Find connection settings and choose personal or shared access.
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:
| Method | Use it for | Where to set it up |
| --------------------------- | -------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| **Native integrations** | Repository access, starting sessions from Slack or tickets, and other built-in workflows | Follow the integration's guide below. Native connections such as Slack, Jira, and Linear remain under **Settings → Connections**. |
| **Plugins and MCP servers** | Giving Devin tools to query data and act in external services, with optional skills explaining how to use them | Install plugins from **Customize → Plugins** and manage MCP connections in **Customize → MCPs**. |
| **Secrets Manager** | API keys and credentials for command-line tools or custom workflows | Store them in [Devin Secrets](/product-guides/secrets) so Devin can use them during a session. |
For example, connecting the [Slack integration](/integrations/slack) lets you start Devin sessions from Slack. Installing a plugin that contains an MCP server gives Devin tools to use during a session. Follow the native integration guide when you need its session or workflow features.
## 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. Start sessions from any PR by commenting `/devin`.
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.
## Incident Management
Connect Devin to your incident management tools to start investigating as soon as an incident fires.
Connect PagerDuty to trigger Devin automations from incidents and give Devin access to incidents and on-call schedules.
## MCP Marketplace
The [Model Context Protocol (MCP)](/work-with-devin/mcp) allows you to connect Devin to hundreds of external tools and data sources. Install integrations as plugins from the marketplace on the [Customize](/product-guides/plugins) page, or add MCP servers directly on its MCPs tab, to connect Devin with:
* **Monitoring** - Sentry, Datadog, PagerDuty
* **Databases** - PostgreSQL, MySQL, MongoDB
* **Documentation** - Notion, Confluence
* **And many more**
Choose the **Personal**, **Organization**, or **Enterprise** installation scope for the people who need the integration. After installing a plugin, let it finish indexing and connect its MCPs from [Customize → MCPs](https://app.devin.ai/customize?tab=mcps). For OAuth servers, the **Access** setting determines whether members share one authenticated connection or each connect their own account; see [MCP configuration tips](/work-with-devin/mcp#configuration-tips).
If an installed plugin's tools are missing, start with [indexing troubleshooting](/product-guides/plugins#resolve-indexing-issues). For server connectivity or authentication failures, see [MCP troubleshooting](/work-with-devin/mcp#troubleshooting-custom-mcp-servers).
Install plugins, choose a scope, and manage their skills and MCPs.
Connect MCP servers, configure custom servers, and troubleshoot authentication.
## Additional Configuration
Configure pull request templates for Devin's contributions.
Connect Devin to self-hosted source control and artifact repositories.
}>
Connect Devin to Databricks with a service principal, the Databricks CLI, and Unity Catalog grants.
## 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.
# PagerDuty integration
Source: https://docs.devin.ai/integrations/pagerduty
Connect PagerDuty to Devin to trigger automations from incidents and give Devin sessions access to incidents, services, and on-call schedules.
Connect PagerDuty so Devin can start working as soon as an incident fires. PagerDuty incidents trigger Devin [automations](/product-guides/automations), and the PagerDuty MCP server gives Devin sessions access to incidents, services, and on-call schedules.
The PagerDuty page in Connections has three sections, and PagerDuty is fully set up once all three are done:
* **Connection**: the REST API key Devin uses to post incident notes and updates.
* **Webhook**: sends incident events to Devin to trigger automations.
* **App registration**: sets up the PagerDuty MCP server, and lets members connect their PagerDuty accounts.
## Setting up the integration
1. In PagerDuty, go to **Integrations > API Access Keys** and click "Create New API Key". Create a **General Access** key with full access, and copy it. User API tokens are not accepted.
2. In your Devin account at app.devin.ai, go to [Settings > Connections > PagerDuty](https://app.devin.ai/settings/connections/pagerduty), and click "Connect".
3. Select your **API region** (US or EU), then enter:
* **Actor email**: the PagerDuty user that Devin's incident notes and updates are attributed to. We recommend a dedicated service user.
* **General Access REST API key**: the key you created in step 1.
4. Click "Connect". Devin automatically creates a webhook subscription in PagerDuty so it can receive incident events.
## Configure webhook subscriptions
When you connect, Devin creates one account-wide webhook subscription in PagerDuty. It sends these events to Devin:
* `incident.triggered`
* `incident.acknowledged`
* `incident.resolved`
* `incident.priority_updated`
* `incident.reassigned`
* `incident.service_updated`
The **Webhook** section of the settings page shows the subscription's status. If automatic setup fails, click "Retry webhook setup", or add the webhook manually:
1. In the **Webhook** section, click "Add webhook" and copy the webhook URL.
2. In PagerDuty, go to **Integrations > Generic Webhooks (v3)**, and add a webhook that points at that URL with **Account** scope.
3. Select the incident event types listed above.
4. Copy the signing secret PagerDuty shows once, paste it into Devin, and click "Save".
Disconnecting PagerDuty stops incident events and deletes the webhook subscription Devin created. It does not remove the app registration or the PagerDuty MCP server.
## Register Devin as an OAuth app
The PagerDuty MCP server signs in each member with OAuth. PagerDuty doesn't support automatic OAuth client registration, so an admin registers Devin as an OAuth app in PagerDuty and adds it under **App registration** in Connections. Saving the app registration sets up the PagerDuty MCP server for you.
### Create the app in PagerDuty
1. In [Settings > Connections > PagerDuty](https://app.devin.ai/settings/connections/pagerduty), copy the **Redirect URI** shown in the **App registration** section.
2. In PagerDuty, go to **Integrations > App Registration** and click "New App". Enter a name, such as `Devin`, and select **OAuth 2.0**.
3. Select **Scoped OAuth**, and add the redirect URI from Devin as a **Redirect URL**.
4. Under permission scopes, select the scopes you want Devin to have. We recommend `abilities.read`, `escalation_policies.read`, `incidents.read`, `incidents.write`, `oncalls.read`, `priorities.read`, `schedules.read`, `services.read`, `teams.read`, and `users.read`.
5. Register the app, then copy the **client ID** and **client secret**.
### Add the app registration in Devin
1. In the **App registration** section, enter the **Client ID** and **Client secret** from your PagerDuty app.
2. Select the **API region** of your PagerDuty account (US or EU).
3. Leave **Scopes** empty to use the permissions configured on your PagerDuty app. To request only some of them, enter a space-separated list of scopes that are enabled on the app.
4. Click "Save".
Devin then adds the PagerDuty MCP server for your region. On enterprise accounts, it's added once for the whole enterprise and is available in every organization. Otherwise, it's added to your organization. If a PagerDuty MCP server is already installed, Devin doesn't add another one.
Changing the client ID or region disconnects every member's PagerDuty account. Each member needs to connect again.
### Existing PagerDuty MCP servers
A PagerDuty MCP server installed with its own OAuth client ID and secret keeps working, and members who already connected through it stay connected. The **App registration** section shows a warning that it isn't fully connected.
To switch it over, add the app registration, then click "Use app registration" in the warning. Members then connect their PagerDuty accounts again through the app registration.
## Connecting your PagerDuty user account
In addition to the organization-level integration, each team member links their own PagerDuty account to their Devin account. This lets Devin use the PagerDuty MCP server as that member. It's also required to create PagerDuty automations.
To connect your user account, go to [Personal Connections](https://app.devin.ai/account/connections), click "Connect" next to PagerDuty, and approve access in PagerDuty. Use a PagerDuty user from the PagerDuty account your organization connected.
Members can only connect once an admin has added the [app registration](#register-devin-as-an-oauth-app). PagerDuty MCP access is always personal: Devin never uses a shared organization token for it, so each member must connect their own PagerDuty user account before Devin can use PagerDuty tools in their sessions.
## Triggering Devin from PagerDuty
Devin starts working on PagerDuty incidents through [automations](/product-guides/automations). Once PagerDuty is connected, you don't need to set up a separate webhook for each automation.
1. Go to **Automations** and create a new automation.
2. Add a trigger, choose **PagerDuty**, and pick an event:
* **Incident triggered**: a new incident opens.
* **Incident acknowledged**: someone acknowledges an incident.
* **Incident resolved**: an incident is resolved.
* **Incident updated**: an incident's priority, assignment, or service changes.
3. Optionally add conditions to narrow which incidents match:
* **Service**, **Team**, and **Priority**: options load from your PagerDuty account.
* **Urgency** (`high` or `low`) and **Status**.
* **Title**, **Escalation policy**, and **Assignee**.
* **Change** (`priority`, `assignment`, or `service`): for **Incident updated** only.
4. Add a **Start session** action with instructions for Devin, and save.
For example, to investigate high-urgency incidents on your checkout service, use the **Incident triggered** event with the conditions **Service** is `checkout-api` and **Urgency** is `high`. Then add a prompt such as: "Investigate this incident. Check recent deploys and error logs for checkout-api, and find the likely root cause."
To create or edit an automation with a PagerDuty trigger, you must [connect your PagerDuty user account](#connecting-your-pagerduty-user-account) first. Your PagerDuty user must belong to the PagerDuty account your organization connected.
# GitHub Pull Request Templates
Source: https://docs.devin.ai/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: a single **Summary** section that describes what changed and why, written for a reader who hasn't seen the diff. The session URL and requester are appended to the description automatically.
You do not need to copy this unless you want to customize it; supplying any of the supported files above completely replaces the default. If you want a review checklist, notes, or other sections in Devin's PR descriptions, add them to your own template.
## 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.devin.ai/integrations/self-hosted-scm-artifacts
Connect Devin to self-hosted SCM systems like GitLab (15.0+) and artifact repositories like Artifactory using IP allowlisting or load balancers.
## 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** (version 15.0 or later, or another supported 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. Email [enterprise@cognition.ai](mailto:enterprise@cognition.ai) with your specific setup details
2. Reach out to your Cognition account team
3. Share relevant configuration files (with sensitive data redacted) when reporting issues
# Slack
Source: https://docs.devin.ai/integrations/slack
Chat and collaborate with Devin directly in your company Slack: start sessions from any channel, sync threads, and run a session in a dedicated code channel.
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. On the **Integrate Devin with Slack** card, click **Connect**
3. You’ll be prompted to install the Devin app for Slack in your workspace
4. Back on the Slack settings page, the connected workspace shows a "Slack is connected. Link your user profile" banner — click **Link user profile**. Every user in your organization needs to complete this step once to use Devin from Slack.
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. To see it in action, watch [Devin tackle a bug in Slack](/tutorial-library/slack-bug-fix).
*Note that Devin may make mistakes. Please double-check responses.*
### Inline Slack Keywords & Functions
| Keyword | Function |
| --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `!ask` | get a quick codebase answer without starting a full agent. Must come first in the message, right after `@Devin` |
| `!deep` | get a deeper research answer using advanced search, without starting a full agent. Like `!ask`, it must come first in the message |
| `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` | start the session in Fast Mode for quicker responses on simpler tasks |
| `!ultra` | start the session in Ultra Mode for the most complex tasks |
| `!lite` | start the session in Lite Mode |
| `!fusion` | start the session in Fusion Mode |
| `!swe`, `!swe2` | start the session on Cognition's latest SWE model (SWE-2 where available) |
| `!normal` | switch an active session back to the default Devin mode |
| `!new` | force the session to start in a new thread — or, where [code channels](#code-channels) are enabled, in a dedicated channel — 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) |
| `!mac` | run the new session on a macOS VM (requires the macOS entitlement for your organization) |
| `!outpost ` | run the new session on one of your [Outposts](/cloud/outposts/overview#starting-sessions-on-an-outpost) — by exact name, unique prefix, or ID. `!outpost` alone lists the outposts you can use |
| `!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 |
Apart from `!ask` and `!deep`, bang commands (`!fast`, `!lite`, `!ultra`, `!fusion`, `!swe`, `!swe2`, `!normal`, `!new`, `!channel`, `!windows`, `!mac`, `!outpost`, `!dana`, `!data`) 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.
### Code channels
A **code channel** is a Slack channel dedicated to a single Devin session. Instead of following the run in a thread, you get a channel whose name tracks the session title, a status chip showing whether Devin is working / blocked / done, a link back to the session in the webapp, chips and tabs for the pull requests it opens, and a live worklog of the thoughts and tool calls behind each message. Every message you send in the channel goes to that session — no `@Devin` mention needed.
There are two ways a session ends up in a code channel:
* **Start it there with `!new`.** `@Devin !new ` creates the channel and runs the session in it from the beginning. A `!new` from inside a code channel spawns a separate sibling channel for the new session.
* **Let Devin move the conversation.** When a thread conversation turns into real work, Devin can move the session into a code channel itself. The original thread keeps its history and gets a "This session moved to #channel" notice; the session continues in the new channel, and further replies in the old thread no longer reach it. Devin won't move a session whose Slack sync you turned off (see [Sync sessions with Slack threads](#sync-sessions-with-slack-threads)).
You can also create the channel from Slack's own affordance on a message. The first message in an empty code channel becomes the task that starts the session — and if Devin isn't a member of the conversation the channel was spawned from, it says so in the channel, since the quoted message is all the context it has.
Code channels are enabled for every Devin organization. They also depend on Slack's own Code Channels feature, which Slack is rolling out to workspaces gradually — if you don't see them yet in your workspace, that rollout is still in progress and nothing needs to be enabled on Devin's side.
### 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.
### 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` | Join public channels in a workspace | Lets Devin add itself to public channels configured for automations and incident response |
| `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).
# AGENTS.md
Source: https://docs.devin.ai/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.devin.ai/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.** For a video walkthrough, see the [repo setup tutorial](/tutorial-library/repo-setup).
## 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 **Settings > Connections** 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 **Settings > Repositories** 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.devin.ai/onboard-devin/environment/android-emulation
Build, run, and test Android apps on a full emulator inside Devin's session: blueprint setup, adb workflows, Computer Use, and recordings.
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). For the iOS equivalent, see [macOS support](/onboard-devin/environment/macos-support), where Devin drives the iOS Simulator on a macOS session.
### 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.devin.ai/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 optional `runs-on`, `shell`, and `includes` fields, a `post-build` section for organization- and enterprise-level blueprints, and a `clone` section for repository-level blueprints:
```yaml theme={null}
initialize: ... # Install tools and runtimes
maintenance: ... # Install project dependencies
knowledge: ... # Reference info for Devin (never executed)
runs-on: ... # Platforms to build for (default: ["default"])
shell: ... # Shell for `run` steps on Windows (default: "default")
includes: ... # (Git-backed repository root blueprint only) Workspace blueprints
post-build: ... # (Organization/enterprise only) Commands that run after all setup
clone: ... # (Repository-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 |
| `runs-on` | Select one or more build platforms | Used to create one snapshot build per platform |
| `shell` | Select the shell for `run` steps on Windows | Applied to `initialize`, `maintenance`, and `post-build` `run` steps during builds on Windows; ignored on Linux and macOS |
| `includes` | Discover workspace blueprints from a repository root blueprint | Git-backed repository root blueprints only |
| `post-build` | Commands that run after all repositories are cloned and set up (organization/enterprise only) | Yes, during builds — a non-zero exit code fails the build |
| `clone` | Override how the repository is cloned into the snapshot (repository-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
```
## runs-on
The optional top-level `runs-on` field accepts a string or a list of strings. Its default is `["default"]`. The `default` and `linux` labels are case-insensitive aliases for the default Linux platform. Any other label must match a machine configuration registered on your account, such as `windows` or `macos`.
When a block lists multiple platform labels, Devin creates one snapshot build per platform and runs the same steps for each platform. Two blocks in the same file cannot resolve to the same platform; this includes the `default` and `linux` aliases.
For platform-specific setup, see [Windows support](/onboard-devin/environment/windows-support) and [macOS support](/onboard-devin/environment/macos-support).
## shell
The optional top-level `shell` field selects the shell that runs the block's `run` steps on Windows machines. It applies to every `run` step in the block's `initialize`, `maintenance`, and `post-build` sections.
| Value | Behavior on Windows | Behavior on Linux and macOS |
| ------------------- | ----------------------------------------- | ------------------------------------ |
| `default` (default) | `run` steps execute in Git Bash | `run` steps execute in bash |
| `bash` | Alias for `default` | Alias for `default` |
| `powershell` | `run` steps execute in Windows PowerShell | Ignored; `run` steps execute in bash |
Values are case-insensitive. Any other value is rejected with `shell: must be 'default', 'bash', or 'powershell'`.
```yaml theme={null}
runs-on: windows
shell: powershell
initialize:
- name: "Install .NET SDK"
run: |
choco install dotnet-sdk -y
New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\tools" | Out-Null
maintenance: |
dotnet restore
```
With `shell: powershell`:
* Secrets, step-level `env` variables, variables that earlier steps wrote to `$ENVRC`, and the working directory are the same as for bash steps. Read environment variables with PowerShell syntax (`$env:NAME`).
* The [cross-step `$ENVRC` examples](#cross-step-environment-variables-envrc) are written for bash steps. In a PowerShell step, `$env:ENVRC` holds the Git Bash-style path of the file (`/c/...`), so those examples don't apply as written; keep steps that need to persist variables to later steps in a block that uses the default shell.
* Use native Windows paths (`C:\Users\...`) rather than the Git Bash `/c/...` form.
* A PowerShell error (for example, a failing cmdlet or an unknown command) stops the step.
* For native executables, only the exit code of the last one the script runs determines the step result. Check `$LASTEXITCODE` after earlier native commands whose failure should stop the step.
* `uses` steps (GitHub Actions) are not affected.
The setting only affects build steps. Windows sessions still use Git Bash as the default shell. Because `shell` is set per block, a [multi-document blueprint](/onboard-devin/environment/windows-support#multi-platform-blueprint) can use `shell: powershell` in its Windows document without affecting the Linux document. In a block that lists multiple platforms in `runs-on`, the same `run` bodies execute in PowerShell on Windows and in bash everywhere else, so they must be valid in both shells.
## includes
The optional `includes` field only applies to [git-backed blueprints](/onboard-devin/environment/git-backed-blueprints): Devin resolves it when it discovers a repository's root `.devin/blueprint.yaml` file. It is ignored in blueprints authored in the Settings editor, and it is not allowed in an included workspace blueprint.
It accepts a string or a list of strings. Each entry identifies a workspace subdirectory; Devin looks for `/.devin/blueprint.yaml`, and the full file path also works. Paths cannot contain `..`.
Nested includes are rejected, and each workspace path can appear only once. If an included file is missing, Devin treats that workspace as removed.
## post-build
The `post-build` section is available on **organization-level and enterprise-level blueprints only** (it is not supported in repository-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-repository 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 repository and every tool installed by the enterprise, organization, and repository 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` (shell `run` commands and GitHub Actions `uses`), and run from the home directory (`~`).
## clone
For **repository-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 **repository-level** blueprints — it controls how that specific repository is cloned into the snapshot. It has no effect in organization-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`). `maintenance` steps support `run` only; see [GitHub Actions](#github-actions-uses).
### Shorthand and validation rules
* A section provided as a bare string becomes a single `run` step.
* A list entry provided as a bare string becomes a `run` step.
* A step must define `run` or `uses`, but never both.
* `uses` steps can't be used in `maintenance`. The build fails with `'uses' steps are not supported in maintenance sections`.
* `with` is valid only on `uses` steps.
* All `with` values are converted to strings; quote numeric values when the action expects a string.
### YAML document rules
Each `---` document must be a YAML mapping. A top-level sequence is rejected with `each YAML document must be a mapping, not a sequence; use '---' to separate multiple blocks`.
### Shell commands (`run`)
Execute arbitrary shell commands in bash, or in Windows PowerShell on Windows when the block sets [`shell: powershell`](#shell):
```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 (Git Bash on Windows). If any command in a multi-line script fails, the entire step stops immediately. On Windows, set the top-level [`shell`](#shell) field to `powershell` to run commands in Windows PowerShell instead.
* Org-level blueprints execute in the home directory (`~`).
* Repo-level blueprints execute in the cloned repository root.
* Each step has a timeout of 3 hours.
* Secrets are automatically available as environment variables.
### GitHub Actions (`uses`)
Run GitHub Actions directly in your blueprint's `initialize` (or `post-build`) section:
```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"` |
Node.js actions (`node16`, `node20`, `node24`) and composite actions are supported. Docker actions are supported on Linux builds only, not on [Windows](/onboard-devin/environment/windows-support) builds. `post` cleanup steps are skipped. See [GitHub Actions limitations](/onboard-devin/environment/github-actions#limitations).
`uses` steps are not supported in `maintenance`. Actions can only run during `initialize` (and `post-build`); a `uses` step in `maintenance` fails the build.
**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. They are scrubbed from the snapshot image itself, so credentials are never baked into saved machine images. Outside of blueprint commands, secrets are not exported to every shell; Devin binds them to the specific commands that need them.
* **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**: Available as environment variables in that repo's blueprint steps and commands. Configure these in the **Secrets** tab of the repository's blueprint editor.
**Build-only secrets**: Enterprise secrets can be marked **Build only** when you add them in the enterprise blueprint editor's **Secrets** tab. This option is not available for org or repository secrets. A build-only secret is available only to enterprise and org blueprint steps during snapshot builds. It is removed before repositories are cloned, so repo blueprint steps and `post-build` steps cannot read it, and it is never injected into Devin sessions. Use it for credentials needed only during enterprise or org setup (e.g., downloading private artifacts in the enterprise blueprint's `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 `settings.xml` or other 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 (leading and trailing underscores are removed), prefixed with `FILE_`.
File names must be plain file names: they cannot start with a dot or contain path separators, whitespace, or control characters. To use a dotfile such as `.npmrc`, upload it under a name without the leading dot (for example, `npmrc`) and copy it into place in a blueprint step.
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
- name: "Configure npm"
run: cp "$FILE_NPMRC" ~/.npmrc
```
## 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.devin.ai/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 organization access to its repositories 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 repository."*
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. Build time depends on how many repositories you have configured and how much work your blueprints do, so 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 repositories, 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 organization/enterprise blueprints and an optional `clone` block for repository-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 (organization/enterprise only) | During builds, after all repositories are cloned and set up. A non-zero exit fails the build. |
| `clone` | Override git-clone defaults for the repository (repository-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`** (organization- and enterprise-level only) runs after every repository 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-repository 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`** (repository-level only) overrides defaults Devin uses when cloning the repository 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 > Organization blueprint | Tools shared across all repositories: language runtimes, package managers, Docker auth |
| **Repository** | Settings > Environment > Blueprints > \[repo name] | Project-specific setup: `npm install`, lint/test/build commands |
Blueprints are **additive**: repository blueprints build on top of the organization blueprint. A repository's `maintenance` can use tools installed by the organization's `initialize`. If only one repository needs a tool, put it in that repository's blueprint. If every repository needs it, put it in the organization blueprint.
For monorepos, a repository can have a root blueprint plus per-subdirectory workspace blueprints, each with its own `initialize`, `maintenance`, and `knowledge` sections and working directory. See [Workspaces and monorepos](/onboard-devin/environment/workspaces) for setup instructions and examples.
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, repositories, and dependencies pre-installed. All configured repositories 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. Organization blueprint (runs in ~):
a. initialize
b. maintenance
3. Clone all repositories (up to 10 concurrent).
Each repository's blueprint may override clone defaults via the
`clone` block (branch/tag, depth, submodules, LFS, etc.).
4. For each configured repository, in the order shown in Settings
(runs in ~/repos/):
a. initialize
b. maintenance
5. post-build steps (organization blueprint's first, then enterprise's; runs in ~)
6. Health check, then snapshot is saved
```
Layers are **additive**: repository-specific commands can use tools installed by the organization or enterprise blueprint. Lower levels cannot override what a higher level set up. Build time scales with the number of configured repositories and the work your blueprints do. Individual steps time out after 3 hours.
### 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 repositories.
2. `maintenance` commands (enterprise, organization, and repository) 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 repository's `knowledge` entries are loaded into Devin's context.
**Knowledge is per-repository.** If you have 5 repositories 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 |
| ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Queued** | The build is accepted and waiting for a machine. |
| **Building** | Setup steps are running on the build machine. |
| **Success** | All steps completed. Snapshot is ready. |
| **Partial** | Some repository-level steps failed, but the snapshot is usable. Repositories that succeeded work normally; repositories that failed need their blueprints fixed. |
| **Failed** | The snapshot is not usable. This happens when an organization or enterprise blueprint fails (including its post-build steps), a repository fails to clone, or the machine does not pass the final health checks. |
| **Cancelled** | Superseded by a newer build or manually cancelled. |
A **partial** build still produces a working snapshot. Every repository was cloned, so all of your source code is available in the session — only the setup steps of the failing blueprints did not run. If one of five repositories has a broken blueprint, the other four are fully set up, and Devin can still read and work on the fifth.
**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 organization but not added to the environment. Not cloned. |
**Included vs. configured:** An "included" repository is cloned so Devin can access the code, but has no custom setup commands. A "configured" repository 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 repository gets its own blueprint. During a build, all repositories are set up in the same snapshot, cloned into separate directories with dependencies installed independently.
If two repositories 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 organization-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), open its menu, and click **Use this build**. While pinned, periodic refreshes are skipped, the build is badged **Locked**, 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 repository, the repository was renamed/moved/deleted, or there was a transient network issue.
**Fix:** Verify repository access in your Git provider settings. Remove and re-add the repository 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 blueprint step has a 3-hour timeout. Repository clones and pulls have the same 3-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 repository, then multiple repositories with shared dependencies, then multiple organizations.
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 repository as `.devin/blueprint.yaml` and sync via the API or UI.
Enterprise-wide environment management: 3-tier hierarchy, secrets, and cross-organization configuration.
# Devin macOS support
Source: https://docs.devin.ai/onboard-devin/environment/macos-support
Run Devin on macOS VMs with Xcode and the iOS Simulator to build, run, and test Apple-platform apps.
Devin now has access to macOS virtual machines. This means Devin can now build and test iOS and macOS applications, and [upload builds to TestFlight](/onboard-devin/environment/testflight).
For a step-by-step walkthrough, see [Build an iOS app with Devin](/tutorial-library/ios-app).
If you're on a Dedicated SaaS deployment, please reach out to your account team to enable macOS VMs.
## How it works
macOS support is built on the same [declarative configuration](/onboard-devin/environment/blueprints) system as Linux. The `runs-on` field in your blueprint tells Devin which platform to build and run on, and each platform gets its own snapshot.
The main differences from Linux are the shell, the file system layout, and the package manager:
| Aspect | Linux (default) | macOS |
| ---------------- | ---------------------- | ------------------------------------ |
| Home directory | `/home/ubuntu` | `/Users/devin` |
| Repo directory | `~/repos/` | `/Users/devin/repos/` |
| Shell | `bash` | `zsh` |
| Package manager | `apt-get` | `brew` (Homebrew at `/opt/homebrew`) |
| File attachments | `/home/ubuntu/.files/` | `/Users/devin/.files/` |
## Starting a macOS session
You can choose macOS per session:
* **Blueprint**: add `runs-on: macos` so the repo's snapshot is built for macOS (see below).
* **Slack**: use the `!mac` [bang command](/integrations/slack) to start a session on a macOS VM.
* **API**: set `platform: "macos"` when creating a session, schedule, or automation. See the [API reference](/api-reference/overview).
## Writing macOS blueprints
### Single-platform blueprint
If your repository only targets Apple platforms, use `runs-on: macos` at the top level:
```yaml theme={null}
runs-on: macos
initialize:
- name: "Install build tooling"
run: |
brew install xcodegen swiftlint xcbeautify
maintenance: |
xcodebuild -resolvePackageDependencies -project MyApp.xcodeproj -scheme MyApp
knowledge:
- name: build
contents: xcodebuild -scheme MyApp -destination 'platform=iOS Simulator,name=iPhone 17' build
- name: test
contents: xcodebuild -scheme MyApp -destination 'platform=iOS Simulator,name=iPhone 17' test
- name: lint
contents: swiftlint
```
### Multi-platform blueprint
To build the same repository for more than one platform, 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: |
apt-get update && apt-get install -y build-essential
maintenance: |
npm install
knowledge:
- name: test
contents: npm test
---
runs-on: macos
initialize: |
brew install cocoapods
maintenance: |
npm install
(cd ios && pod install)
knowledge:
- name: test
contents: npm test
```
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: macos`) is rejected by the backend. 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) |
| `macos` | macOS |
| `windows` | Windows |
You can specify `runs-on` as a string or a list:
```yaml theme={null}
# Single platform
runs-on: macos
# Multiple platforms in one block (same commands run on each)
runs-on: [default, macos]
```
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`). For platform-specific commands (like `apt-get` on Linux or `brew` on macOS), use the [multi-document format](#multi-platform-blueprint) instead.
## Usage and cost
macOS sessions currently consume the same usage as equivalent Linux sessions, with no macOS surcharge.
This is **promotional launch pricing** and is subject to change.
For details on how usage is metered, see [Usage](/admin/billing/usage#macos-sessions).
## What's preinstalled
macOS session images ship with the Apple toolchain already installed, so your blueprint doesn't have to download it:
| Category | Included |
| --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Xcode | The latest Xcode 26 release as the default at `/Applications/Xcode.app`, plus the Xcode 27 prerelease alongside it (e.g. `/Applications/Xcode-27.0-RC.app`) |
| Simulators | One iOS Simulator runtime per installed Xcode (iOS 26 and iOS 27), each with a preconfigured iPhone device |
| Apple tooling | `xcodebuild`, `xcrun`, `simctl`, Swift, and the Metal toolchain |
| Package manager | Homebrew at `/opt/homebrew` |
| Languages | Node.js, Python, Java, Rust (plus `npm`, `yarn`, `pnpm`) |
| CLI tools | `git`, `git-lfs`, `gh`, `jq`, `ripgrep`, `ffmpeg`, `wget`, `direnv` |
| Browser | Google Chrome |
Versions move as Apple ships new releases and the image is refreshed. To see exactly what a session has, ask Devin to run:
```bash theme={null}
sw_vers
xcodebuild -version
ls -d /Applications/Xcode*.app
xcrun simctl list runtimes
```
### Selecting an Xcode version
The default Xcode is the one `xcode-select` points at. To use another installed version for a single command, set `DEVELOPER_DIR`:
```bash theme={null}
DEVELOPER_DIR=/Applications/Xcode-27.0-RC.app/Contents/Developer /usr/bin/xcodebuild -version
```
Use `/usr/bin/xcodebuild` (the shim that honors `DEVELOPER_DIR`) rather than a `xcodebuild` resolved from a specific Xcode's `Contents/Developer/usr/bin` on `PATH`, which reports its own version regardless of `DEVELOPER_DIR`.
Or switch the default for the whole session:
```bash theme={null}
sudo xcode-select -s /Applications/Xcode-27.0-RC.app
```
Put whichever you need in your blueprint so every session starts on the right toolchain.
## macOS session behavior
### Shell
macOS sessions use **zsh** as the default shell. Most POSIX shell commands work unchanged from Linux blueprints, but note the BSD userland: `sed -i` requires an argument (`sed -i ''`), and GNU tools like `gsed`, `gdate`, and `greadlink` come from the Homebrew `coreutils` formula.
### Paths
```yaml theme={null}
# Linux paths
- run: cp config.json ~/.config/myapp/config.json
# macOS paths
- run: cp config.json /Users/devin/.config/myapp/config.json
```
Repositories are cloned to `/Users/devin/repos/`, and files you upload to a session are written to `/Users/devin/.files/`.
### Secrets
[Secrets](/product-guides/secrets) are available as environment variables during sessions (`$SECRET_NAME`), same as on Linux. This is how to supply App Store Connect API keys, signing credentials, or private registry tokens:
```yaml theme={null}
maintenance:
- name: "Configure private Swift package registry"
run: |
git config --global url."https://$GIT_TOKEN@github.com/".insteadOf "https://github.com/"
```
For the App Store Connect secrets and setup that TestFlight uploads need, see [Upload iOS builds to TestFlight](/onboard-devin/environment/testflight).
### Session sleep and wake
Sessions snapshot to disk when they sleep. Everything on disk survives a wake: installed tools, cloned repos, build caches, derived data. Running processes do not: dev servers, simulators, and watchers need to be restarted after the session wakes up.
### Computer Use
[Computer Use](/work-with-devin/computer-use) works on macOS sessions: Devin gets a full macOS desktop with Chrome, mouse, and keyboard, and can test macOS-native apps as well as web apps, and [record](/work-with-devin/testing-and-recordings) what it does. Devin uses the Command key for macOS shortcuts (⌘C, ⌘V, ⌘Tab) rather than Control.
### iOS Simulator
Devin can boot and drive the iOS Simulator directly:
```bash theme={null}
open -a Simulator # boot the default device
xcrun simctl list devices # see available devices
xcrun simctl boot "iPhone 17" # boot a specific device
xcrun simctl install booted MyApp.app
xcrun simctl launch booted com.example.MyApp
```
The **iOS Simulator** tab in the session workspace streams the booted simulator, so you can watch Devin tap through your app in real time. It's the Apple equivalent of [Android emulator support](/onboard-devin/environment/android-emulation).
## Tips & Tricks
### Warm build caches
A cold Xcode build results in a suboptimal developer experience, with longer build time. Use the `maintenance` field in `environment.yml` to prewarm the cache.
```yaml theme={null}
runs-on: macos
initialize:
- name: "Install tooling"
run: brew install cocoapods xcodegen swiftlint
maintenance:
- name: "Resolve dependencies and warm the build"
run: |
xcodebuild -resolvePackageDependencies -project MyApp.xcodeproj -scheme MyApp
xcodebuild -scheme MyApp -destination 'platform=iOS Simulator,name=iPhone 17' build-for-testing
- name: "Pre-boot the simulator"
run: xcrun simctl boot "iPhone 17" || true
```
Resolved Swift packages, CocoaPods, and DerivedData will persist in the snapshot, so new sessions start from an incremental build.
### Network access
Builds that fetch from CocoaPods, Swift Package Manager, Firebase, or a private registry need those hosts reachable. If your organization runs with a restricted network policy, make sure the macOS allowlist covers the same registries your Linux builds use. The two are configured separately, and a missing entry usually shows up as a dependency-resolution or TLS failure in the middle of a build.
### Running containers
macOS VMs have no nested hardware virtualization, so a container runtime has to fall back to QEMU's software emulation (TCG). Colima detects this and switches to emulation on its own:
```bash theme={null}
brew install colima docker qemu lima
colima start --vm-type qemu --arch aarch64 --cpu 4 --memory 8 --disk 30
```
The VM takes two to four minutes to become usable, and the first start can time out waiting for SSH while the emulated guest brings up networking, so retry the `colima start` if it fails. Containers then run roughly 15 to 25x slower on CPU than native, with a few seconds of startup each; pulls run at host network speed. That's fine for a linting or packaging container, painful for compiling. For container-heavy work, use a Linux session or point the macOS session at a remote Docker daemon.
### Don't install Xcode in a blueprint unless you have to
Xcode is a multi-gigabyte download, and Apple gates it behind an Apple ID. Prefer the versions already in the image, selected with `DEVELOPER_DIR` or `xcode-select`. If you need a different release or beta, you can store an Apple ID as a [secret](/product-guides/secrets) and have the blueprint download that version, at the cost of a much slower build.
## Limitations
| Limitation | Detail |
| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| Docker and containers | No nested hardware virtualization, so containers run under software emulation. See [Running containers](#running-containers). |
| Physical devices | No USB passthrough, so builds and tests run on simulators, not physical iPhones or iPads. |
| Xcode downloads | Fetching another Xcode or simulator runtime requires supplying Apple ID credentials and a long download. |
| Performance measurement | Instruments-style timing and profiling inside a VM isn't representative of real device performance. |
## Troubleshooting
**Builds are much slower in the first session after a snapshot rebuild.** DerivedData was rebuilt from scratch. Add a `build-for-testing` step to `maintenance` so the snapshot carries a warm build.
**`xcodebuild` picks the wrong toolchain.** Check `xcode-select -p`, and set `DEVELOPER_DIR` explicitly in the blueprint step.
**A destination isn't found.** Run `xcrun simctl list devices available` to see what the installed runtimes actually provide, and match the `-destination` name and OS to it.
**Dependency resolution hangs or fails with a TLS error.** The host is likely missing from your organization's network allowlist for macOS. See [Network access](#network-access).
# Upload iOS builds to TestFlight with Devin
Source: https://docs.devin.ai/onboard-devin/environment/testflight
Set up App Store Connect, an API key, and Devin secrets so Devin can archive an iOS app on a macOS VM and upload the build to TestFlight.
**Time:** 2–10 minutes. **Requires:** a paid [Apple Developer Program](https://developer.apple.com/programs/) membership.
Devin can archive an iOS app, sign it, upload it to TestFlight, and add the build to a beta group. It runs `xcodebuild` on a [macOS VM](/onboard-devin/environment/macos-support) and authenticates with an App Store Connect API key that you store as Devin secrets.
Before Devin can upload a build, you need to:
1. Set up your app in App Store Connect.
2. Create an App Store Connect API key.
3. Add the key and your Team ID to Devin as secrets.
4. Make sure Devin can reach Apple's servers.
Uploading to TestFlight requires macOS sessions. If you're on a Dedicated SaaS deployment, contact your account team to enable macOS VMs.
## Requirements
| Requirement | Detail |
| ---------------------------------- | ---------------------------------------------------------------------- |
| Apple Developer Program membership | A paid membership for the team that owns the app. |
| App record in App Store Connect | An app with the same bundle ID as the Xcode project. |
| App Store Connect API key | A team key with the **App Manager** role. |
| Devin secrets | `ASC_KEY_ID`, `ASC_ISSUER_ID`, `ASC_PRIVATE_KEY`, and `APPLE_TEAM_ID`. |
| Network access | Devin's macOS VM can reach Apple's servers. |
## Set up App Store Connect
Do these steps in the Apple Developer portal and App Store Connect. Devin can't do them for you: most require an Account Holder or Admin, and some need two-factor authentication on a person's Apple Account.
The Account Holder signs in to [App Store Connect](https://appstoreconnect.apple.com) and accepts any pending agreements in **Business**. Uploads fail while a required agreement is pending.
In the [Apple Developer portal](https://developer.apple.com/account/resources/identifiers/list), go to **Certificates, Identifiers & Profiles → Identifiers** and register an App ID that matches the bundle ID of your app target. Skip this step if the identifier already exists.
In App Store Connect, go to **Apps**, click **+**, and select **New App**. Choose the platform, name, primary language, the bundle ID from the previous step, and a SKU. TestFlight uploads fail if no app record exists for the bundle ID.
Open the app, go to **TestFlight**, and create a group:
* **Internal testing**: testers must be users on your App Store Connect team. Builds are available as soon as processing finishes.
* **External testing**: testers can be anyone with an email address or a public link. Fill in **Test Information** (beta app description, feedback email, and review contact details) first. The first build for each version goes through Beta App Review.
Every build must answer the export compliance question before testers can install it. To skip the question for each build, set `ITSAppUsesNonExemptEncryption` in your app's `Info.plist`. Set it to `NO` if the app uses only exempt encryption, such as HTTPS.
## Create an App Store Connect API key
Devin authenticates with an App Store Connect API key, not an Apple Account. The key doesn't need two-factor authentication.
In App Store Connect, go to **Users and Access → Integrations → App Store Connect API**. If API access isn't enabled yet, the Account Holder clicks **Request Access** and accepts the terms.
Under **Team Keys**, click **+**. Enter a name, such as `Devin TestFlight`, and select the **App Manager** role. You need the Admin role to generate a key. If Xcode can't create a distribution certificate with an App Manager key, generate a key with the **Admin** role instead.
Click **Download** next to the new key to save `AuthKey_.p8`. Apple lets you download the file only once. If you lose it, revoke the key and generate a new one.
The **Issuer ID** is shown above the keys table. The **Key ID** is in the key's row.
In the [Apple Developer portal](https://developer.apple.com/account), go to **Membership details** and copy the **Team ID**. It's a 10-character string, such as `A1B2C3D4E5`.
Anyone who has the `.p8` file can upload builds and manage TestFlight for every app on your team. Store it only in Devin secrets, and don't commit it to a repository.
## Add secrets to Devin
Add the following values as raw secrets on the [Secrets page](https://app.devin.ai/settings/secrets):
| Secret name | Value | Where to find it |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- |
| `ASC_KEY_ID` | Key ID, such as `2X9R4HXF34` | App Store Connect → Users and Access → Integrations → App Store Connect API |
| `ASC_ISSUER_ID` | Issuer ID, a UUID | Same page, above the keys table |
| `ASC_PRIVATE_KEY` | Full contents of `AuthKey_.p8`, including the `-----BEGIN PRIVATE KEY-----` and `-----END PRIVATE KEY-----` lines | The file you downloaded when you created the key |
| `APPLE_TEAM_ID` | Team ID, such as `A1B2C3D4E5` | Apple Developer portal → Membership details |
To copy the private key on a Mac, run:
```bash theme={null}
pbcopy < AuthKey_.p8
```
Choose a scope for the secrets:
* **Organization**: every session in your organization can use the key. Use this scope when the team ships builds with Devin.
* **Personal**: only sessions you start can use the key.
Devin binds secrets to the commands that need them; they are not exported into every shell, so scripts should read the variable Devin binds for them. Secrets added while a session is running are picked up by later commands. For more on scopes and injection, see [Secrets](/product-guides/secrets).
## Allow network access
Devin's macOS VM needs to reach Apple's servers to sign and upload builds. If your organization uses a restricted network policy, add `api.appstoreconnect.apple.com` and the other Apple hosts that `xcodebuild` uses for signing and uploads. Allowing `*.apple.com` covers them.
A blocked host usually shows up as an authentication error, not a network error. See [Troubleshooting](#troubleshooting).
## Upload a build
Start a macOS session and ask Devin to upload a build:
```text theme={null}
Archive the MyApp scheme and upload it to TestFlight. Use a build number
higher than the latest build in App Store Connect, add the build to the
"QA" group, and send me the build number when it's done.
```
Devin uses the secrets to do the following:
1. Write `ASC_PRIVATE_KEY` to `~/.appstoreconnect/private_keys/AuthKey_$ASC_KEY_ID.p8` with `0600` permissions.
2. Check the latest build number with the App Store Connect API and pick a higher one.
3. Archive the app with `xcodebuild archive`.
4. Sign and upload the build with `xcodebuild -exportArchive`.
5. Wait for processing to finish, then add the build to the beta group with the App Store Connect API.
The export step uses an export options plist with `destination` set to `upload`:
```xml theme={null}
methodapp-store-connectdestinationuploadteamIDA1B2C3D4E5signingStyleautomatic
```
And these commands:
```bash theme={null}
xcodebuild -project MyApp.xcodeproj -scheme MyApp \
-configuration Release -destination 'generic/platform=iOS' \
-archivePath build/MyApp.xcarchive \
CURRENT_PROJECT_VERSION= archive
xcodebuild -exportArchive \
-archivePath build/MyApp.xcarchive \
-exportOptionsPlist ExportOptions.plist \
-exportPath build/export \
-allowProvisioningUpdates \
-authenticationKeyID "$ASC_KEY_ID" \
-authenticationKeyIssuerID "$ASC_ISSUER_ID" \
-authenticationKeyPath ~/.appstoreconnect/private_keys/AuthKey_$ASC_KEY_ID.p8
```
`-allowProvisioningUpdates` lets Xcode create the distribution certificate and provisioning profile with the API key, so the VM doesn't need signing assets installed.
If your repository already has a release script, such as a `fastlane` lane or a `make` target, tell Devin to use it. `fastlane` accepts the same key through `app_store_connect_api_key`.
### Save the steps in your blueprint
To avoid repeating the instructions in every prompt, add them to the `knowledge` section of your repository's [blueprint](/onboard-devin/environment/blueprints):
```yaml theme={null}
runs-on: macos
knowledge:
- name: testflight
contents: |
To upload a TestFlight build:
1. Write $ASC_PRIVATE_KEY to ~/.appstoreconnect/private_keys/AuthKey_$ASC_KEY_ID.p8 (chmod 600).
2. Use a build number higher than the latest build in App Store Connect.
3. Archive the MyApp scheme, then run xcodebuild -exportArchive with
ExportOptions.plist (destination: upload, teamID: $APPLE_TEAM_ID),
-allowProvisioningUpdates, and the -authenticationKey* flags.
4. Add the build to the "QA" beta group.
```
## Troubleshooting
**`No Accounts with App Store Connect Access` or `Failed to Use Accounts` during export.** Check network access first. If the VM can't reach Apple's servers, `xcodebuild` reports this error even when the key is valid. Look for `ITunesConnectFoundationErrorDomain Code=-1003` in the lines above it. If the network is fine, check that the key has the App Manager role.
**`No profiles for '' were found`.** The bundle ID isn't registered for the team in `APPLE_TEAM_ID`, or no app record exists for it in App Store Connect.
**`The provided entity includes an attribute with a value that has already been used`.** The build number was already used for this version. Upload again with a higher build number.
**The build uploads but testers can't install it.** Check the build in App Store Connect → TestFlight. It may still be processing, be missing export compliance information, or be waiting for Beta App Review.
**Xcode can't create a distribution certificate.** The key's role doesn't allow managing certificates. Generate a key with the Admin role, or have an Admin create the distribution certificate in the Apple Developer portal.
**Environment variables are empty in the session.** Secrets are not exported into every shell. Ask Devin to bind the secret (for example `ASC_KEY_ID`) to the command that needs it, and check that the secret exists on the [Secrets page](https://app.devin.ai/settings/secrets) with a scope the session can use.
# Windows support
Source: https://docs.devin.ai/onboard-devin/environment/windows-support
Run Devin on Windows VMs: configure the runs-on and shell blueprint fields, Git Bash or PowerShell steps, Chocolatey installs, and app testing.
Devin supports Windows as a build and session platform. By default, Windows environments use the same bash shell (Git Bash) as Linux, so most blueprint commands work across both platforms without modification. Blueprints can also run their Windows setup steps in [PowerShell](#the-shell-field).
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. The optional `shell` field lets a Windows block run its `run` steps in Windows PowerShell instead of Git Bash.
Since both platforms use bash by default, 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) |
| `macos` | [macOS](/onboard-devin/environment/macos-support) |
| `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 `---`.
## The `shell` field
By default, a block's `run` steps execute in Git Bash on Windows. Set the optional top-level `shell` field to `powershell` to write setup steps with native PowerShell cmdlets, syntax, and Windows paths instead:
```yaml theme={null}
runs-on: windows
shell: powershell
initialize:
- name: "Install build tools"
run: |
choco install visualstudio2022buildtools -y
New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\tools" | Out-Null
maintenance:
- name: "Restore packages"
run: |
Write-Host "Restoring packages"
dotnet restore
```
The setting is per block. In a [multi-platform blueprint](#multi-platform-blueprint), set `shell: powershell` only in the `runs-on: windows` document so the Linux document keeps using bash. It only affects build steps; Windows sessions still use Git Bash as the default shell. For the accepted values, how secrets and environment variables reach PowerShell steps, and error handling, see [`shell`](/onboard-devin/environment/blueprint-reference#shell) in the blueprint reference.
## 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. Unless a block sets [`shell: powershell`](#the-shell-field), blueprint `run` steps also execute in Git Bash, so standard bash syntax works on both platforms:
```yaml theme={null}
- run: |
export MY_VAR="hello"
echo $MY_VAR
```
### Paths
Git Bash uses POSIX-style paths (`/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
```
Steps in a [`shell: powershell`](#the-shell-field) block use native Windows paths instead:
```yaml theme={null}
- run: Copy-Item config.json "$env:USERPROFILE\.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.devin.ai/onboard-devin/index-repo
Index your repositories from the DeepWiki settings page so Devin can power Ask Devin and DeepWiki with an up-to-date understanding of your code.
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 **DeepWiki** and scroll to the **Repositories** section, which lists the repositories your organization has already indexed
4. Click **Add**
5. In the **Add repositories** dialog, check every repository you want Devin to index, then click **Add repositories**
6. Wait for indexing to complete — newly added repositories show **Indexing…** until they're ready, which may take a few minutes depending on repository size
Devin indexes each repository's default branch. To index additional branches, click a repository in the list to open its **Indexed branches** page, then use the **Add branch** dropdown to pick a 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.devin.ai/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 is deprecated and will be removed in a future update. Existing Knowledge is being migrated to [Skills in Plugins](/product-guides/plugins) automatically — the migration is rolling out gradually and requires no action on your part. Use Skills for new instructions and context you want to share with Devin.
## Knowledge 101
Knowledge lets you 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.devin.ai/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.devin.ai/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** template, which watches a Slack channel for bug reports
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 on the **Customize → MCPs** tab (or install their plugins from the plugin marketplace) 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.devin.ai/product-guides/automations
Set up Devin automations: event-driven workflows that start Devin sessions from Slack, GitHub, Linear, schedules, and webhooks.
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. You can also manage automations declaratively with the [Terraform provider](/api-reference/terraform-provider). For a video walkthrough with four examples, see the [Devin Automations tutorial](/tutorial-library/automations).
## 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, issue comment, PR opened/updated, PR review, check run (CI), push | Auto-fix CI failures, respond to `/devin` comments on issues |
| **GitLab** | Merge request, MR comment, issue, issue comment, push, pipeline | Auto-fix failing pipelines, respond to comments on merge requests |
| **Linear** | Issue created, label added, status changed, priority changed, assigned, moved to a team | Triage bugs when labeled, implement tickets when assigned to Devin |
| **Jira** | Issue created, issue updated, label added, status changed, assigned, commented | Implement tickets when assigned to Devin, track status changes |
| **Pylon** | Issue created, tag added, status changed | Triage customer bug tickets filed in Pylon |
| **PagerDuty** | Incident triggered, acknowledged, resolved, updated | Investigate high-urgency incidents as soon as they fire. See the [PagerDuty integration](/integrations/pagerduty) |
| **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 |
Non-schedule sources appear in the trigger picker once the corresponding integration is connected in **Settings > Connections**.
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** and choose **Create** to open a blank editor (if you have no automations yet, click **Create manually** on the landing page instead). The same menu also offers **Template** (opens the template gallery) and **Generate with Devin** (starts a session that builds the automation with you)
3. Configure the trigger, conditions, and action
4. Click **Create automation**
### From a template
1. Navigate to **Automations** in the sidebar
2. Click **Create automation** > **Template** (if you have no automations yet, click **Create from template** on the landing page instead), or go directly to `/automations/templates`
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 click **Create automation**
### Using natural language
On the automations page, click **Create automation** > **Generate with Devin** (if you have no automations yet, click the **Generate with Devin** card on the landing page instead). Devin opens a new session to help you build the automation. Describe what you want — 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 create.
## 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. A channel condition is added by default; you can remove it to match messages across channels, but every condition group then needs at least one other filter (for example message text or sender type — **Include thread replies** alone is not enough).
* **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.
For channel-scoped triggers, Devin must be invited to the Slack channel. 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**: Fires on issue events (opened, closed, reopened, edited, labeled).
* **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.
### GitLab triggers
GitLab triggers fire on project events in your connected GitLab instance:
* **Merge request**: Fires on MR actions (opened, closed, merged, reopened, approved, updated).
* **MR comment**: Fires when a comment (note) is posted on a merge request, including diff review threads.
* **Issue**: Fires on issue actions (opened, closed, reopened, updated).
* **Issue comment**: Fires when a comment is posted on an issue.
* **Push**: Fires on pushes to a branch.
* **Pipeline**: Fires when a pipeline reaches a given status — filter by status (e.g. `failed`) to auto-fix failing pipelines.
### 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.
* **Issue moved**: Fires when an issue is moved to a different team — the trigger's team filter matches the destination team.
### Jira triggers
Jira triggers fire on issue events in your connected Jira site. You can filter by project, labels, status, assignee, and epic:
* **Issue created**: Fires when a new issue is created.
* **Issue updated**: Fires when an issue's fields change.
* **Label added**: Fires when a label is applied to an issue.
* **Status changed**: Fires when an issue's status changes.
* **Assigned**: Fires when an issue is assigned to someone.
* **Comment created or edited**: Fires when a comment is added or edited on an issue.
### 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
Pass the webhook secret in any one of these ways:
* `X-Webhook-Secret: ` header
* `Authorization: Bearer ` header
* `?secret=` query parameter
Prefer a header — query strings are often captured in proxy, CDN, and server access logs.
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 cleared, the automation runs without that limit. New automations start with no ACU limit and a **Rate limit** of 50 runs per hour (150 per hour for Slack channel-watching triage automations); templates apply the same defaults.
### 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. An automation's network policy only ever narrows access: it is intersected with the [security profile](/product-guides/security-profiles) governing the automation's sessions.
## 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 "Fix Sentry Errors Daily" template recommends the Sentry MCP so Devin can query Sentry for unresolved errors. The "Investigate Alerts Triggered" template recommends the Datadog MCP for pulling metrics and traces.
Enable MCP servers on the **Settings → Connections → MCPs** tab (or install their plugins from the plugin marketplace) 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 | Monitoring & Triage | Watches a Slack channel for bug reports — Devin triages each one, investigates the root cause, and replies in the thread |
| Triage Support Requests | Monitoring & Triage | Watches a support channel — Devin drafts an accurate reply in the thread and flags anything needing escalation |
| Triage Customer Bug Tickets | Monitoring & Triage | When a customer files an issue in Pylon, Devin reproduces the bug, investigates the codebase, and reports findings for the support team |
| Investigate Support Escalations | Monitoring & Triage | When support tags a Pylon issue for engineering, Devin finds the root cause, reproduces it, suggests a fix, and reports back in the internal Slack thread — tagging the likely owner and filing a Linear ticket if that's where escalations live |
| Investigate Alerts Triggered | Monitoring & Triage | When an alert lands in your Slack alerts channel, Devin uses the Datadog MCP to pull metrics, logs, and traces, then posts a root-cause analysis in the thread |
| Fix Sentry Errors Daily | Monitoring & Triage | Every morning, pulls the top unresolved Sentry errors, investigates each one, and opens fix PRs |
| Daily Error Report | Monitoring & Triage | Every morning, scans Datadog for new and spiking errors across your services and posts a concise report to Slack |
| Recurring Capacity Planning | Monitoring & Triage | On a schedule, reviews usage and resource-utilization trends to forecast capacity needs and flag services approaching their limits |
| Fix CI Failures | CI/CD & Release | Automatically fixes failing CI checks on non-Devin PRs — reads the build logs, identifies the root cause, pushes a fix, and verifies it passes |
| /devin Issue Fix | CI/CD & Release | When someone comments `/devin` on a GitHub issue, Devin investigates the codebase and opens a fix PR |
| Weekly Dependency Update | CI/CD & Release | Every Monday, scans for outdated packages, reviews changelogs for breaking changes, and opens update PRs grouped by risk level |
| Weekly Changelog | CI/CD & Release | Every Friday, compiles merged PRs into a categorized changelog and opens a PR updating CHANGELOG.md |
| Stale PR Cleanup | CI/CD & Release | Weekly scan for PRs not updated in over a week — checks for merge conflicts and posts a friendly nudge |
| Dependency Vulnerability Scanner | Security | Daily scan for known CVEs in your dependencies, prioritized by severity, with fix PRs |
| Secret Scanner | Security | Daily scan for leaked credentials, API keys, and tokens — replaces hardcoded secrets with environment variable references and opens fix PRs |
| Code Pattern Enforcer | Security | Weekly comparison of your repo against a golden reference repository, opening alignment PRs for deviations |
| OWASP Security Hardening | Security | Weekly scan for OWASP Top 10 vulnerabilities — injection flaws, XSS, missing auth checks, insecure defaults — with fix PRs |
| Cloudflare Security Audit | Security | Weekly review of Cloudflare audit logs to flag suspicious activity, configuration changes, and potential security issues |
| Weekly Status Digest | Project Management | Every Monday, compiles the past week's merged PRs into a concise status update and posts it to Notion |
| Sprint Progress Report | Project Management | A daily standup summary from Asana — pulls task status across projects and posts a progress update to Slack |
| Backlog Cleanup | Project Management | A weekly pass over your Linear backlog — closes stale and duplicate issues, flags untriaged ones, and fills in missing labels, priorities, and estimates |
To browse all templates, open the **Automations** page in the Devin app and click **Create automation** > **Template** (or go directly to `/automations/templates`).
# Devin PR bot comment settings
Source: https://docs.devin.ai/product-guides/bot-comment-settings
Control which bot comments Devin responds to on pull requests with the Responding to bots setting: no bots, all bots, or an allowlist.
## 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 **Responding to bots** setting 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** > **Devin**](https://app.devin.ai/settings/devin) > **Pull requests** > **Responding to bots**.
Only organization admins can modify this setting.
## Available modes
### No bots (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.
### All bots
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.
### Selected 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 **Selected 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 ("No bots"), 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 **"Selected only"** and add `devin-ai-integration[bot]` to the allowlist.
* Set the mode to **"All bots"**.
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 **"Require @Devin to respond"** 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 **"Selected 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 **"No bots"** to stop them immediately.
* A commenter is treated as a bot when its GitHub user type is `Bot` or its username ends in `[bot]`, so GitHub App bots such as `github-actions[bot]` are recognized even when the webhook payload omits the user type.
# Creating Playbooks
Source: https://docs.devin.ai/product-guides/creating-playbooks
Create Devin playbooks in the web app to build a library of reusable, detailed prompts that your organization can share and run across sessions.
## 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: open [Settings → Playbooks](https://app.devin.ai/settings/playbooks) and click **Create playbook** on the **Organization** tab (or on the **Enterprise** tab, for enterprise-wide playbooks).
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, underscores, 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.devin.ai/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.
* **Native deployments toggle**: the **Enable native deployments** setting under [**Settings > Devin**](https://app.devin.ai/settings/devin) controls whether Devin can deploy to the public internet with its built-in deployment tools. Turning it off (secure mode) removes the deploy tool from sessions.
* **Security profiles and network policies**: sessions governed by an enforced [security profile](/product-guides/security-profiles) run in secure mode, and any session with a network policy (from a profile or an [automation](/product-guides/automations#network-policy)) cannot deploy, because uploading the site and calling Fly.io require unrestricted network access.
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.devin.ai/product-guides/invite-team
Invite teammates to your Devin organization, assign roles, and manage members from the Membership settings page on 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 > Membership** in the sidebar, or go to [app.devin.ai/settings/members](https://app.devin.ai/settings/members).
2. Click **Add member** to open the **Invite members** dialog.
3. Select a role for the invited users.
4. Enter the email addresses of the people you want to invite.
5. Click **Add**.
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 **Membership** settings page, users who can manage membership can:
* View all current members and their roles
* Change a member's role
* Remove members from the organization
Admins can invite new members, change roles, and remove members by default. On Enterprise plans, users with a [custom role](/enterprise/security-access/custom-roles) that grants the **Manage Membership** organization permission or the **Manage Account Membership** enterprise permission can manage membership too.
# Knowledge
Source: https://docs.devin.ai/product-guides/knowledge
Onboard Devin with Knowledge: share tips, docs, and instructions Devin recalls across sessions, scoped to repos, your organization, or your enterprise.
Knowledge is deprecated and will be removed in a future update. Existing Knowledge is being migrated to [Skills in Plugins](/product-guides/plugins) automatically — the migration is rolling out gradually and requires no action on your part. Use Skills for new instructions and context you want to share with Devin.
## 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
Knowledge can be scoped to a single organization or to your entire enterprise. What the Knowledge page shows depends on which organization you're in:
* **Non-primary organizations** — The Knowledge page has two tabs:
* **Organization** (default) — 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.
* **Primary organization** — The Knowledge page shows a single enterprise knowledge view with no tabs. Enterprise knowledge applies across all organizations in your enterprise, and enterprise admins create and manage it here.
Non-primary organizations do not have an Enterprise tab. If your organization belongs to an enterprise, use the **Looking for enterprise knowledge?** link on the Knowledge page to open enterprise knowledge in your enterprise's primary organization.
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.devin.ai/product-guides/oidc
Give Devin short-lived, keyless access to AWS, GCP, Vault, JFrog, Databricks, and your own services with OpenID Connect workload identity federation.
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`).
For a worked example of this pattern with a third-party platform, see [Connect Devin to Databricks](/integrations/databricks), which federates a Databricks service principal to Devin's issuer and wraps the Databricks CLI so each call carries a fresh token.
## 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.devin.ai/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.
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 --local ./plugins/my-plugin # linked, this machine only: edits apply on the next session
devin plugins list
```
You can also upload a plugin folder or `.zip` to your personal scope from [Customize → Plugins](/product-guides/plugins#from-a-repository-a-zip-or-the-editor) and try it in a cloud session.
## 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 Customize
An admin installs the marketplace repo from [**Customize → Plugins → Add plugin → From repository**](https://app.devin.ai/customize) at the organization or enterprise scope — see the [Plugins guide](/product-guides/plugins). That adds one entry to the scope's managed manifest:
```json theme={null}
{
"requiredPlugins": ["acme/plugins"]
}
```
Requiring the marketplace repo installs its root meta-plugin, which pulls in the whole baseline recursively. Customize then indexes the scope and lists every plugin it pulled in, with their skills, MCPs, hooks, and rules.
Everyone in scope now gets the baseline automatically — in cloud sessions, the Devin CLI, and Devin Desktop. Pick the scope deliberately:
* The **enterprise** manifest reaches every organization in the enterprise.
* An **organization** manifest reaches that organization's cloud sessions, and the CLI/Desktop of members whose primary organization it is.
If the baseline ships MCP servers that need credentials, finish setup on the [MCPs tab](/product-guides/plugins#mcps) after indexing. For OAuth servers with **Organization** access, connect a service account for members to share; with **Personal** access, each member connects their own account. If the baseline's content is missing, follow [Resolve indexing issues](/product-guides/plugins#resolve-indexing-issues).
## 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** are currently **best effort and fail open** — a hook that fails to load or run doesn't stop the session — so don't rely on them for crucial guardrails yet. See the [CLI hooks reference](/cli/extensibility/hooks/overview) for local configuration.
* **Governance fails open**: if a managed manifest can't be fetched at session start, that level's plugins aren't installed and its forbids aren't enforced for that session.
* Plugin content from a **private repo** appears in Customize only for organizations whose Git integration can reach the repo; elsewhere it's withheld until the repo is granted on Settings → Repositories.
## Learn more
* [Plugins guide](/product-guides/plugins) — the web app side: Customize, scopes, indexing, MCPs
* [CLI plugins reference](/cli/extensibility/plugins/overview) — file format, authoring, per-user installs
* [Skills](/product-guides/skills) — the `SKILL.md` procedures plugins bundle
# Devin plugins and the Customize page
Source: https://docs.devin.ai/product-guides/plugins
Install Devin plugins from Customize, resolve indexing issues, connect MCP servers, and manage personal, organization, and enterprise scopes.
## 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.
Plugins are the shared customization layer across **cloud Devin sessions**, the [**Devin CLI**](/cli/index), and **Devin Desktop**: install a plugin once and its skills become available as `/:` commands wherever you use Devin. Plugins can be installed at three levels:
| Scope | Who installs | Who gets it |
| ---------------- | ----------------- | --------------------------------------------------------------------------------------------------------- |
| **Personal** | You | Your own sessions — cloud, CLI, and Desktop, on every device you're signed in to |
| **Organization** | Org admins | That organization's cloud sessions, plus the CLI and Desktop for members whose primary organization it is |
| **Enterprise** | Enterprise admins | Everyone in every organization of the enterprise |
This page covers the web app side: the Customize page, installing at each scope, indexing, MCPs, and the managed manifests behind it all.
## The Customize page
Plugins live on the [**Customize**](https://app.devin.ai/customize) page, reached from the **Customize** item in the sidebar (it replaced the older Settings → Plugins, Settings → Marketplace, and Settings → Connections → MCP servers pages; old links redirect). It has five tabs:
* **Plugins** — everything installed, grouped by scope, plus **Browse marketplace** to install more.
* **Skills** — the skills Devin loads on demand, from installed plugins and your repositories.
* **MCPs** — the MCP servers that give Devin tools beyond its built-in ones. See [MCPs](#mcps) below.
* **Hooks** — commands that run automatically at points in a session. See [Hooks](#hooks) below.
* **Rules** — standing guidance for sessions in scope. See [Rules](#rules) below.
Use the scope tabs to choose **Personal**, **Organization**, or **Enterprise**, depending on your access. Each scope shows its *effective* content: what actually applies after governance. To change repository-level content (skills, rules, and plugins declared in a repo's `.devin/config.json`), edit the repository's files.
Who can change what:
* **Personal** — anyone, for their own scope.
* **Organization** — members with organization settings access.
* **Enterprise** — members with enterprise settings access.
Click any plugin to open its details sheet: its skills, MCPs, hooks, rules, and subagents; the tracked ref or pinned SHA and path; which scopes it's installed in and what requires it; its permissions; and — where you have rights — actions to connect its MCPs, change what it requires, uninstall it, or (for an uploaded plugin) delete it.
## Installing plugins
### From the marketplace
Click **Browse marketplace** on the Plugins tab. The marketplace is one list combining the **Devin official marketplace** ([CognitionAI/devin-marketplace](https://github.com/CognitionAI/devin-marketplace), mostly one plugin per integration such as Linear, Notion, Datadog, or Snowflake) with any plugins your organization or enterprise has added. Each card offers an install menu with every scope you can write to, and shows where the plugin is already installed ("Installed for me", "Installed at organization", …).
Before the first install of a plugin, Devin shows a **security notice**: installing lets Devin run the plugin's rules, hooks, and skills (and, for a plugin with MCP servers, reach external data through them), so only proceed if you trust the plugin and have verified its source. Official marketplace plugins are marked as such.
After installing, a toast confirms the scope and — if the plugin ships an MCP server that needs credentials or authorization — offers **Connect MCP** to finish setup right away.
Enterprise admins can hide the official marketplace for every org (**Show official marketplace plugins** switch), and can control which marketplace MCP servers organizations see under **Marketplace availability**.
### From a repository, a `.zip`, or the editor
The **Add plugin** menu on the Plugins tab supports three more sources, each installable at any scope you can write to:
| Where it lives | How to add it |
| -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Git repo** (public or private) | **From repository** — enter `owner/repo` or a git URL, plus a subdirectory when the plugin lives in a subfolder. Any private repo Devin can reach through your Git integration works. |
| **Not in a repo** | **Upload .zip** — an uploaded plugin bundle is stored with the scope and installed for everyone in it. |
| **Doesn't exist yet** | **Create plugin** — a file editor with **Preview**/**Source** tabs and **Version history** (every save is a restorable version). |
Uploaded and created plugins can be edited later from their details sheet. Deleting one removes its files permanently — they have no other copy. Don't put secrets in plugin files; use [secret references](#plugin-environment-variables) instead.
### From the CLI
`devin plugins install ` adds the plugin to your **personal** scope by default, so it follows you to cloud sessions and your other devices. Pass `--local` to install on the current machine only. See [the CLI commands](/cli/extensibility/plugins/overview#installing-a-plugin).
### Letting Devin do it
In a cloud session you can ask Devin to save something as a personal skill, rule, hook, or MCP server, or to install a plugin for you. Devin proposes the change as a card you approve or deny; approved changes go to your personal scope and apply to future sessions.
## How plugins reach sessions (cloud ↔ local sync)
Every scope is backed by a **managed manifest** stored in Devin Cloud (see [The manifest](#the-manifest)). Installing anywhere writes that manifest, and every surface reads it:
* **Cloud sessions** fetch the enterprise, organization, and personal manifests at start and install the resulting plugins on the session machine, alongside plugins declared by the repositories they clone.
* The **Devin CLI** and **Devin Desktop** fetch the same manifests when you're signed in, so a plugin you install on the web appears on your laptop, and `devin plugins install` on your laptop appears in your next cloud session. Plugins from private repos are fetched with your local git credentials, so you need access to the repo yourself. An enterprise can turn off CLI plugins entirely (**Devin CLI plugins** in enterprise settings).
* **Solo users** (no organization) have only a personal scope.
Running sessions keep what they loaded at start; changes apply to the **next** session.
Plugin installation and MCP authentication are separate steps. Connect cloud MCPs from [Customize → MCPs](#mcps); for a plugin's OAuth server running in the CLI, use [`devin mcp login`](/cli/extensibility/mcp/configuration#troubleshooting). Syncing a plugin does not mean every device shares the same credentials.
## Indexing
Devin keeps an **index** of every scope's plugins: it clones each plugin source, reads its manifest and contents, resolves dependencies, and applies governance. The Customize page shows the index result — the plugins, their skills, MCPs, hooks, and rules, and anything blocked by policy — and the status line reports when each scope was last indexed.
* **What triggers it** — installing, removing, or editing a plugin queues a reindex automatically. Use **Plugin settings → Reindex plugins** to refresh the index after pushing changes to a plugin's source repository.
* **While it runs** — a run can be scheduled, queued, starting, or indexing. Frequent reindexes are spaced out, and uploaded-bundle saves can take a short time to queue. Plugin MCPs can be connected once their configuration has been indexed.
* **Results** — open **Plugin settings** (the gear menu) to see the last indexed time and any issues. A failed refresh can leave the last successful result visible; the presence of a plugin in the list doesn't prove the latest refresh succeeded.
* **Repository access** — plugin content indexed from a repository is only shown in an organization that has access to that repository through its Git integration. If it doesn't, the scope's content is **withheld** with a *Plugin repos unauthorized* notice; grant the repository on **Settings → Repositories**. Governance from a withheld scope (its forbids) still applies.
* **Network policy** — indexing runs on a machine that inherits your organization's [session network policy](/product-guides/security-profiles), so plugin sources must be reachable under it.
Sessions themselves don't wait for the index: they fetch and install plugins directly at start.
### Resolve indexing issues
1. Open [Customize → Plugins](https://app.devin.ai/customize) in the organization where you need the plugin. Select its **Personal**, **Organization**, or **Enterprise** scope, then open **Plugin settings** to read the issue and the plugin or scope it names.
2. If a run is scheduled, queued, starting, or indexing, let it finish. If the plugin has never been indexed, or its source changed since the last index, choose **Reindex plugins**.
3. For a failed run or missing content, use the matching fix below. Save or commit the correction, then choose **Reindex plugins** and check the result again. Changes to a shared manifest or repository permissions may require an admin.
| Message or symptom | What to do |
| -------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Plugin repos unauthorized** | Ask an admin to grant the affected organization access to every repository named in the issue from [Settings → Repositories](https://app.devin.ai/settings/repositories). An enterprise plugin may need repository access granted to several organizations. Adding the plugin to a manifest does not grant repository access. |
| **Plugin source could not be cloned** or **Repository unavailable** | Check the repository URL, branch or tag, and pinned commit. Confirm the organization has permission to read the repository, even if it already appears in the repository list. Check the [network policy](/product-guides/security-profiles) if the Git host cannot be reached. Reindex after fixing access or the source reference. |
| **No plugin manifest found** | Check that the source points to the plugin directory. A plugin in a subfolder needs that subdirectory in its source reference. Include a [supported manifest](/cli/extensibility/plugins/overview#compatible-formats) at the expected location. |
| **Plugin manifest malformed**, **Skill malformed**, **MCP config malformed**, or another malformed asset | Open the issue's **Learn more** link for the relevant format. Fix the named file in the source repository or uploaded plugin editor. Check [manifest fields](/cli/extensibility/plugins/overview#manifest), [skill frontmatter](/cli/extensibility/skills/creating-skills#frontmatter-reference), [MCP configuration](/cli/extensibility/plugins/overview#mcp-servers), and paths relative to the plugin root. |
| **Conflicting version pins** | Inspect the manifests requiring the plugin. Align their `sha` values, or let the higher-authority scope supply the pin. See [conflicts and dependencies](/cli/extensibility/plugins/overview#conflicts-and-dependencies). Reindexing alone cannot resolve contradictory pins. |
| **Plugin source not pinned** | This is an advisory, not an indexing failure. The plugin follows a branch or tag. [Pin it to a commit](#pinning-a-plugin) if you need a fixed version. |
| **Could not load plugin contents** or **Indexed content unavailable** | Choose **Reindex plugins** to rebuild the indexed content. If the page instead says **Couldn't load your configuration**, use **Try again** to retry loading it. |
| **Installed but blocked** | Read which scope forbids the plugin and ask the policy owner to review it. A lower scope cannot override that policy; see [Governance](#governance). |
After indexing succeeds, open the plugin's details and confirm the expected skills, rules, hooks, or MCPs appear. If an MCP still needs authorization, finish [connecting it](#mcps). To use changed plugin content, start a new session. For a stale CLI install, use [`devin plugins update`](/cli/extensibility/plugins/overview#managing-plugins); a Customize reindex refreshes the web listing. An install made with `--local` stays on that device.
If indexing keeps failing, or a run stays queued or indexing without progressing, contact support. Include the organization and scope, plugin source and ref, last indexed time, exact error, and a screenshot of the issue.
## MCPs
MCP servers are managed on the **MCPs** tab of Customize, for the same three scopes. The tab has two kinds of entries:
* **From plugins** — MCP servers declared by an installed plugin. The plugin owns the connection settings (URL, transport, required credentials), shown read-only; you can still enable, disable, connect, or uninstall it. Most official marketplace plugins are a single MCP server plus, optionally, skills.
* **Standalone** — MCP servers installed on their own: custom servers (**Add custom MCP**) and servers installed from the legacy **MCP marketplace**, which is still reachable from the tab.
**Connecting.** A plugin MCP that needs an API key opens a Connect sheet with its secrets ready to fill in; one that uses OAuth opens the provider's authorization flow; one that needs neither is ready as soon as the plugin is installed. Connect from the install toast, from the plugin's details sheet, or from the MCP's row.
**Shared vs. per-member connections.** For an OAuth MCP installed at the organization or enterprise scope, the server's **Access** setting decides how the connection is shared: **Organization** access is one shared connection for everyone in the scope — use a **service account**, not a personal login — while **Personal** access has each member authorize their own account. For servers without per-member access, install the plugin (or the MCP) at the personal scope when each member needs their own credentials. If members are connecting the same marketplace MCP one at a time, an admin can install it once for the organization and plugins that declare it will use that connection.
**Enterprise MCPs.** Enterprise admins configure a server once — including a private-CA certificate bundle for MCP traffic routed through the customer network — and choose which organizations get it. An organization's own installation of the same server overrides the enterprise one.
For transport types, custom-server fields, and per-server setup notes, see [MCP servers](/work-with-devin/mcp).
## Hooks
Hooks are commands Devin runs at points in a session, such as before or after a tool call. **New hook** on the Hooks tab edits the scope's `hooks.json`; changes apply to new sessions. Pass credentials through [plugin environment variables](#plugin-environment-variables), not the hook itself. Hooks are best effort: one that fails doesn't stop the session.
For the file format, see the [hooks reference](/cli/extensibility/hooks/overview).
## Rules
Rules are standing guidance for sessions in scope, like team conventions. **New rule** on the Rules tab adds a Markdown file to the scope's `rules/`. Keep always-on rules short, and prefer [skills](/product-guides/skills) for anything that only matters sometimes.
For the file format and `trigger` options, see the [rules reference](/cli/extensibility/rules).
## The manifest
Behind each scope is a managed manifest — a JSON document with three lists. The Customize UI edits it for you; **Plugin settings (gear) → Edit manifest** on the Plugins tab exposes it directly:
```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). Installing from the UI adds an entry here.
* **`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.
### Uploaded plugins
An uploaded plugin is referenced by its bundle ID, and its files belong to the scope it was uploaded to. A reference without `bundleScope` resolves against the files of the manifest that lists it:
```json theme={null}
{ "requiredPlugins": [{ "source": "account-upload", "bundleId": "bugzilla" }] }
```
To install an **enterprise** upload into an organization (or a personal scope), list it in that scope's `requiredPlugins` with `"bundleScope": "account"`, so it resolves against the enterprise's files:
```json theme={null}
{ "requiredPlugins": [{ "source": "account-upload", "bundleId": "bugzilla", "bundleScope": "account" }] }
```
Where an enterprise upload is listed decides who gets it:
* **Enterprise `requiredPlugins`** — installed in every organization.
* **Enterprise `optionalPlugins`** — shown under **Suggested** in each organization, where an admin can install it. From the enterprise plugin's details sheet, **Required organizations** installs it into the organizations you select.
Organization and personal uploads can't be offered to other scopes.
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).
## Governance
The three lists are the policy language at every level — enterprise, organization, repository (`.devin/config.json`), and personal — and higher authority wins: an enterprise can require a plugin no organization, repo, or user can remove, and forbid one no lower level can bring back. A plugin blocked by policy shows under **Installed but blocked** on the Plugins tab, and its skills are skipped at session start with a warning naming the forbidder.
To lock an enterprise down to an approved set, forbid `"*"` and list the approved plugins (and their dependencies) in `requiredPlugins`/`optionalPlugins`; see [Set up your plugin ecosystem](/product-guides/plugin-ecosystem#6-govern) for a worked example and [inheritance and levels](/cli/extensibility/plugins/overview#inheritance-and-levels) for the complete rules.
### Scope and inheritance
* **Standalone accounts** have an **account** manifest (labelled *Organization* in Customize) plus each member's personal manifest.
* **Enterprises** have an **enterprise** manifest inherited by every child organization, a per-**organization** manifest layered below it, and personal manifests below that.
## How updates roll out
* **Manifest changes** (installs, removals, manifest edits) apply to the **next session**, on every surface.
* **Plugin content changes** — merging to the branch a plugin tracks reaches new sessions automatically (cloud sessions fetch at start; the CLI refreshes on `devin plugins update`). Customize shows the new content after the next index run — click **Reindex plugins** to pull it immediately.
* Running sessions keep what they loaded at start — updates never change a session mid-flight.
### Pinning a plugin
A plugin written as `"owner/repo"` (or with a `ref`) follows a branch or tag, so the same manifest can resolve to different content over time. Customize flags such entries as **Plugin source not pinned**. To lock a plugin to exact content, use the object form with a `sha`:
```json theme={null}
{
"requiredPlugins": [
{ "source": "github", "repo": "acme/review-tools", "sha": "3f2a9c1d8e4b7a6f5c0d1e2f3a4b5c6d7e8f9a0b" }
]
}
```
A pinned plugin never changes until you edit the SHA. `ref` (a branch or tag) and `sha` are mutually exclusive — an entry can't set both. The same fields work with the `url` and `git-subdir` [source forms](/cli/extensibility/plugins/overview#dependencies). Uploaded plugins are always pinned to the content you uploaded. If two scopes pin the same plugin to different SHAs, the index reports a pin conflict.
## Plugin environment variables
Add `env` to a `requiredPlugins` or `optionalPlugins` entry to configure [command hooks](#hooks) in cloud sessions. Reference [Devin Secrets](/product-guides/secrets) for credentials; other values can be literal strings.
```json theme={null}
{
"requiredPlugins": [
{
"source": "github",
"repo": "acme/review-tools",
"env": {
"API_KEY": "secret:org:REVIEW_API_KEY",
"REVIEW_MODE": "strict"
}
}
]
}
```
Start a new cloud session to apply changes. Dependencies need their own manifest entry and `env`.
### Supported references
```text theme={null}
secret:org:NAME
secret:enterprise:NAME
secret:personal:NAME
secret:session:NAME
secret:repo:owner/repo:NAME
```
The secret must be available to the session. For an existing key-value secret, append `/ENTRY`, for example `secret:org:AWS_CREDS/ACCESS_KEY_ID`.
Plugin MCP configs reference secrets as `${NAME}`; members supply the values from the server's details sheet, and any literal value written into the config is stripped.
## Learn more
* [Plugins reference](/cli/extensibility/plugins/overview) — plugin file format, manifest, governance semantics, CLI commands
* [Set up your plugin ecosystem](/product-guides/plugin-ecosystem) — build and govern your own plugin repo
* [Quickstart: team marketplace](/cli/extensibility/plugins/quickstart) — from zero to a shared plugin repo
* [Skills](/product-guides/skills) — the `SKILL.md` procedures that plugins bundle
* [MCP servers](/work-with-devin/mcp) — transports, custom servers, per-server setup
# Scheduled Sessions
Source: https://docs.devin.ai/product-guides/scheduled-sessions
Manage legacy Devin scheduled sessions and create new recurring or one-time scheduled work as automations with a Schedule trigger.
**Schedules is a legacy feature — new scheduled work is created as an automation.** [Automations](/product-guides/automations) support schedule triggers along with event-driven triggers (Slack, GitHub, Linear, webhooks), conditions, invocation limits, and more. To run Devin on a schedule, open **Automations** in the sidebar, click **Create automation**, and add a **Schedule** trigger. Existing scheduled sessions will continue to work, and Devin can help migrate them to automations — just ask.
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
New scheduled sessions are created as [automations](/product-guides/automations) with a **Schedule** trigger. There are two ways to start:
### From the automations page
1. Navigate to **Automations** in the sidebar
2. Click **Create automation**
3. In the trigger dropdown, expand **Schedule** and choose **Every hour**, **Every day**, **Every week**, **Run once**, or **Custom schedule**
4. Write the prompt Devin should follow on each run, then click **Save**
### From an existing session
1. Open the menu on a session in the sidebar
2. Select **Schedule Devin**
3. You'll be taken to the automation editor with that session's prompt pre-filled
See [Schedule triggers](/product-guides/automations#schedule-triggers) for the full set of scheduling options. The rest of this page describes the options available on existing legacy schedules.
## Configuring a Schedule
When editing an existing 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
Existing schedules don't have a sidebar entry. Open [app.devin.ai/settings/schedules](https://app.devin.ai/settings/schedules) to see all your legacy 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.devin.ai/product-guides/secrets
Store organization, personal, repo, and session secrets — API keys, site cookies, and TOTP codes — so Devin can sign in to tools.
## 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.
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. For an example that stores an API key as several raw secrets, see [Upload iOS builds to TestFlight](/onboard-devin/environment/testflight#add-secrets-to-devin).
**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, add them in that repository's blueprint editor:
1. Go to **Settings > Environment > Blueprints** and select the repository. The repository must already be part of your [environment](/onboard-devin/environment).
2. Open the **Secrets** tab.
3. Click **Create secret** to add a single secret, or **Import secrets** to add several at once.
From the same tab you can search, reveal, edit, and delete the repository's secrets. Managing repository secrets requires the `ManageOrgSecrets` permission; other members see the list read-only.
Repository secrets are only available for that repository: to its blueprint steps during snapshot builds, and to Devin when it works in that repository during sessions. They are stored encrypted and are never written into your blueprint or snapshot. See [Secrets in the blueprint reference](/onboard-devin/environment/blueprint-reference#secrets) for how they are injected.
Don't put secret values in blueprint YAML, setup commands, or `.env` files committed to the repository. Store them in the repository's **Secrets** tab and reference them by name (for example, `$MY_SECRET`) instead.
## 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
Devin provides each secret to the specific commands and tools that need it. In the browser, Devin types the value directly. For shell commands, it binds secrets as environment variables whenever needed. This applies to organization-wide, repo-specific, and session-specific secrets.
Secrets are not exported into every shell, so scripts should not assume a variable like `$API_KEY` is already set. If a script depends on a secret, tell Devin which environment variable it reads and Devin will bind it to the relevant commands.
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 begins with a digit, Devin adds an underscore to the beginning of the name. For example, the secret 123MYVAR would become the ENV variable \_123MYVAR (names that already start with a letter or underscore are unchanged)
* 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.
## 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.
## Adding a New TOTP
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.
# Security Profiles
Source: https://docs.devin.ai/product-guides/security-profiles
Define reusable Devin security profiles that restrict network, MCP, git, and GitHub CLI access, and bind them to orgs, automations, and sessions.
Security profiles let you define reusable bundles of security restrictions — network access, MCP access, git access, and GitHub CLI credentials — and apply them to Devin sessions across your organization. Instead of configuring restrictions session by session, admins create named profiles once and attach them at the level that makes sense: as an organization-wide default, on a specific automation, or on an individual session. Enterprises can additionally share profiles across every organization and enforce them as a hard floor that no one below can loosen.
## Restrictions in a profile
A profile is a named set of restrictions. Each restriction is optional — a profile only constrains the settings it configures.
### Network policy
A network policy is an allowlist of destinations the session's machine is permitted to reach. All other outbound connections are blocked. Allowlist entries can be:
* **Hostnames**, with `*` wildcards (e.g. `*.github.com`, `registry.npmjs.org`). A `*` matches any sequence of characters, including dots.
* **IPv4 / IPv6 CIDR ranges** (e.g. `10.0.0.0/8`).
The restriction applies to all network access from the session — shell commands, browsing, package installs, and scripts alike. Devin is aware when it's running under a restricted network policy: it can see the current allowlist and, when it's blocked by a missing destination, it will ask for access. Approving the request adds the destination for that session (subject to any mandatory envelope — see [enforcement](#mandatory-vs-recommended-enforcement)).
Destinations required for Devin to function (such as the git proxy used to reach your connected repositories) are allowed automatically.
### MCP access
By default, sessions can use any [MCP server](/work-with-devin/mcp) installed in your organization. A profile can restrict this with **an allowlist of MCP servers** — sessions governed by the profile can only use the listed servers.
MCP access is managed independently of the network policy: you do **not** need to add an MCP server's address to the network allowlist. Servers allowed by the profile are reachable automatically, and servers excluded by the profile stay unusable regardless of the network policy.
### Devin MCP access
Sessions also have access to Devin's own management tools via the built-in Devin MCP — creating and messaging child sessions, editing knowledge and playbooks, managing schedules, and so on. A profile can restrict this surface with **Devin MCP read-only**: sessions governed by the profile can still read Devin resources (list sessions, look up knowledge, inspect playbooks) but cannot perform write operations like creating sessions or editing knowledge.
### Git access level
Controls what the session can do with your connected repositories:
| Level | What Devin can do |
| ------------- | --------------------------------------------------------------- |
| **Read-only** | Clone and fetch repositories, but not push branches or open PRs |
| **Full** | Clone, fetch, push, and open PRs as usual |
### GitHub CLI token
Beyond the base git operations covered by the git access level, Devin's machine can carry a GitHub CLI (`gh`) token that lets Devin use GitHub features directly through the GitHub API. A profile can **remove the GitHub CLI token** from the machine: sessions governed by the profile keep working with your repositories through Devin's git integration, but cannot make direct GitHub API calls.
A profile may only keep the token if it also grants **Full** git access and, when it sets a network policy, allows `api.github.com`. Both conditions are enforced when you save the profile.
## Where profiles live
Profiles exist at two scopes:
* **Organization profiles** are created in **Settings → Customization → Security profiles** and are usable only within that organization.
* **Enterprise profiles** (enterprise accounts only) are created in **Enterprise settings → Devin → Security profiles** and are usable by every organization in the enterprise. Organizations can select an enterprise profile for their sessions, automations, or org default, but only enterprise admins can edit the profile itself.
Profile names must be unique within their scope. Each profile also carries an [enforcement level](#mandatory-vs-recommended-enforcement) that determines whether lower levels can override it.
## What you can bind a profile to
A profile takes effect by being *bound* to a resource. Bindings form a hierarchy, from broadest to most specific:
1. **Enterprise default** — applies to new sessions in every organization in the enterprise.
2. **Organization default** — applies to new sessions in that organization.
3. **Automations default** — applies to sessions started by [automations](/product-guides/automations) in that organization, overriding the organization default for those sessions. Set from the same security-profiles settings page.
4. **Automation** — applies to sessions started by that specific automation, overriding the automations default. Set from the automation's editor.
5. **Session** — chosen for an individual session when it's created (via the options menu in the session start box), or changed later from the session's settings.
At each level you can make one of three choices:
* **Inherit** (the default) — no opinion; the level above decides.
* **Pin a profile** — sessions at this level use the selected profile.
* **No profile** — explicitly opt out, so sessions at this level run unrestricted even if a level above sets a recommended default.
When a session starts, Devin walks the hierarchy from the top down: the most specific binding wins, unless a mandatory profile higher up locks things down (see below). Sessions spawned by other sessions (child sessions) are governed by the same chain as their parent, so restrictions can't be escaped by delegating work.
### When changes take effect
A session resolves its governing profile at the moments it boots: when it's first created, and each time it wakes from sleep or reboots. Edits to a profile's contents or to any binding (a default, automation pin, or session selection) do **not** automatically propagate to sessions that are already running — a running session keeps the restrictions it resolved at its last wake. Changes take effect for new sessions immediately, and for existing sessions the next time they resume.
## Mandatory vs. recommended enforcement
Every profile has an enforcement level:
### Recommended
A recommended profile is a default, not a mandate. Anyone (with the appropriate permission) at a lower level can pin a different profile or opt out entirely. Use recommended profiles to give teams a sensible starting posture while preserving flexibility.
### Mandatory
A mandatory profile is a floor that lower levels cannot escape:
* **Opting out has no effect.** A "no profile" selection below a mandatory profile is ignored.
* **Lower-level selections can only tighten, never loosen.** If a lower level pins another profile, the two are *intersected*:
* Network allowlists narrow to the destinations allowed by **both** profiles.
* MCP allowlists narrow to the servers allowed by both.
* Git access takes the **minimum** (read-only wins over full).
* Devin MCP access is read-only if **either** profile sets read-only.
* The GitHub CLI token is removed if **either** profile removes it.
* **Mid-session edits are clamped.** Network access granted during a session (e.g. by approving Devin's request for a new domain) is intersected with the mandatory profile's policy, so a session can never be granted access beyond what the mandatory profile allows.
For example, an enterprise can bind a mandatory profile with a network policy allowing `*.internal.example.com` as the enterprise default. Organizations can then layer their own profiles on top to further restrict specific teams or workflows — but no organization, automation, or session can widen access beyond the enterprise policy.
## Permissions and governance
Managing profiles is governed by a dedicated **Manage security profiles** permission, separate from general settings management. It exists at two levels, each granted independently:
| Permission level | What it allows | Granted by default to |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------ | --------------------- |
| Organization | Create, edit, and delete organization profiles; set the org and automations defaults; pin profiles to automations and sessions | Org admins |
| Enterprise | Create, edit, and delete enterprise profiles; set the enterprise default | Enterprise admins |
Both levels of the permission can be granted to [custom roles](/enterprise/security-access/custom-roles), so you can delegate security-policy management (for example, to a security team) without granting full admin rights.
Members without the permission can't enumerate, select, or change profiles — their sessions simply follow the resolved default — but anyone can see whether their session is governed by a profile and what network access it has.
## Setting up security profiles
1. **Create a profile.** Go to **Settings → Customization → Security profiles** (or **Enterprise settings → Devin → Security profiles** for an enterprise-wide profile), create a profile, and configure its security settings and enforcement level.
2. **Set a default.** Bind the profile as your organization default (or enterprise default) so new sessions pick it up automatically.
3. **Pin where needed.** Override the default on specific automations — for example, a stricter profile for an automation that touches sensitive systems — or on individual sessions at creation time.
4. **Tighten over time.** Start with a recommended profile to observe impact, then switch it to mandatory once your allowlists cover your teams' legitimate needs.
## Automations and profiles
Automations can carry their own network policy and MCP selection. These are **restriction-only layers** on top of the governing profile — sessions started by the automation only get network destinations and MCP servers allowed by **both** the automation and the profile, so an automation can never widen the profile's access.
The automation layer is resolved live at each session boot and wake, so editing an automation's network policy takes effect without recreating its sessions.
## Outposts and profiles
Sessions that run on [Devin Outposts](/cloud/outposts/overview) resolve their governing profile through the same binding chain as cloud sessions, and the restrictions Devin enforces from its cloud — the MCP allowlist, Devin MCP read-only, the git access level, and GitHub CLI token removal — apply to outpost sessions exactly as they do to cloud sessions.
The **network policy** is different. Devin enforces a session's network allowlist at the machine level on Devin-managed VMs, but an outpost worker runs on infrastructure you operate, so Devin does not install firewall rules on your machines. Instead, each queued session's effective network policy is published to your orchestrator in the [Outposts API](/cloud/outposts/reference) as `spec.network_policy` (whether the policy is enabled, plus the allowed hostnames and CIDRs). Enforcing it — for example with a per-session egress proxy, a Kubernetes `NetworkPolicy`, or VM firewall rules — is the outpost operator's responsibility. Devin still sees the allowlist and requests access to missing destinations as usual, but approving a request only updates the session's policy in Devin; it does not change your network by itself. `spec.network_policy` is captured when the session is queued for an outpost and refreshed when it is re-queued (for example after the session sleeps and wakes), so re-read it from the API rather than assuming it is static.
If you rely on a mandatory profile's network policy as a hard boundary, make sure your outpost infrastructure enforces `spec.network_policy` for every session it serves. Without that, sessions on outposts have whatever network access your machines have.
# Session Insights
Source: https://docs.devin.ai/product-guides/session-insights
Use Devin Session Insights to analyze completed sessions, review issues and knowledge usage, and get improved prompts for future sessions
## 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, open the session menu (the **⋯** button at the right end of the session's top bar) and select **Session insights**.
In enterprise organizations, the session's top bar also shows a session size chip next to the session title. Clicking it opens the same Session Insights modal.
### Step 3: Generate or View Analysis
In 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 classification (XS, S, M, L, XL) based on how much usage a session consumes, measured in ACUs. The number of user messages does not affect session size.
The thresholds for each size category are:
| Size | ACU threshold |
| ------ | ------------- |
| **XS** | ≤ 2 ACUs |
| **S** | ≤ 5 ACUs |
| **M** | ≤ 10 ACUs |
| **L** | ≤ 20 ACUs |
| **XL** | > 20 ACUs |
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). On quota-based plans, sessions are sized on their overage cost, converted to ACUs at \$2 per ACU.
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.
# Devin Skills
Source: https://docs.devin.ai/product-guides/skills
Teach Devin reusable procedures by committing SKILL.md files to your repos, so testing, deployment, and review steps run the same way every session.
## 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. A skill can also carry a [dynamic workflow](/work-with-devin/dynamic-workflows) script, so a multi-agent orchestration you ran once becomes reusable.
## 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`
* `.cognition/skills//SKILL.md`
* `.windsurf/skills//SKILL.md`
All six 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.devin.ai/product-guides/using-playbooks
Attach Devin playbooks to a session with a macro, refine them as Devin runs, and browse Organization, Enterprise, and System playbooks in Settings.
## How to use Playbooks
To use playbooks simply select one of the playbooks available to you: your organization's playbooks, your enterprise's playbooks, or Devin's System playbooks. 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.
### 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**:
## Browsing Playbooks
Browse and manage playbooks at [Settings > Playbooks](https://app.devin.ai/settings/playbooks). The page groups playbooks into tabs:
* **Organization**: playbooks shared within your current organization.
* **Enterprise**: playbooks shared across every organization in your enterprise. This tab appears at the enterprise level; from an organization, use the **Looking for enterprise playbooks?** link to open them.
* **System**: playbooks provided by Devin, available to everyone.
Each tab lists playbooks with their name, macro, creator, and last-updated date, and includes a search box. If you have permission to manage playbooks in that tab, click **Create playbook** to add a new one.
# 2024
Source: https://docs.devin.ai/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.devin.ai/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.devin.ai/release-notes/2026
Devin release notes for 2026: new features, improvements, and bug fixes across the product, organized by release date.
**SWE-2 Research Preview in the Agent Selector**
SWE-2, Cognition's next-generation software engineering model, is rolling out as a research preview in the agent selector under the "Research preview" section. Choose SWE-2 and a reasoning effort (Medium, High, or Max) when starting a session, or switch to it mid-session with the agent toggle next to the message input; in Slack, use `!swe2`. Enterprise admins enable SWE-2 (Preview) for their enterprise in Settings, and organization admins can then turn it on or off for their organization under Agent capabilities. As a research preview, behavior and availability may change.
**Attach a Folder to a Message**
You can now attach a whole folder to a Devin message by dropping it on the composer or choosing "Upload folder". The folder is compressed in your browser and attached as a single zip file.
**More Automatic Merge-Conflict Fixes**
Devin now fixes merge conflicts on its PRs automatically more often: within 12 hours of session activity (36 hours if the PR is approved), including conflicts that reappear after an earlier one was fixed.
**Shell Command Durations in the Worklog**
Finished shell commands in the session worklog now show how long they took, so slow commands are easy to spot.
**Full Links for PRs, Issues, and Commits**
Devin now links PRs, issues, and commits it mentions instead of writing bare numbers like #123.
**File Tree, Smart Diffs, and Open in Editor in the PR Tab**
The PR tab now has a file tree alongside the diff that highlights the current file as you scroll, a Smart diffs toggle in the diff settings to view a PR as a flat list of files, an "Open in editor" button, and a "File tree on left" option to move the changed-files tree to the left of the diffs.
**Checks Tab and Faster Diffs**
The PR tab has a new Checks tab showing CI status, with tabs ordered Changes, Description, Discussion, Commits, Checks, Bugs. Diffs highlight faster and scrolling large PRs is smoother, and the embedded editor now matches the diff viewer's fonts and colors.
**Devin Review in Spanish and Portuguese**
Devin Review's interface is now available in Spanish and Portuguese for users whose display language is set to Español or Português.
**Devin Review for Bitbucket Data Center**
Devin Review can be enabled for Bitbucket Data Center repositories, including automatic reviews when pull requests are opened or updated. Bitbucket Data Center projects and repos can be selected on the Devin Review home page, the merge bar shows merge, approval, and build status, and admins can configure a webhook (Settings › Integrations › Bitbucket) so Devin updates pull request status and comments in near real time.
**npx devin-review CLI Retired**
The standalone `npx devin-review` command-line tool and its unauthenticated review page have been removed. Use Devin Review on the PR tab or in the Devin Review home instead; existing installed copies of the CLI will no longer work.
**Azure DevOps Improvements**
Devin can now add and remove pull request labels (tags) on Azure DevOps and Azure DevOps Server. In Settings, Azure DevOps connections show the organization name, and organizations or Server collections with more than 100 projects now list repositories from every project.
**Rotate Bitbucket Data Center Tokens**
Admins can rotate a Bitbucket Data Center connection's HTTP access token from Settings → Bitbucket or the enterprise API without disconnecting; the new token must belong to the same Bitbucket user.
**Link Your Bitbucket Data Center Account**
Once an admin registers an OAuth application for a Bitbucket Data Center host, you can link your own Bitbucket account from Devin Review or Profile → Linked accounts. Review approvals and comments Devin posts on that host are then attributed to you rather than the shared connection.
**Microsoft 365 MCP Servers and Plugins**
Microsoft 365 Mail & Contacts, Calendar, To Do, OneDrive & SharePoint, Teams, and Directory (Entra ID) are now available in the MCP marketplace and as plugins that bundle each MCP server with a usage skill. Connect them with your own Microsoft Entra app registration, pick OAuth scopes from a list that explains what each permission is for, and Devin connects with read-only permissions by default when no scope is configured. The Files MCP can return files converted to PDF or JPG.
**Google Workspace MCPs Through Plugins**
Gmail, Google Drive, and Google Calendar MCPs installed through a plugin can now be connected with your own Google OAuth client ID and secret, including custom OAuth scope and resource. On plugin MCPs that need your own OAuth client, the client ID and secret fields now appear first.
**Personal MCP Servers Are Private**
MCP servers you add or install from the Personal tab in Customize are now private to you instead of being shared with your organization, and editing a personal MCP server more than once no longer fails.
**Devin Can Manage Org and Enterprise Plugins**
Org and enterprise admins can have Devin create, update, remove, and install plugins for their whole organization or enterprise, approving each change. Devin can also create, update, and remove skills, rules, MCP servers, and hooks in your uploaded personal plugins through a single tool, including plugins that use a root mcp.json.
**Required and Available-to-Install Plugins**
Org and enterprise admins can make uploaded plugins "Available to install" so members choose whether to add them, or "Required", from the plugin's card or details panel. Renaming a plugin updates its name across Customize, Marketplace, and the session plugins menu, plugin indexing errors on the Customize page now say what actually failed, and plugins can be up to 5x larger (20 MiB, 2,500 files).
**Simpler Create Automation Menu**
The Create automation menu is reordered, "Manual" is now "Create", and "Suggest automations" is now "Suggest for me".
**Reactivated SCIM Users Keep Their Groups**
SCIM users who are deactivated and later reactivated by the identity provider now keep their IdP group memberships, including group changes made while they were inactive.
**Knowledge Is Moving to Skills**
Knowledge is being migrated to [Skills](/product-guides/plugins). Your existing Knowledge notes are converted automatically into skills in a `knowledge` plugin for each scope (organization, enterprise, or personal), with their content unchanged and their folder structure preserved; Devin uses them in sessions the same way it used the notes. Once an organization is migrated, its Knowledge page shows the legacy notes read-only and points to Customize → Skills, where you can view and manage them. No action is needed; the migration is rolling out gradually.
**Filter Sessions by Origin**
The sidebar session filters now include Origin, so you can show or hide sessions by where they were created: Slack, Web, API, Jira, or Linear.
**Command Palette: Open Devin Review from a PR Link**
Paste a pull request link into the Cmd+K palette and press Enter to open that PR's Devin Review.
**Smoother Screen Recordings**
Ask Devin to record at a higher frame rate and its screen recordings capture at up to 60 fps, so animations and scrolling look smooth in demos while keeping Devin's test-case annotations. Default recordings are unchanged.
**Email Notifications for Enterprise and Security-Profile Organizations**
Devin can now send email notifications to members of the same organization for enterprise organizations and organizations with a security profile.
**Enterprise API: Audit-Logs Pagination**
The `total` field in the Enterprise API audit-logs list response is no longer populated (returns `null`). Use `has_next_page` / `end_cursor` to paginate.
**Azure DevOps Server Support**
Organizations can connect Azure DevOps Server 2020/2022 collections with a personal access token from the Azure DevOps settings page.
**"Require Session Access for PR Comments" Org Setting**
Org admins can require that PR comments only reach Devin sessions the commenter has access to, under Settings → Devin → Pull requests. Enterprise admins can enforce it for all organizations.
**Perforce: Workspace Follows Connection Changes**
When a Perforce depot path is removed from an organization's connection, running Devin sessions lose access to it on their next Perforce command; the session's workspace is narrowed automatically and the command is retried.
**@-Mentions and Session Links in Microsoft Teams**
Devin can now @-mention people in its Microsoft Teams replies so they get notified. Sessions linked to a Teams thread show a Teams indicator in the session header, and "connect your account" messages take you to your Connections settings.
**Plugin Management in Customize**
Plugin version history shows readable diffs and a file tree for every version. You can download a plugin you uploaded as a .zip, edit skills and rules from organization plugins directly on the Skills and Rules pages, and share a direct link to a plugin from the address bar.
**MCP Connection Status and Reconnect**
Each MCP server now shows how it is authenticated, with a Reconnect action to redo authentication without uninstalling. Public MCP servers that offer optional sign-in (such as Context7 or Clerk) are marked ready instead of asking you to sign in, and org-owned MCPs where each member connects their own account also appear under Organization so admins can manage them.
**Connect Enterprise MCPs with Your Own Account**
Developers can authenticate enterprise MCPs that use individual OAuth from All organizations → Customize → MCPs → Personal, then use that connection across the applicable organizations.
**New in the MCP Marketplace: ActiveCampaign**
ActiveCampaign lets Devin manage contacts, campaigns, automations, and deals in your account.
**Grafana (OAuth) Plugin Support**
Grafana (OAuth) connects to Grafana Cloud's hosted MCP server with no API key or Docker setup; the Docker-based integration remains available as Grafana (stdio).
**Live Voice Mode**
Voice calls with Devin now run on a live speech model. Starting a call drops you straight into the call controls (with a ringtone while connecting), holding Space to talk works right after muting, and Devin's spoken replies stay in order in the transcript. When a session is connected to Slack, the thread shows who is on the call and how long it lasted instead of Devin's internal voice notes.
**Sessions Wake as You Type**
A sleeping session starts waking up as soon as you begin typing in its composer, so Devin is usually ready to work the moment you press send.
**Copied Messages Keep Their Formatting**
Copying a Devin message now preserves formatting when pasted into email or documents, still pastes as Markdown into code editors, and keeps bullets and links when pasted back into the Devin composer. Transcript copies include each speaker's name.
**Configurable Send Shortcut**
Choose whether Enter or Cmd/Ctrl+Enter sends a message under Settings → Personal → Send shortcut. The preference applies across Devin's composers.
**Skipped Questions Are Shown as Skipped**
When Devin moves on from a question before you answer, the transcript (and the Slack thread, for Slack-connected sessions) now shows the question as skipped, with what was asked, instead of "User answered: (no answer)".
**Reboot VM from the Sidebar**
Sessions that lose their VM now show a "Reboot VM" action in the sessions sidebar instead of a generic blocked or finished state.
**Agent Mode Icons in the Sidebar**
You can show each session's agent mode as an icon in the detailed sidebar. Enable Agent mode under Properties → Property visibility; it is off by default.
**Redesigned Session Dialogs**
Session dialogs — including the confirmations for stopping a session or closing its PRs — have been restyled to match the rest of the app.
**Security Bugs Are Always Checked in Devin Review**
Devin Review now always checks for security bugs in every review; the "Security scan" toggle has been removed from Settings › Review. Whether security bugs are posted to GitHub remains toggleable.
**Slack User-Group Mention Triggers for Automations and Oncall**
Trigger automations and oncall responders when a Slack user group is mentioned. Select a group or enter its Slack ID manually, and optionally restrict matching to specific channels.
**Admins Can Opt into Allowing Automations on Public GitLab Repos**
GitLab connections now have an "Automation scope" setting. Org admins can choose "All connected repos" to let automations access public-visibility GitLab projects on that connection.
**Install a Personal Plugin from a Directory**
Devin can now install a plugin from a folder on its machine (for example an attachment you sent it, once unpacked), not only from a GitHub repository URL.
**Read-only Customize View**
Members who can view Customize but have no layer of their own to install into see a read-only view of what's configured. When no plugins are available to browse, the Browse view explains that admins can add plugins instead of showing a blank list.
**MCP Secrets Are Now Managed in the MCP Page**
Settings → Secrets shows a banner explaining that MCP server credentials moved to each server's page, with a button to the right surface and a docs link.
**Teams Improvements**
Devin sessions attached to Microsoft Teams format replies for Teams (tabular data is sent as file attachments), include images pasted earlier in a thread when Devin is mentioned, and respond faster to new conversations. Picking new or org from the / command menu now works in personal and group chats, and the first-session welcome card suggests tagging @Devin in Teams when your organization has Teams connected. When Devin isn't connected to your Teams organization or a team wasn't fully set up, the bot now explains how to fix it.
**Connection Page Titles**
Browser tab titles on Settings → Connections detail pages show the integration name (e.g. "Microsoft Teams") instead of "Settings".
**Blueprint Source in the v3 API**
The v3 blueprint API lets you choose whether a repository blueprint is managed from .devin/blueprint.yaml in git or from Devin's database (source: "git" | "database" on create/update) and reports the current mode in blueprint responses.
**Clearer Machine Startup in the Computer Tab**
The Computer tab now says the machine is being provisioned while a session's VM is starting, instead of showing a connection failure, and waits up to roughly five minutes for slow-starting machines.
**Sidebar Keyboard Navigation**
Arrow keys now move between every sidebar navigation row, including items in the More menu, and screen readers announce them as a single menu.
**Nested Sidebar Groups Stay Expanded**
Expanded nested session groups in the sidebar stay expanded after you refresh the page.
**Neutral Primary Buttons**
Primary buttons across the app now use a neutral style instead of blue.
**Teams Parity Improvements**
Emoji reactions on Devin messages in Teams (including channel threads) are now forwarded to the session. Devin sees the recent Teams conversation when you reply in a thread or chat that already has a session. PR links in Devin's messages include a Devin Review link for organizations with Devin Review enabled. When a conversation moves from Teams to the Devin webapp or Desktop, the Teams thread shows a notice linking to where it continued. Devin no longer posts a "went to sleep due to inactivity" message, and shared-channel threads note that Devin can only see messages that @mention it.
**PagerDuty Integration for Oncall and Automations**
Connect PagerDuty to Devin to trigger automations on incident events (triggered, acknowledged, resolved, and updated) and to let Devin act as an oncall responder that triages PagerDuty incidents and posts its investigation as incident notes.
**Jira Site Picker**
Connecting Jira with an Atlassian account that belongs to more than one Jira site no longer fails; after signing in, Devin shows the sites you can access and lets you pick the one to connect.
**Datadog MCP on the Stable Endpoint**
The Datadog MCP integration now uses Datadog's stable `/v1/mcp` endpoint. Existing installations can adopt it via "Update from marketplace" in MCP settings and keep their region; users of the OAuth-based Datadog server need to reconnect once after the update.
**21 New Zero-Config OAuth MCP Servers**
21 new one-click integrations in the MCP marketplace — including Dropbox, ClickHouse Cloud, Lucid, Typeform, Coda, GitBook, Railway, Retool, Smartsheet and Make — each connecting through OAuth with no API keys or setup steps.
**Unified Plugin Marketplace**
Browse marketplace now lives in the Customize page's tab bar and shows one list across your scopes: Install lets you pick which scope to install to, cards say where a plugin is already installed, and a "+" adds it to other scopes you manage. The official marketplace loads without separately granting your organization access to its public repository, and a short introduction appears the first time you visit Customize.
**Customize Editor Improvements**
Skill and rule rows open an editor with Preview, Edit, and Version history tabs; removing or uninstalling a plugin asks for confirmation first. Customize shows only the configuration layers you can edit, with plugins your organization or enterprise requires shown as read-only "Required by organization" / "Required by enterprise" sections. Skills from plugins not activated in a session appear greyed out in the `/` and `@` menus.
**Devin-Managed Personal Plugins**
Plugin install approval cards in the worklog now show the plugin's marketplace name, contents summary, and logo, distinguish approval from successful saves and installs, and offer a "View plugin" link to open the item in Customize. Devin can install a plugin from a bare GitHub repository URL and save personal skills, rules, MCP configurations, and hooks from files.
**Effective Membership in Member Lists**
Enterprise admins now see everyone who effectively belongs to an organization — including users granted access through IdP/SCIM group mappings — in the enterprise Members page and each organization's Members page. Group-derived access is labeled with the granting group.
**Safer Secret Defaults**
New secrets default to Personal for non-admins, and creating or importing organization secrets asks you to confirm that everyone in your organization can use them.
**Idempotent Session Creation**
The v1 Sessions API accepts an optional `idempotency_key`; repeating a key returns the original session, and if creation with that key is still in progress the API returns 409 so the caller can retry shortly. The legacy `idempotent` boolean is deprecated.
**Azure DevOps Citations**
Source citations in Devin Wiki for Azure DevOps repositories now open the correct file, linking to the exact commit the wiki was built from.
**Archiving Closes Child Sessions' PRs**
Archiving a session now also closes the open pull requests of the child sessions archived with it; they are listed in the archive prompt so you can choose which to close.
**Multi-PR Dropdown in the Sidebar**
Sidebar sessions with several pull requests in the same state now show a dropdown listing each PR, with the same details as the session header's PR popover.
**Open Changes and PR Files as Diffs**
In a session's Changes and PR tabs, file paths are clickable while Devin's machine is online: clicking opens the file's diff in the embedded editor, with a button to view the full file.
**Desktop Tab on Touch Devices**
The Desktop tab now works like a remote desktop on iPad and other touch devices (tap to click, drag, long-press for right-click, two-finger scroll). When Devin is asleep, the last screenshot fills the pane and hovering it offers a one-click "Wake up Devin" action.
**Continue in a New Session after a Machine Failure**
Hard-blocked machine-failure cards now offer "Continue in a new session" alongside "Try restart", with a note that machine-local files and running processes do not transfer.
**Composer Code Chips**
Typing `` `code` `` in the message composer reliably turns the text into a code chip, Undo turns the chip back into plain text, and a backtick typed inside a chip becomes part of the code.
**Cleaner Chat Rendering**
A question you or a teammate answered now shows as that person's normal chat message. In sessions where you are the only participant, Devin's avatar and name header are hidden (hover a message to see its time) and appear once someone else joins.
**Faster Tab Switching**
Switching between the Progress, Diff, and PR tabs inside a session is roughly twice as fast, the Progress tab keeps your selected step, and switching no longer slows down as more pull-request tabs are kept open.
**Queued Messages Survive Idle/Resume**
Messages queued in a session are no longer lost when the session goes idle and resumes.
**Simplify Devin Review PR Summaries**
Devin Review's top-of-page analysis is now a short, behavior-focused summary (one to two sentences plus up to five bullets) instead of a long implementation walkthrough.
**Improve Progressive Disclosure of Review Findings**
Review findings keep concise summaries while offering an optional "Learn more" section with a plain-language explanation, a concrete example, and a recommended fix; whole findings can be copied.
**Re-scan New Commits and Bulk Remediate via MCP**
Devin can re-run an existing code scan on just the new commits and fix several findings in one go, from a session or any Devin MCP client.
**Webapp Answers Mirrored to Slack**
Answers to Devin's questions given in the web app now appear in the linked Slack thread.
**Slack Controls in the Sidebar**
Link a session to Slack, or turn Slack sync on and off, from the session's "..." menu in the sidebar without opening the session.
**Sync to Teams from the Webapp**
Sessions connected to a Teams chat can turn syncing on and off from the composer, the sidebar, and the command palette, the same way Slack sync works.
**Teams Improvements**
`mute` now fully disconnects a session from the chat and `unmute` or mentioning @Devin reconnects it; a "Detach session" card appears when Devin goes to sleep in DMs and group chats; Devin shows an "Approve deployment" button when it asks to deploy; and the Teams settings page includes the keyword tutorial and thread-mode setting.
**Regex Matching in Text Fields**
Automation text fields can use case-sensitive regular expressions (Google RE2 syntax).
**Grayed-Out Templates**
Templates that need an MCP server or integration your organization hasn't set up stay visible but grayed out, with a hint explaining what to connect.
**Update Approvals Show a Diff**
Approving an automation update now shows exactly what changes: added, removed and modified triggers and actions, settings as old → new, and prompt edits as a line diff.
**Automations Page Refresh**
The Automations page opens on a "Mine" tab by default, empty tabs show the creation options in place, creating an automation or on-call responder opens in a side panel, and the preflight-check card and script editor have been redesigned.
**Marketplace Updates**
The Meticulous MCP server is out of beta, and Intercom now connects with an access token.
**Plugins**
Plugins bundle skills, rules, hooks, and MCP servers into a single installable package so you can customize how Devin works and share that setup across your team. Install plugins from the marketplace in Settings → Marketplace or from a repository, for your organization or your whole enterprise; plugin details show where a plugin comes from (pinned commit or tracked ref and folder) and which scopes have it installed, and skills from a newly installed plugin are available in the `/` and `@` menus right away. Every install shows a security notice describing what the plugin can do and asks you to confirm you trust its source. Org and enterprise admins can mark plugins as required or available, and organizations inherit enterprise-managed plugins automatically.
**Environment Build Attention**
Enterprise admins can see which organizations need attention on the Environment page — consecutive failed builds, no usable snapshot, and a "Needs attention" filter — plus a "Last build failed" filter for repositories in an organization's environment settings.
**Roles and Access**
Roles whose only remaining assignments are expired service users can be deleted. Members with an Ask-only role (such as "DeepWiki Only") can see their past Asks in the sidebar, and view-only roles' session lists are restored.
**Git Bash on Windows**
On Windows machines, Devin runs commands under Git Bash by default (PowerShell remains available on request, and is used when Git Bash is not installed).
**Blueprint Suggestions**
Devin validates proposed repository blueprints (YAML and schema) before suggesting them, and the setup guide lists the optional Clone step.
**Lightbox Keyboard Navigation and Mermaid Diagrams**
Use the arrow keys to move between images in the lightbox carousel, and Mermaid diagrams now join the carousel alongside images.
**Single Devin PR Comment**
Devin's PR intro comment and the "Original prompt" details block are now a single comment, with the prompt shown below the intro.
**Code Scan Multi-Select Findings**
Select several findings at once to assign them to a single Devin session (one branch/PR) or to bulk-update their status (reviewed or dismissed).
**Code Scan No-Op Runs When There Are No New Commits**
Scan-new-commits runs (including scheduled runs in Automations) now skip starting a session when the repository has no new commits since the last scan; the run is recorded as completed with no ACU usage, and the webapp shows a "No new commits" toast.
**AWS and Braintrust MCP Servers in the Marketplace**
The MCP marketplace now includes AWS and Braintrust servers.
**Google Workspace MCP Setup Guidance**
The Google Drive, Gmail, and Calendar MCP configure pages now warn that the Google Cloud project must be enrolled in the Developer Preview and explain the bring-your-own OAuth client setup.
**Security Profiles Can Allow Orgs' Custom MCP Installations**
Enterprise admins can now let an enterprise security profile permit organizations' own custom MCP server installations.
**Microsoft Teams Improvements**
Files shared via SharePoint render as file attachments, Devin shows a typing indicator while working, /new is supported in group chats, and outgoing attachments are sent as their own activity.
**Partial Snapshot Builds on Clone Failures**
A new enterprise setting lets snapshot builds finish as partial when a repository cannot be cloned, instead of failing the whole build.
**New Sidebar Grouping and Filters**
The session sidebar can now group sessions by pull request status or by repository, and session filters now include Devin mode.
**Cleanup Scan Type**
A new cleanup scan type finds dead code and cleanup opportunities in your repositories.
**/scan Composer Command**
You can now start a code scan directly from the composer with the /scan command.
**Scheduled Scans in Automations**
Automations now support a code scan agent type, so you can schedule recurring scans or re-scan new commits automatically.
**Redesigned Findings Tab**
The scan findings tab has been redesigned for easier triage.
**Richer Trigger Event Details**
Automation runs now show richer event details for GitLab, Jira, incident.io, and GitHub triggers.
**Clearer Reply Delivery**
Slack users who are not members of the session's organization are now warned when their replies cannot reach Devin.
**Multi-Select Tag Filters**
The session sidebar now supports multi-select metadata tag filters with per-tag counts, plus a machine-type filter.
**Split Editor Groups in the Session Workspace**
The session workspace editor now supports VS Code-style split editor groups.
**Code Scan History**
The scan detail page has a scan history sheet, and redesigned history rows show each run's profile and cost.
**Code Scan Validation Severities**
Code scan profiles can now configure which finding severities require validation, with a threshold meter in the profile editor.
**New MCP Marketplace Servers**
Gmail, Google Calendar, Gamma, and Supabase MCP servers are now available in the marketplace, and marketplace entries now show icons.
**Clearer MCP Install Approvals**
MCP install approval cards now show the server's identity, source, and resolved scope before you approve.
**Authentication**
We are upgrading our authentication platform and login page.
**New Org Permission: Manage Personal Automations**
Org admins can control who can manage personal automations independently from who can manage system user automations. Account-level automation permissions are also now more granular.
**Queued Message Improvements**
Queued messages are now delivered while Devin is in a long-running wait, and pressing Cmd/Ctrl+Enter while editing a queued message sends it immediately.
**Waiting Activity Status**
Sessions now show a dedicated "Waiting" activity status while Devin is intentionally sleeping in a wait.
**Undo for Folder Moves**
Moving sessions between folders now shows an undo toast, and Cmd/Ctrl+Z triggers the newest toast's Undo action.
**Accessibility Improvements**
Reduced-motion users now get static/text equivalents for animated elements, and high-contrast support has been improved.
**Redesigned GitHub Link Badges**
Devin's GitHub link badges (PRs, branches, commits) have a refreshed design.
**Smarter @mention Routing in Slack Threads**
@mentioning Devin in a thread now routes your reply to the session you're subscribed to.
**Default Working Org for Slack Channel Sessions**
New Slack channel sessions are routed using the mentioning user's default working organization.
**Finer Automation Schedule Controls**
Hourly schedules now have a minute selector, and run-once schedules use a date picker.
**Multiple Slack Channels in Automation Triggers**
Automation triggers can now select and edit multiple Slack channels.
**Improve Existing Automations with Devin**
A new "Improve with Devin" action lets Devin iterate on an existing automation for you.
**Linked Triggering Events**
An automation run's triggering event source now links to its origin (e.g. the Slack message or issue).
**Support Jira previous\_status Automation Triggers**
Jira status\_changed triggers can now filter on the previous status, and the new status is optional.
**Security Section**
Code scan pages moved from /code-scan to /security (old links redirect). Scan sessions are listed for the user who triggered them, and archiving a scan's root session cancels the scan.
**Scan Now**
A "Scan now" button in the Auto Scan configure dialog starts a scan immediately.
**Batch Remediation via v3 API**
New v3 API routes support batch remediation of findings at the org and enterprise level.
**Allow PRs to Be Opened by Session Participants Configuration**
A new org setting, "Allow PRs to be opened by session participants", lets sessions open PRs as a validated session collaborator.
**Streamlined MCP Marketplace Install and OAuth Connect**
Installing an MCP server from the marketplace is now a single streamlined flow: install cards stay visible through approval, and the OAuth screen opens directly from the card.
**Redesigned Session Page Header**
The session page header is more compact, with tags and session hierarchy built in.
**Redesigned Sessions Sidebar**
The sessions sidebar has been redesigned with customizable nav tabs, grouping, richer filtering, and a cleaner session list.
**Refreshed Chat Visual Design**
The chat interface has a refreshed visual design.
**Nested Sub-Devin Sessions**
Sub-Devin sessions are now shown as a nested tree in the sidebar.
**Hideable Sidebar**
The sidebar can be fully hidden and peeked on hover.
**Session Subscribers**
Follow and view others' sessions, with subscriber-based sidebar organization and filtering.
**Inline Session Rename Shortcut**
Press Cmd/Ctrl+Option+R on a session page to rename the session inline.
**Stop Devin Shortcut**
Press Cmd/Ctrl+Shift+Backspace to stop Devin while it is working.
**Default Org Picker in Slack DMs**
In Slack DMs with Devin, you can now set your own default organization with the !org picker.
**Bearer Secrets for Automation Webhooks**
Automation webhooks can now authenticate with an Authorization: Bearer secret.
**Duplicate Findings Fix**
Resolved a regression in Devin Review that led to findings being reported multiple times.
**Clearer Findings**
Improved clarity and conciseness of Devin Review findings.
**Change a Scan's Profile**
You can now change a code scan's security profile from the UI.
**Scan Effort Selection**
Choose a scan effort (normal/deep) on the ingest scan form, and set it via the v3 API.
**New v3 Scan API Endpoints**
The v3 API can now trigger an incremental (diff) scan immediately and accepts multiple repos on ingestion scan start.
**Finding Resolution Notes**
A finding's resolution note is now shown in the UI, and a one-time "Scan new commits" action is available when automations are unavailable.
**Enterprise MCP Servers Support**
Enterprise admins can now configure an MCP server once at the enterprise level and make it available to the organizations they choose, in Settings → Connections → MCP. An organization's own installation of the same server overrides the enterprise version.
**Private Network MCP Servers for Dedicated Deployments**
For dedicated deployments, Devin can now use MCP servers that are only reachable inside your own network: both the OAuth authorization flow and Devin's calls to the server travel through your private network tunnel instead of the public internet. Enterprise admins can also upload the private certificate authority bundle that Devin should trust for that traffic.
**Replace Secret Values in Place**
Enterprise-scoped secrets can now have their values replaced in place.
**New MCP Marketplace Entries**
The New Relic MCP is now available in the MCP marketplace, and the Mintlify Index MCP is out of beta.
**Model Degradation Notifications**
In Ultra sessions, Devin now notifies you when the lead action model degrades or recovers.
**Lightbox Improvements**
Image lightboxes now show filename captions, an image counter, and clickable prev/next arrows; review comment images open in a lightbox on click.
**Attachment Preview Actions**
Attachment previews now offer both copy link and copy content.
**Faster PR Tab**
PR diff files are now virtualized, speeding up session switching with the PR tab open.
**CI Failure Shortcuts**
Worklog "CI failed" rows now open the PR review tab with checks expanded.
**Preview Tab Renamed to Browser**
The session preview tab is now labeled "Browser".
**Slack Mute Moves the Session to the Webapp**
Muting a Devin session in Slack now disconnects it from the Slack thread and continues it in the webapp.
**Automation Schedule Timezones**
Automation schedule triggers now store their timezone.
**Scan Mode Filter in Code Scan**
The scans list can now be filtered by scan mode (discover/ingest).
**Group(s) Column in User Metrics Export**
The user metrics CSV export now includes a Group(s) column.
**Git Provider Connection Details**
On the git provider settings pages (GitHub, GitLab, Bitbucket), clicking a connection now opens a detail sheet with connection info and management actions in place.
**New MCP Marketplace Entry**
The Cello MCP is now available in the MCP marketplace.
**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.devin.ai/release-notes/overview
The latest Devin updates: recently released features, improvements, and bug fixes across the product, updated with each release.
**SWE-2 Research Preview in the Agent Selector**
SWE-2, Cognition's next-generation software engineering model, is rolling out as a research preview in the agent selector under the "Research preview" section. Choose SWE-2 and a reasoning effort (Medium, High, or Max) when starting a session, or switch to it mid-session with the agent toggle next to the message input; in Slack, use `!swe2`. Enterprise admins enable SWE-2 (Preview) for their enterprise in Settings, and organization admins can then turn it on or off for their organization under Agent capabilities. As a research preview, behavior and availability may change.
**Attach a Folder to a Message**
You can now attach a whole folder to a Devin message by dropping it on the composer or choosing "Upload folder". The folder is compressed in your browser and attached as a single zip file.
**More Automatic Merge-Conflict Fixes**
Devin now fixes merge conflicts on its PRs automatically more often: within 12 hours of session activity (36 hours if the PR is approved), including conflicts that reappear after an earlier one was fixed.
**Shell Command Durations in the Worklog**
Finished shell commands in the session worklog now show how long they took, so slow commands are easy to spot.
**Full Links for PRs, Issues, and Commits**
Devin now links PRs, issues, and commits it mentions instead of writing bare numbers like #123.
**File Tree, Smart Diffs, and Open in Editor in the PR Tab**
The PR tab now has a file tree alongside the diff that highlights the current file as you scroll, a Smart diffs toggle in the diff settings to view a PR as a flat list of files, an "Open in editor" button, and a "File tree on left" option to move the changed-files tree to the left of the diffs.
**Checks Tab and Faster Diffs**
The PR tab has a new Checks tab showing CI status, with tabs ordered Changes, Description, Discussion, Commits, Checks, Bugs. Diffs highlight faster and scrolling large PRs is smoother, and the embedded editor now matches the diff viewer's fonts and colors.
**Devin Review in Spanish and Portuguese**
Devin Review's interface is now available in Spanish and Portuguese for users whose display language is set to Español or Português.
**Devin Review for Bitbucket Data Center**
Devin Review can be enabled for Bitbucket Data Center repositories, including automatic reviews when pull requests are opened or updated. Bitbucket Data Center projects and repos can be selected on the Devin Review home page, the merge bar shows merge, approval, and build status, and admins can configure a webhook (Settings › Integrations › Bitbucket) so Devin updates pull request status and comments in near real time.
**npx devin-review CLI Retired**
The standalone `npx devin-review` command-line tool and its unauthenticated review page have been removed. Use Devin Review on the PR tab or in the Devin Review home instead; existing installed copies of the CLI will no longer work.
**Azure DevOps Improvements**
Devin can now add and remove pull request labels (tags) on Azure DevOps and Azure DevOps Server. In Settings, Azure DevOps connections show the organization name, and organizations or Server collections with more than 100 projects now list repositories from every project.
**Rotate Bitbucket Data Center Tokens**
Admins can rotate a Bitbucket Data Center connection's HTTP access token from Settings → Bitbucket or the enterprise API without disconnecting; the new token must belong to the same Bitbucket user.
**Link Your Bitbucket Data Center Account**
Once an admin registers an OAuth application for a Bitbucket Data Center host, you can link your own Bitbucket account from Devin Review or Profile → Linked accounts. Review approvals and comments Devin posts on that host are then attributed to you rather than the shared connection.
**Microsoft 365 MCP Servers and Plugins**
Microsoft 365 Mail & Contacts, Calendar, To Do, OneDrive & SharePoint, Teams, and Directory (Entra ID) are now available in the MCP marketplace and as plugins that bundle each MCP server with a usage skill. Connect them with your own Microsoft Entra app registration, pick OAuth scopes from a list that explains what each permission is for, and Devin connects with read-only permissions by default when no scope is configured. The Files MCP can return files converted to PDF or JPG.
**Google Workspace MCPs Through Plugins**
Gmail, Google Drive, and Google Calendar MCPs installed through a plugin can now be connected with your own Google OAuth client ID and secret, including custom OAuth scope and resource. On plugin MCPs that need your own OAuth client, the client ID and secret fields now appear first.
**Personal MCP Servers Are Private**
MCP servers you add or install from the Personal tab in Customize are now private to you instead of being shared with your organization, and editing a personal MCP server more than once no longer fails.
**Devin Can Manage Org and Enterprise Plugins**
Org and enterprise admins can have Devin create, update, remove, and install plugins for their whole organization or enterprise, approving each change. Devin can also create, update, and remove skills, rules, MCP servers, and hooks in your uploaded personal plugins through a single tool, including plugins that use a root mcp.json.
**Required and Available-to-Install Plugins**
Org and enterprise admins can make uploaded plugins "Available to install" so members choose whether to add them, or "Required", from the plugin's card or details panel. Renaming a plugin updates its name across Customize, Marketplace, and the session plugins menu, plugin indexing errors on the Customize page now say what actually failed, and plugins can be up to 5x larger (20 MiB, 2,500 files).
**Simpler Create Automation Menu**
The Create automation menu is reordered, "Manual" is now "Create", and "Suggest automations" is now "Suggest for me".
**Reactivated SCIM Users Keep Their Groups**
SCIM users who are deactivated and later reactivated by the identity provider now keep their IdP group memberships, including group changes made while they were inactive.
**Knowledge Is Moving to Skills**
Knowledge is being migrated to [Skills](/product-guides/plugins). Your existing Knowledge notes are converted automatically into skills in a `knowledge` plugin for each scope (organization, enterprise, or personal), with their content unchanged and their folder structure preserved; Devin uses them in sessions the same way it used the notes. Once an organization is migrated, its Knowledge page shows the legacy notes read-only and points to Customize → Skills, where you can view and manage them. No action is needed; the migration is rolling out gradually.
**Filter Sessions by Origin**
The sidebar session filters now include Origin, so you can show or hide sessions by where they were created: Slack, Web, API, Jira, or Linear.
**Command Palette: Open Devin Review from a PR Link**
Paste a pull request link into the Cmd+K palette and press Enter to open that PR's Devin Review.
**Smoother Screen Recordings**
Ask Devin to record at a higher frame rate and its screen recordings capture at up to 60 fps, so animations and scrolling look smooth in demos while keeping Devin's test-case annotations. Default recordings are unchanged.
**Email Notifications for Enterprise and Security-Profile Organizations**
Devin can now send email notifications to members of the same organization for enterprise organizations and organizations with a security profile.
**Enterprise API: Audit-Logs Pagination**
The `total` field in the Enterprise API audit-logs list response is no longer populated (returns `null`). Use `has_next_page` / `end_cursor` to paginate.
**Azure DevOps Server Support**
Organizations can connect Azure DevOps Server 2020/2022 collections with a personal access token from the Azure DevOps settings page.
**"Require Session Access for PR Comments" Org Setting**
Org admins can require that PR comments only reach Devin sessions the commenter has access to, under Settings → Devin → Pull requests. Enterprise admins can enforce it for all organizations.
**Perforce: Workspace Follows Connection Changes**
When a Perforce depot path is removed from an organization's connection, running Devin sessions lose access to it on their next Perforce command; the session's workspace is narrowed automatically and the command is retried.
**@-Mentions and Session Links in Microsoft Teams**
Devin can now @-mention people in its Microsoft Teams replies so they get notified. Sessions linked to a Teams thread show a Teams indicator in the session header, and "connect your account" messages take you to your Connections settings.
**Plugin Management in Customize**
Plugin version history shows readable diffs and a file tree for every version. You can download a plugin you uploaded as a .zip, edit skills and rules from organization plugins directly on the Skills and Rules pages, and share a direct link to a plugin from the address bar.
**MCP Connection Status and Reconnect**
Each MCP server now shows how it is authenticated, with a Reconnect action to redo authentication without uninstalling. Public MCP servers that offer optional sign-in (such as Context7 or Clerk) are marked ready instead of asking you to sign in, and org-owned MCPs where each member connects their own account also appear under Organization so admins can manage them.
**Connect Enterprise MCPs with Your Own Account**
Developers can authenticate enterprise MCPs that use individual OAuth from All organizations → Customize → MCPs → Personal, then use that connection across the applicable organizations.
**New in the MCP Marketplace: ActiveCampaign**
ActiveCampaign lets Devin manage contacts, campaigns, automations, and deals in your account.
**Grafana (OAuth) Plugin Support**
Grafana (OAuth) connects to Grafana Cloud's hosted MCP server with no API key or Docker setup; the Docker-based integration remains available as Grafana (stdio).
**Live Voice Mode**
Voice calls with Devin now run on a live speech model. Starting a call drops you straight into the call controls (with a ringtone while connecting), holding Space to talk works right after muting, and Devin's spoken replies stay in order in the transcript. When a session is connected to Slack, the thread shows who is on the call and how long it lasted instead of Devin's internal voice notes.
**Sessions Wake as You Type**
A sleeping session starts waking up as soon as you begin typing in its composer, so Devin is usually ready to work the moment you press send.
**Copied Messages Keep Their Formatting**
Copying a Devin message now preserves formatting when pasted into email or documents, still pastes as Markdown into code editors, and keeps bullets and links when pasted back into the Devin composer. Transcript copies include each speaker's name.
**Configurable Send Shortcut**
Choose whether Enter or Cmd/Ctrl+Enter sends a message under Settings → Personal → Send shortcut. The preference applies across Devin's composers.
**Skipped Questions Are Shown as Skipped**
When Devin moves on from a question before you answer, the transcript (and the Slack thread, for Slack-connected sessions) now shows the question as skipped, with what was asked, instead of "User answered: (no answer)".
**Reboot VM from the Sidebar**
Sessions that lose their VM now show a "Reboot VM" action in the sessions sidebar instead of a generic blocked or finished state.
**Agent Mode Icons in the Sidebar**
You can show each session's agent mode as an icon in the detailed sidebar. Enable Agent mode under Properties → Property visibility; it is off by default.
**Redesigned Session Dialogs**
Session dialogs — including the confirmations for stopping a session or closing its PRs — have been restyled to match the rest of the app.
**Security Bugs Are Always Checked in Devin Review**
Devin Review now always checks for security bugs in every review; the "Security scan" toggle has been removed from Settings › Review. Whether security bugs are posted to GitHub remains toggleable.
**Slack User-Group Mention Triggers for Automations and Oncall**
Trigger automations and oncall responders when a Slack user group is mentioned. Select a group or enter its Slack ID manually, and optionally restrict matching to specific channels.
**Admins Can Opt into Allowing Automations on Public GitLab Repos**
GitLab connections now have an "Automation scope" setting. Org admins can choose "All connected repos" to let automations access public-visibility GitLab projects on that connection.
**Install a Personal Plugin from a Directory**
Devin can now install a plugin from a folder on its machine (for example an attachment you sent it, once unpacked), not only from a GitHub repository URL.
**Read-only Customize View**
Members who can view Customize but have no layer of their own to install into see a read-only view of what's configured. When no plugins are available to browse, the Browse view explains that admins can add plugins instead of showing a blank list.
**MCP Secrets Are Now Managed in the MCP Page**
Settings → Secrets shows a banner explaining that MCP server credentials moved to each server's page, with a button to the right surface and a docs link.
**Teams Improvements**
Devin sessions attached to Microsoft Teams format replies for Teams (tabular data is sent as file attachments), include images pasted earlier in a thread when Devin is mentioned, and respond faster to new conversations. Picking new or org from the / command menu now works in personal and group chats, and the first-session welcome card suggests tagging @Devin in Teams when your organization has Teams connected. When Devin isn't connected to your Teams organization or a team wasn't fully set up, the bot now explains how to fix it.
**Connection Page Titles**
Browser tab titles on Settings → Connections detail pages show the integration name (e.g. "Microsoft Teams") instead of "Settings".
**Blueprint Source in the v3 API**
The v3 blueprint API lets you choose whether a repository blueprint is managed from .devin/blueprint.yaml in git or from Devin's database (source: "git" | "database" on create/update) and reports the current mode in blueprint responses.
**Clearer Machine Startup in the Computer Tab**
The Computer tab now says the machine is being provisioned while a session's VM is starting, instead of showing a connection failure, and waits up to roughly five minutes for slow-starting machines.
**Sidebar Keyboard Navigation**
Arrow keys now move between every sidebar navigation row, including items in the More menu, and screen readers announce them as a single menu.
**Nested Sidebar Groups Stay Expanded**
Expanded nested session groups in the sidebar stay expanded after you refresh the page.
**Neutral Primary Buttons**
Primary buttons across the app now use a neutral style instead of blue.
**Teams Parity Improvements**
Emoji reactions on Devin messages in Teams (including channel threads) are now forwarded to the session. Devin sees the recent Teams conversation when you reply in a thread or chat that already has a session. PR links in Devin's messages include a Devin Review link for organizations with Devin Review enabled. When a conversation moves from Teams to the Devin webapp or Desktop, the Teams thread shows a notice linking to where it continued. Devin no longer posts a "went to sleep due to inactivity" message, and shared-channel threads note that Devin can only see messages that @mention it.
**PagerDuty Integration for Oncall and Automations**
Connect PagerDuty to Devin to trigger automations on incident events (triggered, acknowledged, resolved, and updated) and to let Devin act as an oncall responder that triages PagerDuty incidents and posts its investigation as incident notes.
**Jira Site Picker**
Connecting Jira with an Atlassian account that belongs to more than one Jira site no longer fails; after signing in, Devin shows the sites you can access and lets you pick the one to connect.
**Datadog MCP on the Stable Endpoint**
The Datadog MCP integration now uses Datadog's stable `/v1/mcp` endpoint. Existing installations can adopt it via "Update from marketplace" in MCP settings and keep their region; users of the OAuth-based Datadog server need to reconnect once after the update.
**21 New Zero-Config OAuth MCP Servers**
21 new one-click integrations in the MCP marketplace — including Dropbox, ClickHouse Cloud, Lucid, Typeform, Coda, GitBook, Railway, Retool, Smartsheet and Make — each connecting through OAuth with no API keys or setup steps.
**Unified Plugin Marketplace**
Browse marketplace now lives in the Customize page's tab bar and shows one list across your scopes: Install lets you pick which scope to install to, cards say where a plugin is already installed, and a "+" adds it to other scopes you manage. The official marketplace loads without separately granting your organization access to its public repository, and a short introduction appears the first time you visit Customize.
**Customize Editor Improvements**
Skill and rule rows open an editor with Preview, Edit, and Version history tabs; removing or uninstalling a plugin asks for confirmation first. Customize shows only the configuration layers you can edit, with plugins your organization or enterprise requires shown as read-only "Required by organization" / "Required by enterprise" sections. Skills from plugins not activated in a session appear greyed out in the `/` and `@` menus.
**Devin-Managed Personal Plugins**
Plugin install approval cards in the worklog now show the plugin's marketplace name, contents summary, and logo, distinguish approval from successful saves and installs, and offer a "View plugin" link to open the item in Customize. Devin can install a plugin from a bare GitHub repository URL and save personal skills, rules, MCP configurations, and hooks from files.
**Effective Membership in Member Lists**
Enterprise admins now see everyone who effectively belongs to an organization — including users granted access through IdP/SCIM group mappings — in the enterprise Members page and each organization's Members page. Group-derived access is labeled with the granting group.
**Safer Secret Defaults**
New secrets default to Personal for non-admins, and creating or importing organization secrets asks you to confirm that everyone in your organization can use them.
**Idempotent Session Creation**
The v1 Sessions API accepts an optional `idempotency_key`; repeating a key returns the original session, and if creation with that key is still in progress the API returns 409 so the caller can retry shortly. The legacy `idempotent` boolean is deprecated.
**Azure DevOps Citations**
Source citations in Devin Wiki for Azure DevOps repositories now open the correct file, linking to the exact commit the wiki was built from.
**Archiving Closes Child Sessions' PRs**
Archiving a session now also closes the open pull requests of the child sessions archived with it; they are listed in the archive prompt so you can choose which to close.
**Multi-PR Dropdown in the Sidebar**
Sidebar sessions with several pull requests in the same state now show a dropdown listing each PR, with the same details as the session header's PR popover.
**Open Changes and PR Files as Diffs**
In a session's Changes and PR tabs, file paths are clickable while Devin's machine is online: clicking opens the file's diff in the embedded editor, with a button to view the full file.
**Desktop Tab on Touch Devices**
The Desktop tab now works like a remote desktop on iPad and other touch devices (tap to click, drag, long-press for right-click, two-finger scroll). When Devin is asleep, the last screenshot fills the pane and hovering it offers a one-click "Wake up Devin" action.
**Continue in a New Session after a Machine Failure**
Hard-blocked machine-failure cards now offer "Continue in a new session" alongside "Try restart", with a note that machine-local files and running processes do not transfer.
**Composer Code Chips**
Typing `` `code` `` in the message composer reliably turns the text into a code chip, Undo turns the chip back into plain text, and a backtick typed inside a chip becomes part of the code.
**Cleaner Chat Rendering**
A question you or a teammate answered now shows as that person's normal chat message. In sessions where you are the only participant, Devin's avatar and name header are hidden (hover a message to see its time) and appear once someone else joins.
**Faster Tab Switching**
Switching between the Progress, Diff, and PR tabs inside a session is roughly twice as fast, the Progress tab keeps your selected step, and switching no longer slows down as more pull-request tabs are kept open.
**Queued Messages Survive Idle/Resume**
Messages queued in a session are no longer lost when the session goes idle and resumes.
**Simplify Devin Review PR Summaries**
Devin Review's top-of-page analysis is now a short, behavior-focused summary (one to two sentences plus up to five bullets) instead of a long implementation walkthrough.
**Improve Progressive Disclosure of Review Findings**
Review findings keep concise summaries while offering an optional "Learn more" section with a plain-language explanation, a concrete example, and a recommended fix; whole findings can be copied.
**Re-scan New Commits and Bulk Remediate via MCP**
Devin can re-run an existing code scan on just the new commits and fix several findings in one go, from a session or any Devin MCP client.
**Webapp Answers Mirrored to Slack**
Answers to Devin's questions given in the web app now appear in the linked Slack thread.
**Slack Controls in the Sidebar**
Link a session to Slack, or turn Slack sync on and off, from the session's "..." menu in the sidebar without opening the session.
**Sync to Teams from the Webapp**
Sessions connected to a Teams chat can turn syncing on and off from the composer, the sidebar, and the command palette, the same way Slack sync works.
**Teams Improvements**
`mute` now fully disconnects a session from the chat and `unmute` or mentioning @Devin reconnects it; a "Detach session" card appears when Devin goes to sleep in DMs and group chats; Devin shows an "Approve deployment" button when it asks to deploy; and the Teams settings page includes the keyword tutorial and thread-mode setting.
**Regex Matching in Text Fields**
Automation text fields can use case-sensitive regular expressions (Google RE2 syntax).
**Grayed-Out Templates**
Templates that need an MCP server or integration your organization hasn't set up stay visible but grayed out, with a hint explaining what to connect.
**Update Approvals Show a Diff**
Approving an automation update now shows exactly what changes: added, removed and modified triggers and actions, settings as old → new, and prompt edits as a line diff.
**Automations Page Refresh**
The Automations page opens on a "Mine" tab by default, empty tabs show the creation options in place, creating an automation or on-call responder opens in a side panel, and the preflight-check card and script editor have been redesigned.
**Marketplace Updates**
The Meticulous MCP server is out of beta, and Intercom now connects with an access token.
**Plugins**
Plugins bundle skills, rules, hooks, and MCP servers into a single installable package so you can customize how Devin works and share that setup across your team. Install plugins from the marketplace in Settings → Marketplace or from a repository, for your organization or your whole enterprise; plugin details show where a plugin comes from (pinned commit or tracked ref and folder) and which scopes have it installed, and skills from a newly installed plugin are available in the `/` and `@` menus right away. Every install shows a security notice describing what the plugin can do and asks you to confirm you trust its source. Org and enterprise admins can mark plugins as required or available, and organizations inherit enterprise-managed plugins automatically.
**Environment Build Attention**
Enterprise admins can see which organizations need attention on the Environment page — consecutive failed builds, no usable snapshot, and a "Needs attention" filter — plus a "Last build failed" filter for repositories in an organization's environment settings.
**Roles and Access**
Roles whose only remaining assignments are expired service users can be deleted. Members with an Ask-only role (such as "DeepWiki Only") can see their past Asks in the sidebar, and view-only roles' session lists are restored.
**Git Bash on Windows**
On Windows machines, Devin runs commands under Git Bash by default (PowerShell remains available on request, and is used when Git Bash is not installed).
**Blueprint Suggestions**
Devin validates proposed repository blueprints (YAML and schema) before suggesting them, and the setup guide lists the optional Clone step.
**Lightbox Keyboard Navigation and Mermaid Diagrams**
Use the arrow keys to move between images in the lightbox carousel, and Mermaid diagrams now join the carousel alongside images.
**Single Devin PR Comment**
Devin's PR intro comment and the "Original prompt" details block are now a single comment, with the prompt shown below the intro.
**Code Scan Multi-Select Findings**
Select several findings at once to assign them to a single Devin session (one branch/PR) or to bulk-update their status (reviewed or dismissed).
**Code Scan No-Op Runs When There Are No New Commits**
Scan-new-commits runs (including scheduled runs in Automations) now skip starting a session when the repository has no new commits since the last scan; the run is recorded as completed with no ACU usage, and the webapp shows a "No new commits" toast.
**AWS and Braintrust MCP Servers in the Marketplace**
The MCP marketplace now includes AWS and Braintrust servers.
**Google Workspace MCP Setup Guidance**
The Google Drive, Gmail, and Calendar MCP configure pages now warn that the Google Cloud project must be enrolled in the Developer Preview and explain the bring-your-own OAuth client setup.
**Security Profiles Can Allow Orgs' Custom MCP Installations**
Enterprise admins can now let an enterprise security profile permit organizations' own custom MCP server installations.
**Microsoft Teams Improvements**
Files shared via SharePoint render as file attachments, Devin shows a typing indicator while working, /new is supported in group chats, and outgoing attachments are sent as their own activity.
**Partial Snapshot Builds on Clone Failures**
A new enterprise setting lets snapshot builds finish as partial when a repository cannot be cloned, instead of failing the whole build.
**New Sidebar Grouping and Filters**
The session sidebar can now group sessions by pull request status or by repository, and session filters now include Devin mode.
**Cleanup Scan Type**
A new cleanup scan type finds dead code and cleanup opportunities in your repositories.
**/scan Composer Command**
You can now start a code scan directly from the composer with the /scan command.
**Scheduled Scans in Automations**
Automations now support a code scan agent type, so you can schedule recurring scans or re-scan new commits automatically.
**Redesigned Findings Tab**
The scan findings tab has been redesigned for easier triage.
**Richer Trigger Event Details**
Automation runs now show richer event details for GitLab, Jira, incident.io, and GitHub triggers.
**Clearer Reply Delivery**
Slack users who are not members of the session's organization are now warned when their replies cannot reach Devin.
**Multi-Select Tag Filters**
The session sidebar now supports multi-select metadata tag filters with per-tag counts, plus a machine-type filter.
**Split Editor Groups in the Session Workspace**
The session workspace editor now supports VS Code-style split editor groups.
**Code Scan History**
The scan detail page has a scan history sheet, and redesigned history rows show each run's profile and cost.
**Code Scan Validation Severities**
Code scan profiles can now configure which finding severities require validation, with a threshold meter in the profile editor.
**New MCP Marketplace Servers**
Gmail, Google Calendar, Gamma, and Supabase MCP servers are now available in the marketplace, and marketplace entries now show icons.
**Clearer MCP Install Approvals**
MCP install approval cards now show the server's identity, source, and resolved scope before you approve.
**Authentication**
We are upgrading our authentication platform and login page.
**New Org Permission: Manage Personal Automations**
Org admins can control who can manage personal automations independently from who can manage system user automations. Account-level automation permissions are also now more granular.
**Queued Message Improvements**
Queued messages are now delivered while Devin is in a long-running wait, and pressing Cmd/Ctrl+Enter while editing a queued message sends it immediately.
**Waiting Activity Status**
Sessions now show a dedicated "Waiting" activity status while Devin is intentionally sleeping in a wait.
**Undo for Folder Moves**
Moving sessions between folders now shows an undo toast, and Cmd/Ctrl+Z triggers the newest toast's Undo action.
**Accessibility Improvements**
Reduced-motion users now get static/text equivalents for animated elements, and high-contrast support has been improved.
**Redesigned GitHub Link Badges**
Devin's GitHub link badges (PRs, branches, commits) have a refreshed design.
**Smarter @mention Routing in Slack Threads**
@mentioning Devin in a thread now routes your reply to the session you're subscribed to.
**Default Working Org for Slack Channel Sessions**
New Slack channel sessions are routed using the mentioning user's default working organization.
**Finer Automation Schedule Controls**
Hourly schedules now have a minute selector, and run-once schedules use a date picker.
**Multiple Slack Channels in Automation Triggers**
Automation triggers can now select and edit multiple Slack channels.
**Improve Existing Automations with Devin**
A new "Improve with Devin" action lets Devin iterate on an existing automation for you.
**Linked Triggering Events**
An automation run's triggering event source now links to its origin (e.g. the Slack message or issue).
**Support Jira previous\_status Automation Triggers**
Jira status\_changed triggers can now filter on the previous status, and the new status is optional.
**Security Section**
Code scan pages moved from /code-scan to /security (old links redirect). Scan sessions are listed for the user who triggered them, and archiving a scan's root session cancels the scan.
**Scan Now**
A "Scan now" button in the Auto Scan configure dialog starts a scan immediately.
**Batch Remediation via v3 API**
New v3 API routes support batch remediation of findings at the org and enterprise level.
**Allow PRs to Be Opened by Session Participants Configuration**
A new org setting, "Allow PRs to be opened by session participants", lets sessions open PRs as a validated session collaborator.
**Streamlined MCP Marketplace Install and OAuth Connect**
Installing an MCP server from the marketplace is now a single streamlined flow: install cards stay visible through approval, and the OAuth screen opens directly from the card.
**Redesigned Session Page Header**
The session page header is more compact, with tags and session hierarchy built in.
**Redesigned Sessions Sidebar**
The sessions sidebar has been redesigned with customizable nav tabs, grouping, richer filtering, and a cleaner session list.
**Refreshed Chat Visual Design**
The chat interface has a refreshed visual design.
**Nested Sub-Devin Sessions**
Sub-Devin sessions are now shown as a nested tree in the sidebar.
**Hideable Sidebar**
The sidebar can be fully hidden and peeked on hover.
**Session Subscribers**
Follow and view others' sessions, with subscriber-based sidebar organization and filtering.
**Inline Session Rename Shortcut**
Press Cmd/Ctrl+Option+R on a session page to rename the session inline.
**Stop Devin Shortcut**
Press Cmd/Ctrl+Shift+Backspace to stop Devin while it is working.
**Default Org Picker in Slack DMs**
In Slack DMs with Devin, you can now set your own default organization with the !org picker.
**Bearer Secrets for Automation Webhooks**
Automation webhooks can now authenticate with an Authorization: Bearer secret.
**Duplicate Findings Fix**
Resolved a regression in Devin Review that led to findings being reported multiple times.
**Clearer Findings**
Improved clarity and conciseness of Devin Review findings.
**Change a Scan's Profile**
You can now change a code scan's security profile from the UI.
**Scan Effort Selection**
Choose a scan effort (normal/deep) on the ingest scan form, and set it via the v3 API.
**New v3 Scan API Endpoints**
The v3 API can now trigger an incremental (diff) scan immediately and accepts multiple repos on ingestion scan start.
**Finding Resolution Notes**
A finding's resolution note is now shown in the UI, and a one-time "Scan new commits" action is available when automations are unavailable.
**Enterprise MCP Servers Support**
Enterprise admins can now configure an MCP server once at the enterprise level and make it available to the organizations they choose, in Settings → Connections → MCP. An organization's own installation of the same server overrides the enterprise version.
**Private Network MCP Servers for Dedicated Deployments**
For dedicated deployments, Devin can now use MCP servers that are only reachable inside your own network: both the OAuth authorization flow and Devin's calls to the server travel through your private network tunnel instead of the public internet. Enterprise admins can also upload the private certificate authority bundle that Devin should trust for that traffic.
**Replace Secret Values in Place**
Enterprise-scoped secrets can now have their values replaced in place.
**New MCP Marketplace Entries**
The New Relic MCP is now available in the MCP marketplace, and the Mintlify Index MCP is out of beta.
**Model Degradation Notifications**
In Ultra sessions, Devin now notifies you when the lead action model degrades or recovers.
**Lightbox Improvements**
Image lightboxes now show filename captions, an image counter, and clickable prev/next arrows; review comment images open in a lightbox on click.
**Attachment Preview Actions**
Attachment previews now offer both copy link and copy content.
**Faster PR Tab**
PR diff files are now virtualized, speeding up session switching with the PR tab open.
**CI Failure Shortcuts**
Worklog "CI failed" rows now open the PR review tab with checks expanded.
**Preview Tab Renamed to Browser**
The session preview tab is now labeled "Browser".
**Slack Mute Moves the Session to the Webapp**
Muting a Devin session in Slack now disconnects it from the Slack thread and continues it in the webapp.
**Automation Schedule Timezones**
Automation schedule triggers now store their timezone.
**Scan Mode Filter in Code Scan**
The scans list can now be filtered by scan mode (discover/ingest).
**Group(s) Column in User Metrics Export**
The user metrics CSV export now includes a Group(s) column.
**Git Provider Connection Details**
On the git provider settings pages (GitHub, GitLab, Bitbucket), clicking a connection now opens a detail sheet with connection info and management actions in place.
**New MCP Marketplace Entry**
The Cello MCP is now available in the MCP marketplace.
**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)
# Devin Automations tutorial
Source: https://docs.devin.ai/tutorial-library/automations
Video walkthrough of Devin Automations: four examples of automating repetitive engineering tasks in plain English with triggers and schedules.
This video walks through four examples of using Devin Automations to hand off repetitive engineering tasks, described in plain English.
To set up your own, see [Automations](/product-guides/automations).
# Build an iOS app with Devin
Source: https://docs.devin.ai/tutorial-library/ios-app
Building an iOS app with Devin on a macOS VM: building SwiftUI code, testing in the iOS Simulator, and shipping to TestFlight
## Before you start
Make sure you have a Devin [Pro or Teams](/admin/billing/self-serve) account. macOS sessions are available by default.
* **Enable macOS VMs**: ask your account team to turn on macOS VMs for your organization. See [macOS support](/onboard-devin/environment/macos-support).
* **Enable Computer Use**: turn on **Computer use** under [Settings > Devin](https://app.devin.ai/settings/devin) > **Sessions** so Devin can interact with the Simulator and record its testing. See [Computer Use](/work-with-devin/computer-use).
## Step 1: Prompt Devin to build the app
Open [Devin](https://app.devin.ai/) and choose **macOS** from the platform menu below the prompt box. Xcode, the iOS Simulator, and Homebrew are preinstalled.
Type what you want Devin to build:
```text theme={null}
build a flappy otter game for iphone, like flappy bird but a cute otter instead
```
## Step 2: Watch Devin build and test
Devin works through the task much like an iOS developer would:
1. **Creates the project in Xcode**
2. **Builds and fixes errors**
3. **Runs the game in the Simulator**
4. **Plays the game**: taps to make the otter jump with [Computer Use](/work-with-devin/computer-use), checks that scoring and collisions work, and [records](/work-with-devin/testing-and-recordings) the run.
5. **Shares the result**: sends you the recording and opens a pull request if the session has a repository.
You can open the **Computer** tab in the session workspace to watch the booted simulator live while Devin taps through the app.
## Step 3: Review and iterate
Continue building in the same session with more features:
## Optional: Ship a beta to TestFlight
To test on a real iPhone, see [Upload iOS builds to TestFlight](/onboard-devin/environment/testflight).
See [macOS support limitations](/onboard-devin/environment/macos-support#limitations) to learn more about Devin macOS support.
## Next steps
App Store Connect setup, API keys, and secrets for uploading builds
Blueprint options, preinstalled tools, and troubleshooting for macOS sessions
How Devin tests your app and records the results
# Devin repo setup tutorial
Source: https://docs.devin.ai/tutorial-library/repo-setup
Set up Devin's environment for your repository, so sessions boot with dependencies, tools, and secrets ready.
To set up Devin's environment, just ask Devin to do it for you.
For the full guide, see [Environment configuration](/onboard-devin/environment) and [Blueprints](/onboard-devin/environment/blueprints).
# Fix a bug with Devin in Slack
Source: https://docs.devin.ai/tutorial-library/slack-bug-fix
Watch Devin get tagged on a bug report in a Slack thread and turn it into a fix, from triage to a pull request, without leaving Slack.
In this video, Devin tackles a bug in Slack with Walden: a bug report in a thread becomes a session and a pull request.
To set this up in your workspace, see the [Slack integration](/integrations/slack).
# Advanced Capabilities
Source: https://docs.devin.ai/work-with-devin/advanced-capabilities
Devin can orchestrate managed sessions in parallel, analyze past work, create playbooks, and keep your organization's knowledge base current.
**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. When the orchestration itself has structure — a wide fan-out with a combine step, or stages whose prompts are built from earlier results — ask for a [dynamic workflow](/work-with-devin/dynamic-workflows) instead, so the coordination runs as a recorded, resumable script.
**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.devin.ai/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. For a video walkthrough, see the [Ask Devin tutorial](/tutorial-library/ask-devin).
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**.
Add repositories to index from Settings > DeepWiki 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
# Devin browser authentication
Source: https://docs.devin.ai/work-with-devin/browser-auth
Log in once in Devin's Interactive Browser, save the browser profile, and have every future Devin session start already authenticated to your web apps.
Devin often needs to be logged into web apps — your staging environment, an admin dashboard, a SaaS tool — before it can do useful work. Instead of repeating a login every session, log in once and have Devin save the browser profile so all future sessions start authenticated.
## The workflow
Open the **Desktop** tab in the session and drive the browser yourself: complete the login, including SSO redirects, MFA prompts, and CAPTCHAs. See [Interactive Browser](/work-with-devin/devin-session-tools#interactive-browser).
Say **"save the browser profile"** or **"persist my login sessions"**. Devin calls its `save_browser_profile` tool, which zips the browser data directory (cookies, `localStorage`, and other Chrome profile data) and attaches it to your organization's blueprint as a file. Other phrasings work too — "save browser cookies", "remember my browser logins", "keep my browser state", "save the browser to my snapshot".
Devin proposes a one-time update to the **organization-level** [blueprint](/onboard-devin/environment/blueprint-reference), adding an `initialize` step named *Initialize browser profile* that unzips the saved profile into the browser data directory. Review it in your timeline and approve it.
Every new session in the organization restores that browser state during setup, so Devin's browser is already logged in when the session starts. No further approvals needed.
The restore step is a normal blueprint `initialize` step, referencing the profile zip through a `$FILE_BROWSER_PROFILE` [file attachment](/onboard-devin/environment/blueprint-reference#file-attachments):
```bash theme={null}
# Restore saved browser profile from org blueprint files
if [ -f "$FILE_BROWSER_PROFILE" ]; then
mkdir -p /home/ubuntu/.browser_data_dir
unzip -o "$FILE_BROWSER_PROFILE" -d /home/ubuntu/.browser_data_dir
fi
```
To refresh expired sessions, log in again and ask Devin to save the profile again — the tool replaces the existing step rather than adding a second one.
## Limitations and security
Saved profiles are **organization-level**, not per-repository. Anyone in your organization can start a session that loads the profile, including the logins, cookies, and session tokens it contains. Only save profiles for accounts your whole organization is allowed to use — prefer a dedicated service account over a personal one.
* **No browser extensions.** Only profile data is restored. Extension-based tools (for example, MetaMask) are not loaded, so flows that depend on an extension won't work.
* **Saved passwords are excluded.** Chrome's password store is skipped, along with caches — so the profile carries session state, not credentials. Store credentials as [Secrets](/product-guides/secrets) instead.
* **Size limit.** The profile zip must be under 200 MB.
* **Sessions still expire.** Cookies restored from the profile expire on the app's normal schedule; re-save the profile when they do.
## Alternatives
| Approach | Best for |
| ----------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| Save browser profile | Logins that are hard to script — SSO, MFA, CAPTCHAs — where clicking through once is easiest |
| [Playwright login script](/work-with-devin/computer-use#scripted-browser-use-via-playwright) in `.agents/skills/` | Scriptable logins and injecting arbitrary browser state such as `localStorage` keys, per repository and versioned in git |
| [Secrets](/product-guides/secrets) | API tokens and credentials Devin uses from the shell or from a login script |
# Devin Code Scans
Source: https://docs.devin.ai/work-with-devin/code-scans
Use Devin Code Scans to find performance, test coverage, dead code, accessibility, and other issues across your repositories, then fix them with Devin
A code scan is a Devin session, and the child sessions it starts, that reads one or more repositories, reports **findings**, and can fix them through pull requests. Security scans are covered in [Security Swarm](/work-with-devin/security-swarm). This page covers the other scan types.
To run a scan:
* You need the **Use code scans** permission and permission to use Devin sessions. See [Access and permissions](/work-with-devin/security-swarm#access-and-permissions).
* Your organization must have access to the repository you want to scan.
## Start a scan with `/scan`
1. In the composer, type `/scan` followed by what you want to find, and mention the repositories to scan. For example: `/scan find N+1 queries in @acme/api`. Repositories you've selected in the composer are included too.
2. Send the message. Devin starts a new session to set up the scan and opens it. If you sent `/scan` on its own, Devin suggests example scans, such as finding slow database queries or unused code, and asks what you want to find.
3. Devin chooses the scan type from your request and states it in one line, for example that it will set up a custom scan that only looks for camelCase variable names. Reply if you want something different.
4. Devin shows a **Code scan setup** card. Confirm the **Repositories** to scan, and optionally add guidance under **What should the scan focus on?**. If you didn't mention a repository, Devin preselects the one you've worked in most, based on your recent pull requests.
5. Click **Start scan**. Devin creates the scan only after you submit the card, then shares a link to the scan's session. Click **Dismiss** to cancel setup instead.
You don't need to pick a scan type or configure the scan yourself. Requests that cover a whole area, such as a performance scan of a repository, use the matching [scan type](#scan-types). Narrower or different objectives, such as finding memory leaks, use a **Custom** scan focused on what you described.
When a non-security scan finishes, Devin sends you a Slack direct message summarizing the findings, unless you asked for a different notification or none. Slack messages require your organization's Slack integration to let sessions send direct messages.
Non-security scans run unattended at normal effort. Effort choices and interactive mode, where Devin pauses so you can review a threat model before investigating, are only available for [security scans](/work-with-devin/security-swarm#interactive-mode).
## Scan types
| Scan type | What it looks for |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Performance** | Performance issues and opportunities to make your code faster and more efficient. |
| **Database queries** | Problems in the places your code queries its data stores: inefficient, incorrect, unsafe, or unreliable queries. |
| **Test coverage** | Flows and components that aren't covered by tests. |
| **Dead code** | Code nothing reaches anymore: unused functions, modules, flags, and dependencies that are safe to remove. |
| **Code quality** | Maintainability problems that make the code harder to read, change, and keep correct. |
| **Cleanup** | Messy, redundant, and over-built code that can be cleaned up without changing behavior. |
| **Telemetry** | Places that need telemetry or tracking instrumentation. |
| **Accessibility** | Frontend code that doesn't meet accessibility guidelines (WCAG), such as missing labels, broken keyboard access, and low contrast. |
| **Compliance** | Gaps against the regulations, standards, and policies the scan is set up to check, such as sensitive-data handling, audit trails, and retention. |
| **Migration docs** | Traces your code's end-to-end flows and business logic and produces migration-ready documentation with diagrams. |
| **Custom** | Anything else you describe, such as places that log personal data or a naming convention your team wants to enforce. |
For vulnerabilities and attack surfaces, use a [Security Swarm](/work-with-devin/security-swarm) scan.
## Review and fix findings
Open the **Findings** tab in the session that started the scan, or in the scan's main session, to work through its findings. Open findings are grouped by stage:
* **Unassigned** — no remediation session has started.
* **Assigned** — a remediation session has started, but no pull request is open.
* **PR open** — a pull request for the finding is open.
For each finding, you can:
* **Assign to Devin** — start a Devin session that fixes the finding and opens a pull request. Use **Open session** to follow the work and **Open PR** to review the result.
* **Dismiss** — remove a finding that doesn't need action.
While a scan is running, the Findings tab in the scan's main session also offers **Pause scan**, **Resume scan**, and **Kill scan**. These controls require **Manage code scans**.
## Scale scanning
### Scan new commits
After a scan of any type completes, click **Scan new commits** in the Findings tab to start an incremental run that scans only the commits added since the scan's last completed run. The run uses the scan's existing configuration and adds its findings to the same scan. The button isn't shown while the scan is running or after it's archived, and it requires **Manage code scans**. If no new commits have landed, no run starts.
You can also ask Devin in a session to scan an existing scan's new commits.
### Automations
[Automations](/product-guides/automations) can run scans of any type on a schedule or in response to an event. Choose the **Code scan** agent type, then under **Scan**:
* Choose **Create a new scan** to start a fresh scan each time the automation fires. Pick the repositories, scan type, and profile. Non-security scan types require a [scan profile](/work-with-devin/security-swarm#scan-profiles) of the same type.
* Choose an existing scan to scan its new commits each time the automation fires. The scan must already have a completed run.
Scans started by automations run unattended. See [Start scans from Automations](/work-with-devin/security-swarm#start-scans-from-automations).
### API
The [Code Scans API](/api-reference/v3/code-scans/triggering-code-scans) starts scans, polls them, and reads findings without the web app. When you start a non-security scan through the API, you must pass a `profile_id` for a profile of that scan type; `scan_type` defaults to the profile's type. Scans started through the API are not interactive.
## Related pages
* [Security Swarm](/work-with-devin/security-swarm) — security scans, scan profiles, interactive mode, and code scan permissions.
* [Triggering Code Scans via the Devin API](/api-reference/v3/code-scans/triggering-code-scans) — the end-to-end API flow.
* [Automations](/product-guides/automations) — schedule and trigger scans.
# Computer Use
Source: https://docs.devin.ai/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), **Windows**, and **macOS** sessions, and on [Outposts](/cloud/outposts/overview) machines 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, Windows, or macOS), 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 |
| macOS | Supported — sessions on [macOS environments](/onboard-devin/environment/macos-support) run a full macOS desktop, including the iOS Simulator |
| 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). |
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); on macOS it can test Mac apps and iOS apps in the Simulator. To run sessions on another platform, configure a blueprint as described in [Windows support](/onboard-devin/environment/windows-support) or [macOS support](/onboard-devin/environment/macos-support). For an end-to-end example, see [Build an iOS app with Devin](/tutorial-library/ios-app).
On macOS, Devin uses the Command key for keyboard shortcuts (⌘C, ⌘V) rather than Control.
## How to Enable It
Computer Use is controlled by the **Computer use** toggle in your organization's Devin settings.
1. Go to [**Settings > Devin**](https://app.devin.ai/settings/devin)
2. Under the **Sessions** section, toggle **Computer use** 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
Combined with [Secrets](/product-guides/secrets) exposed as environment variables, a script in `.agents/skills/` can inject **any** browser-level state at the start of every session — not just cookies. For example, a script can call `page.evaluate()` to write `localStorage` keys (feature flags, API tokens, tenant selection) read from environment variables, so Devin's browser always starts in the state your app expects. To persist state you captured manually instead of scripting it, see [Browser authentication](/work-with-devin/browser-auth).
## 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.devin.ai/work-with-devin/data-analyst
Use the Data Analyst agent (DANA) for fast database queries, data analysis, and visualizations in Slack or the web app.
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 next to the message input
3. Open the **Mode** submenu and select **Data** — the picker then shows **Data Analyst**
4. Start your session with a data-related question or task
The Data Analyst Agent isn't available on free or trial plans, so the **Data** mode doesn't appear in the picker for those organizations.
### 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 [Customize > MCPs](https://app.devin.ai/customize?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 repository wikis
Source: https://docs.devin.ai/work-with-devin/deepwiki
DeepWiki auto-generates architecture diagrams, documentation, and source links for every repo, configured with a .devin/wiki.json file.
## 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. For a short video introduction, see the [DeepWiki tutorial](/tutorial-library/deepwiki).
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. Both fields are required, and `pages` must list at least one page. When a config file is present, we bypass the default cluster-based planning and create exactly the pages you specify — so list every page you want. 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, required)
Provides context and guidance to help the documentation system understand your repository better. Include the `repo_notes` key even if you have no notes to add — use an empty array (`[]`).
* **content** (string, required): The note content (max 10,000 characters)
* **author** (string, optional): Who wrote the note
### pages (Array, required)
Specifies exactly which pages should be created in your wiki.
This field is required and must contain at least one page. Pages are treated as explicit instructions: only the pages you define in the JSON will be generated, no more, no less. A `.devin/wiki.json` that omits `pages` (or leaves it empty) is rejected, so list every page you want created.
* **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: Use Repo Notes to Emphasize Priorities
Use `repo_notes` to tell Devin what to emphasize, and list the `pages` you want alongside them. Notes guide *how* each page is written; `pages` determines *which* pages are created.
```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."
}
],
"pages": [
{
"title": "Backend API Layer",
"purpose": "Document the backend/ API services and how the frontend and infra interact with them"
},
{
"title": "Frontend Overview",
"purpose": "Document the frontend/ React components and how they consume the backend API"
}
]
}
```
### Example 2: Ensuring Specific Folders Are Documented
If your large repository has important folders that aren't being included in the wiki, add a page for each one and use `repo_notes` to explain why they matter:
```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."
}
],
"pages": [
{
"title": "CUI Components",
"purpose": "Document the cui/ folder and its critical UI components"
},
{
"title": "Backend API Logic",
"purpose": "Document the main API logic in the backend/ folder"
},
{
"title": "Shared Utilities",
"purpose": "Document the shared utilities in the utils/ folder"
}
]
}
```
### Example 3: Addressing Missing Components
If you notice certain parts of your codebase aren't being documented, add a page for each and emphasize them in `repo_notes`:
```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."
}
],
"pages": [
{
"title": "Testing Utilities and Patterns",
"purpose": "Document the test utilities and patterns in the testing/ directory"
},
{
"title": "Operational Scripts",
"purpose": "Document the deployment and maintenance scripts in the scripts/ directory"
}
]
}
```
### 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.
Add a page to the `pages` array for each folder you want covered, and use `repo_notes` to explain why they matter. The wiki generates only the pages you list, so any folder without a page won't appear.
### "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. Specify **all** pages you want created, with clear titles and purposes (at least one page is required)
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.devin.ai/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.devin.ai/work-with-devin/devin-cli
Download and install Devin CLI, a local coding agent that runs in your terminal on macOS, Linux, WSL, and Windows, with handoff 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.
## Download Devin CLI
```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 **Install Devin CLI in Devin Desktop**.
**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.
After you restart your terminal, enter a project directory and type `devin` to start.
For full documentation — including commands, configuration, and extensibility — see the **[Devin CLI docs](/cli)**.
Install and start coding in 2 minutes
Must-know commands and keyboard shortcuts
# Hand off to Devin Cloud from Any Agent
Source: https://docs.devin.ai/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`](/cli/handoff) 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.devin.ai/work-with-devin/devin-mcp
Set up the official Devin MCP server so external AI tools can manage sessions, playbooks, knowledge, and repository docs.
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 at the top of the **Settings > Devin API** page.
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 |
| ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **`devin_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 (the legacy name `list_integrations` is still accepted) |
## 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.devin.ai/work-with-devin/devin-review
A new way to quickly review and understand complex PRs. Track review consumption and manage organization ACU limits.
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), GitLab (including Self-Managed GitLab), and connected Azure DevOps repositories.
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).
Connected Azure DevOps repositories support diffs, analysis, comments, and auto-review;
see [Supported Git Providers](#supported-git-providers) for available actions.
Public PRs don't require a Devin account. Private PRs
can be viewed with a Devin account.
## 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.
* **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.
* **Azure DevOps** — Paste the full PR URL (for example `https://dev.azure.com/.../pullrequest/...`, or your Azure DevOps Server host) into [app.devin.ai/review](https://app.devin.ai/review) after connecting the repository to Devin.
## Supported Git Providers
| Capability | GitHub | GitLab | Bitbucket | Azure DevOps |
| ----------------------------- | ------ | ------- | --------- | ------------ |
| View diffs and analysis | Yes | Yes | No | Yes |
| Bug catcher | Yes | Yes | No | Yes |
| Codebase-aware chat | Yes | Yes | No | Yes |
| Code changes from chat | Yes | Yes | No | No |
| Comments and reviews | Yes | Yes | No | Yes |
| Merge / close / draft actions | Yes | Partial | No | Partial |
| Auto-merge | Yes | Partial | No | No |
| Auto-review | Yes | Yes | No | Yes |
**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).
**Azure DevOps** includes Azure DevOps Services (`dev.azure.com`) and Azure DevOps Server 2020/2022. Connect through the [Azure DevOps integration](/enterprise/integrations/azure-devops), a [Microsoft Entra service principal](/enterprise/integrations/azure-devops-service-principal), or an Azure DevOps Server collection with a personal access token, then enroll repositories from [Settings > Review](https://app.devin.ai/settings/review) for auto-review. Devin posts automated findings through the connected service identity. To comment, reply, resolve threads, vote on a PR, or abandon a PR as yourself, link your personal Azure DevOps account to Devin — these actions are attributed to you, not the service identity. Azure DevOps Server connections use a shared personal access token, so actions as yourself are not available there. Applying chat edits, merging, draft actions, and auto-merge are not available, and the personal PR inbox does not list Azure DevOps PRs.
## Reading a Review
The analysis starts with a short overview of the PR's behavior and impact, followed by key changes in bullets when useful. Related edits are grouped into sections with explanations alongside their diffs.
On mobile, the review opens on **Changes**. Switch to **Bugs** to see bugs, flags, and security findings, or use **Description**, **Discussion**, and **Commits** for the PR's other details.
When a link to a GitHub comment or review opens in Devin Review, it scrolls to and highlights the target. This also works in the review tab inside a Devin session.
## 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 usage counts toward its billing organization's [ACU limit](/admin/billing/org-acu-limits). New review work is blocked when that organization reaches its 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](#security) and hardening suggestions as PR comments.
* **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 security findings are posted as PR comments. Investigate and informational flags are not posted by default. 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.
Bug findings keep the summary concise. When available, expand **Learn more** for a detailed explanation, a concrete example, and a recommended fix. The copy button copies the whole finding, including its location, explanation, and any suggested code change.
### 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 runs on every review and cannot be turned off; use the [posting settings](#posting-to-github) to control whether security findings are posted as PR comments.
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. See [Start Devin from a PR comment](/integrations/gh#start-devin-from-a-pr-comment).
### 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 Devin settings** — Go to [Settings > Devin](https://app.devin.ai/settings/devin) > **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.
## 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.devin.ai/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. For a video tour, see the [Devin 2.0 IDE walkthrough](/tutorial-library/ide-walkthrough); for a real example of delegating work from the IDE, see [Delegate a refactor in the Devin IDE](/tutorial-library/ide-refactor).
### 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 **Browser** tab in the session UI. If [Computer Use](/work-with-devin/computer-use) is enabled for your organization, this tab is labeled **Computer** instead. 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.
### 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.
### Persisting browser state across sessions
Browser state can also carry over to *future* sessions. After logging in through the Interactive Browser, ask Devin to **"save the browser profile"** or **"persist my login sessions"**. Other phrasings work too — "save browser cookies", "remember my browser logins", "keep my browser state", "save the browser to my snapshot".
Devin then zips the browser data directory (cookies, `localStorage`, and other Chrome profile data) and proposes a one-time update to your organization's [blueprint](/onboard-devin/environment/blueprint-reference). Once you approve it, every future session starts with that browser state restored automatically — no repeated logins.
See [Browser authentication](/work-with-devin/browser-auth) for the full workflow, security considerations, and limitations.
## 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 |
| **Browser** or **Computer** (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
# Devin Dynamic Workflows
Source: https://docs.devin.ai/work-with-devin/dynamic-workflows
Orchestrate many Devin sessions with a deterministic Python script: fan out work, pipe structured results between stages, and resume a run where it stopped.
Dynamic Workflows are available in any Devin session — just describe the work and ask Devin to run it as a workflow.
**Enterprise accounts:** the feature is off until an enterprise admin turns on **Dynamic workflows** under [Enterprise Settings > Devin](https://app.devin.ai/settings/enterprise-devin). Until then, Devin won't run workflows in any of the enterprise's organizations.
## What are Dynamic Workflows?
A dynamic workflow is a **deterministic Python script that orchestrates a team of Devin agents**. Devin writes the script, runs it, and the script decides which agents run, in what order, and what each one is told — using the structured results of earlier agents to build the prompts of later ones.
Every agent call is recorded, so a workflow run is observable while it executes and resumable if it is interrupted: completed agents replay their recorded results instantly, and only the unfinished work runs again.
This goes a step beyond [managed Devins](/work-with-devin/advanced-capabilities#managed-devins), where the coordinating session spawns and babysits child sessions by hand. In a workflow, the orchestration itself is code.
## When to use a workflow
Ask for a workflow when the work has real structure:
* **Wide fan-out with a combine step** — roughly five or more independent units (files, modules, endpoints, tickets) that each need judgment or verification, whose results are then rolled up.
* **A staged pipeline** — later stages consume the structured output of earlier ones, for example *audit → fix → verify*.
Stick with a plain session (or a couple of [managed Devins](/work-with-devin/advanced-capabilities#managed-devins)) when:
* The change is mechanical — a codemod, linter autofix, or generator does it faster and more reliably than agents.
* Only one or two independent sessions are needed, with no data flowing between them.
* The work is tightly coupled through shared state, or is small and sequential.
### Example prompts
You describe the task and ask for a workflow; Devin writes the script.
**Migration** — fan out one agent per unit on its own branch, then roll up:
```text theme={null}
Use a workflow to move every job in jobs/ from the legacy cron runner to our
new scheduler API — one agent per job, each working on its own branch and
running the job's tests — then roll up which jobs need manual attention
```
**Research** — gather evidence in parallel, then synthesize:
```text theme={null}
Use a workflow to evaluate Postgres, DynamoDB, and CockroachDB for the new
events service: one agent per option scoring it against our latency, cost,
and operations requirements, then a final agent that compares the evidence
and recommends one
```
**Code review** — one reviewer per file, then a merge step:
```text theme={null}
Use a workflow to review every file changed on this branch against
CONTRIBUTING.md — one reviewer per file — then merge the findings into a
single deduplicated list ordered by severity
```
**Codebase-wide audit** — a staged *audit → fix → verify* pipeline:
```text theme={null}
Use a workflow to audit every SQL query in the reporting module for
missing pagination and N+1 patterns, fix each confirmed issue on its own
branch, and verify each fix with an EXPLAIN before and after
```
**Loop** — repeat until a check passes or progress stalls:
```text theme={null}
Use a workflow to get the flaky integration suite green: run it, fix
whatever failed, and repeat until it passes three consecutive runs or a
round fixes nothing new
```
## How a run works
1. **Devin writes the script** to a file and starts the run. Runs are auto-approved by default; to have Devin ask for your approval before each run, turn off **Settings → Preferences → Auto-approve workflows**.
2. **The script runs on Devin's machine.** Workflow primitives are injected automatically — nothing to install or import.
3. **Each agent call spawns an agent** and waits for its structured output. By default that agent is an independent Devin session on its own VM.
4. **Progress streams into the session.** The workflow panel shows each phase, its agents, and their live status; you can open any agent's session from there.
5. **Results are recorded** against a run ID, which is what makes resuming possible.
The run happens in the background, so the session stays responsive — you can keep talking to Devin while it executes, ask for a progress summary, or ask it to stop the run. Stopping cancels the script and puts the remaining child sessions to sleep; everything already recorded stays resumable.
## Authoring model
The script is plain Python. Devin writes it, but it helps to know the shape when you review one:
| Primitive | What it does |
| -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `register_workflow(meta)` | Declares the workflow's name, description, and phases. Must be awaited before any agents run. |
| `agent(prompt, phase=..., schema=...)` | Runs one agent and returns its structured output as a dict. |
| `pipeline(items, stage1, stage2, ...)` | Runs each item through the stages independently — no barrier between stages, so item A can be in stage 3 while item B is still in stage 1. |
| `parallel([...])` | Runs async callables concurrently and waits for all of them. Use only where a stage genuinely needs every prior result, such as a merge or dedup step. |
| `log("message")` | Writes a progress line that is visible while the run is still executing. |
Each `agent()` call takes a JSON Schema and returns a dict shaped by it, which is how one stage's findings become the next stage's prompt. Keep schemas small and flat.
### Example
An audit-then-fix pipeline across three modules:
```python theme={null}
import asyncio
import json
REPO = "github.com/acme/api"
MODULES = ["auth", "billing", "search"]
META = {
"name": "error-handling-audit",
"description": "Audit and fix error-handling bugs across api modules",
"phases": [
{"title": "analyze", "detail": "audit each module for error-handling bugs"},
{"title": "fix", "detail": "fix confirmed issues and push a branch"},
],
}
FINDINGS_SCHEMA = {
"type": "object",
"properties": {
"module": {"type": "string"},
"issues": {"type": "array", "items": {"type": "string"}},
},
"required": ["module", "issues"],
}
FIX_SCHEMA = {
"type": "object",
"properties": {"branch": {"type": "string"}, "summary": {"type": "string"}},
"required": ["branch", "summary"],
}
async def analyze(module):
return await agent(
f"In {REPO}, audit the '{module}' module for error-handling bugs. "
"Report each issue as a one-line string.",
phase="analyze",
schema=FINDINGS_SCHEMA,
label=f"analyze-{module}",
)
async def fix(findings):
if not findings["issues"]:
return None
return await agent(
f"In {REPO}, fix these issues in the '{findings['module']}' module:\n"
+ json.dumps(findings["issues"], sort_keys=True)
+ "\nPush your work to a new git branch (do not open a PR) and "
"report the branch name and a one-line summary.",
phase="fix",
schema=FIX_SCHEMA,
label=f"fix-{findings['module']}",
)
async def main():
await register_workflow(META)
results = await pipeline(MODULES, analyze, fix)
for module, result in zip(MODULES, results):
log(f"{module}: {result['branch'] if result else 'no fix needed/failed'}")
asyncio.run(main())
```
## Where agents run
Each agent runs on its own VM by default, and can instead be pinned to the orchestrating session's machine.
A full child Devin session with its own machine, repo clones, and [environment](/onboard-devin/environment/blueprints). It cannot see the orchestrating session's files, so code handoffs go through git branches: each agent pushes a branch and reports the branch name, and later stages read it from the structured output.
The agent runs on the orchestrating session's machine and shares its working tree, including uncommitted changes — no git handoff needed. Use it when agents must read or edit the current working tree, or when the repo only exists on that machine.
Shared-VM agents compete with the session for CPU, memory, and disk, and run at a lower concurrency cap. Because they share one working tree with no isolation, parallel writers must be given strictly non-overlapping files or directories.
Agents can also be pinned to a specific Devin mode — for example the cheaper Devin Lite for per-item classification in a wide fan-out.
## Determinism and resuming
A workflow script is re-executed from the top when a run resumes, and each agent call is keyed by a hash of its prompt, schema, and execution settings. Everything that already completed replays from its recorded result; the rest runs fresh with new sessions.
That only works if the script makes the same calls every time. Workflow logic and prompts must not depend on the current time or date, randomness, generated IDs, environment variables, filesystem state, or network responses. Anything that needs to inspect the outside world belongs inside an `agent()` call, whose recorded output the rest of the script consumes.
Two consequences worth knowing:
* **Editing a prompt re-runs that agent** and everything downstream of it, while untouched earlier agents still replay.
* **A run that timed out or was interrupted picks up where it left off** when resumed with its run ID. The default and maximum budget for a run is seven days.
If an agent fails — its session died or it produced no valid structured output — the script decides what happens: skip the item, substitute a default, retry, or fail the run. A resumed run retries failed agents with new sessions.
## Cost
Every agent in a workflow is a Devin session, so one run can consume far more ACUs than doing the same task in a single session. Before pointing a workflow at an entire repo, run it on a slice — one directory, three modules, a narrower question — and check the ACU usage of the agents in the workflow panel. Asking for a cheaper [mode](/essential-guidelines/when-to-use-devin) on high-volume stages, such as per-item classification, also keeps a wide fan-out affordable.
## Saving a workflow for reuse
Once a workflow works, it can be committed to your repo as a [skill](/product-guides/skills): a `workflow.py` next to a `SKILL.md` describing when to use it. Devin then discovers and reruns it on future tasks instead of authoring a new script. Ask Devin to save a workflow and it will create the necessary files for you.
## Related
* [Advanced Capabilities](/work-with-devin/advanced-capabilities) — orchestrating managed Devins directly
* [Skills](/product-guides/skills) — saving reusable procedures, including workflows, in your repos
* [Devin MCP](/work-with-devin/devin-mcp) — creating and monitoring sessions programmatically
# Devin MCP servers and marketplace
Source: https://docs.devin.ai/work-with-devin/mcp
Connect Devin to external tools with MCP servers: install plugins from the marketplace or add custom STDIO, SSE, or HTTP servers.
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
MCP servers are managed on the [**Customize → MCPs**](https://app.devin.ai/customize?tab=mcps) tab, alongside plugins, skills, hooks, and rules, at the personal, organization, or enterprise scope. (The older Settings → Connections → MCP servers page redirects there.)
The recommended way to add an integration is to install its **plugin** from the plugin marketplace (**Browse marketplace** on the Customize page): most official plugins are a single MCP server, often with skills that teach Devin how to use it, and installing one at the organization scope makes it available to everyone. The legacy MCP marketplace is still available from the MCPs tab. See the [Plugins guide](/product-guides/plugins#mcps) for how plugin MCPs, connections, and scopes work.
To connect an MCP supplied by a plugin:
1. Install the plugin at the **Personal**, **Organization**, or **Enterprise** scope where you want to use it.
2. Wait for indexing to read its MCP configuration. If setup remains unavailable, follow [Resolve indexing issues](/product-guides/plugins#resolve-indexing-issues).
3. Open the plugin's MCP from **Customize → MCPs**, choose **Connect**, and supply the required credentials or complete OAuth. Connecting a shared MCP requires the permissions to manage MCPs at that scope.
4. Check its connection status before using it in a new session. Plugin installation alone does not authorize access to the external service.
For CLI plugin MCPs, follow the [CLI MCP configuration guide](/cli/extensibility/mcp/configuration); use `devin mcp login` for OAuth servers running locally.
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 **Add custom MCP** on the Customize → MCPs tab. 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 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 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 [Customize > MCPs](https://app.devin.ai/customize?tab=mcps).
2. Open **Add MCP** and choose **Add custom MCP**.
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. Verify the server from its configuration page. How you verify depends on the transport:
* **SSE or HTTP**: Click **Test tools**. Devin connects to your server and attempts to list its available tools.
* **STDIO**: **Test tools** is disabled, because STDIO servers can only be tested inside a session. Click **Use MCP** to start a Devin session that exercises the server's tools.
**Test tools** and **Use MCP** are unavailable until you save your configuration. If **Test tools** 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**: Save the configuration, then use **Connect** in **Customize → MCPs** to complete authorization. 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 to the redirect URI allowlist in your OAuth application's settings. Copy the exact value from the **OAuth callback URL** field in that section. On app.devin.ai it is `https://api.devin.ai/mcp/oauth/callback`; dedicated and custom-domain deployments use a different API origin, so always use the value shown by your deployment.
* **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
### An installed plugin's MCP is missing or cannot be connected
* Check the plugin's installation scope and indexing result in Customize. Missing or malformed MCP declarations must be fixed in the plugin source, then reindexed. See [Resolve indexing issues](/product-guides/plugins#resolve-indexing-issues).
* Once its MCP configuration is indexed, open the MCP's connection settings and complete any required credentials or OAuth authorization. Successful indexing does not verify the external service connection.
* If you cannot connect a shared organization or enterprise MCP, ask an admin with the appropriate MCP management permissions. For an MCP with **Personal** OAuth access, each member must connect their own account.
### "Test tools" fails
**Test tools** is available only for SSE and HTTP servers. To troubleshoot a STDIO server, see [A STDIO server fails in a session](#a-stdio-server-fails-in-a-session).
| 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) | The server returned an error or crashed while listing tools | Check the server's logs and confirm that any credentials referenced in the URL or headers are set |
### A STDIO server fails in a session
After clicking **Use MCP**, review the session for errors starting the server or listing its tools:
* Verify the command exists and runs locally, and that its dependencies are available in Devin's environment.
* Check that all required environment 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 as a redirect URI — many providers reject the OAuth flow if this URL isn't allowlisted. Copy the exact value from the **OAuth callback URL** field under the MCP's OAuth credentials rather than assuming `https://api.devin.ai/mcp/oauth/callback`, which only applies to app.devin.ai.
* For a shared organization or enterprise connection, contact your admin if you lack the required MCP management permissions. With **Personal** access, each member connects their own account.
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
Find the service through **Browse marketplace** in **Customize → MCPs** and follow its installation prompts. For a plugin-supplied MCP, wait for indexing, then open its connection settings and choose **Connect**.
Complete OAuth before starting a session. Use a service account for shared **Organization** access; with **Personal** access, each member connects their own account. Installation and authorization are separate steps.
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
The marketplace includes API-key and OAuth connections for the official Datadog remote MCP server. Select your Datadog site/region from the options offered by the connection.
* **Datadog (API key)** uses `DD-API-KEY` and `DD-APPLICATION-KEY` headers.
* **Datadog (OAuth)** prompts you to authorize your Datadog account through OAuth.
Follow the setup prompts for the entry you selected, then check its connection status in **Customize → MCPs**.
[Documentation](https://docs.datadoghq.com/bits_ai/mcp_server/)
### Slack
This is the official Slack remote MCP server. Install it from the marketplace, then choose **Connect** in **Customize → MCPs** to authorize your Slack account through 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. Install it from the marketplace, then choose **Connect** in **Customize → MCPs** to authorize your Figma account through 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.devin.ai/work-with-devin/security-swarm
Use Devin Security Swarm to find, triage, and remediate security vulnerabilities across your repositories with code scans and automated fixes
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. Optionally select a [scan profile](#scan-profiles) and a [scan effort](#scan-effort). Leaving the profile blank uses Security Swarm's built-in security scan.
4. Make sure **Interactive mode** is enabled.
5. Click **Run Scan**.
6. When the proposed [threat model](#interactive-mode) is ready, review it and either click **Looks good, start scanning** or provide feedback.
7. As findings appear, review the evidence and [act on the findings](#act-on-a-finding) that need attention.
The New Scan sheet offers other [scan modes](#choose-a-scan-mode) for scanning several repositories at once or importing findings from an existing scanner.
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.
Use **Validate severities** to choose the lowest severity that Devin validates in a sandbox. Only findings at or above that severity start a validation session; by default, critical, high, and medium findings are validated. Raise the threshold to critical or high to spend validation effort only on the findings that matter most.
```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.
### Ingestion profiles
A profile's mode is fixed when you create it. **Discover** profiles (the default) analyze your code to find new issues and use the guidance fields above. **Ingest** profiles import findings you already have from another scanner or report, and replace the scope and threat model inputs with two guidance fields:
* **Ingestion source** — where the existing findings live and how Devin should fetch them. For example, fetch open alerts from GitHub code scanning through its REST API, or read a Semgrep report committed at `reports/semgrep.json`. Reference credentials by organization secret name rather than pasting a token.
* **Post-ingestion triage** — how Devin should triage the imported findings: what to dismiss, what to reprioritize, and what to treat as a duplicate. For example, dismiss findings in test fixtures and treat findings with the same rule ID and file as duplicates.
See [Ingest existing findings](#ingest-existing-findings) for how to run a scan with an ingestion profile. The **Profiles** tab can be filtered by scan type and by mode (Discover or Ingest).
### 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
### Choose a scan mode
The New Scan sheet offers four scan modes:
| Mode | What it does | Best for |
| ------------------- | --------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Single repo** | One scan of one repository. | A focused scan of one codebase. |
| **Multi-repo** | One scan across up to 200 repositories that Devin analyzes together. | Microservices or repositories that call each other, so Devin can catch issues that span repository boundaries. Findings can be filtered by repository. |
| **Bulk scan** | A separate, independent scan for every matching repository. | Covering a whole organization at once. Repositories are not analyzed together. |
| **Ingest findings** | Imports findings from your existing tooling or reports instead of discovering new ones. | Bringing results from another scanner into Devin for triage and remediation. See [Ingest existing findings](#ingest-existing-findings). |
Interactive mode is available for single-repo and multi-repo security scans. It is enabled by default for a single-repo scan when your organization has not run a scan yet.
### Scan effort
Every scan runs at one of two effort levels, selected under **Scan effort** when you start it:
* **Normal** (default) — a faster scan that uses larger investigation batches.
* **Deep** — traces each finding further through the codebase for maximum thoroughness, at a higher cost and longer runtime.
Use Normal for routine and incremental scans, and Deep for a first scan of a high-risk codebase or a periodic in-depth review. The effort a completed scan ran with is shown in its header.
### Bulk scan an organization
Use **Bulk scan** in the New Scan sheet to queue a separate scan for every matching repository:
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.
### Ingest existing findings
Use **Ingest findings** to bring results from another scanner into Security Swarm so you can triage, validate, and remediate them alongside Devin's own findings:
1. Select one or more repositories the findings belong to.
2. Select an [ingestion profile](#ingestion-profiles). The profile tells Devin where the findings live and how to triage them after import.
3. Optionally attach up to 10 reports or exports (for example SARIF, CSV, or PDF files) for Devin to read findings from. If the profile's ingestion source already points at an API or a file in the repository, no attachment is needed.
4. Optionally enable **Interactive mode**. After importing, Devin pauses so you can review what was ingested, including possible duplicates, and request corrections before it continues.
5. Choose a [scan effort](#scan-effort) and click **Run Scan**.
Imported findings appear on the scan page like any other finding, so you can assign them to Devin, adjust them, or change their status. The scans list can be filtered by mode to show only **Discover** or only **Ingest** scans.
Uploading attachments goes through the attachments API, so ingesting from uploaded files also requires **Use Devin sessions**. Ingestion scans can also be started from the [API](/api-reference/v3/code-scans/organizations-code-scans-start-ingestion).
### 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, or disabling its schedule, or by clicking **Scan now** to run it immediately.
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.
Each full or incremental run is recorded in the scan's [scan history](#scan-history).
### Start scans from Automations
[Automations](/product-guides/automations) include a **Code scan** agent type for scans that should run on a schedule or in response to an event. Instead of starting a Devin session with a prompt, the automation starts the scan directly. Choose one of two actions:
* **Start code scan** — starts a fresh scan of the configured repository or repositories, scan type, profile, and effort each time the automation fires.
* **Scan new commits** — extends an existing scan with an incremental run covering the commits added since its last completed run. The scan must already have a completed run.
Auto Scan is a preconfigured automation of the second kind. Use the Automations page when you want other triggers, such as a webhook, or when you want to manage all scheduled scans in one place.
You can also start a scan from a session's composer with the `/scan` command. For performance, test coverage, dead code, and other non-security scans, see [Code Scans](/work-with-devin/code-scans).
## 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.
* **Scan history** — view every run of the scan. See [Scan history](#scan-history).
* **Change profile** — switch the profile used by future runs. See [Change a scan's profile](#change-a-scans-profile).
* **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). The scans list on the Security page can be filtered by status, pull request state, and scan mode (Discover or Ingest).
### Scan history
Open **Scan history** on a scan to see every time it has run, newest first. Each run shows whether it was a **Full scan** or **Incremental**, its status, the effort and profile it used, the ACUs it consumed, and a link to its Devin session. Use it to confirm that Auto Scan is running as scheduled and to compare the cost of full and incremental runs.
### Change a scan's profile
Click **Change profile** on a completed scan to select a different profile. The new profile applies to future runs of the scan, including Auto Scan and **Scan new commits**; completed runs and their findings are unaffected. You cannot change the profile while a scan is running. Changing a profile requires **Use code scans**.
### 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).
The same code scan permissions gate the Code Scans API (API calls do not additionally require session permission, except that uploading scanner reports for ingestion scans goes through the attachments API, which needs **Use Devin sessions**). Service users or personal access tokens with **Use code scans** can [start scans](/api-reference/v3/code-scans/organizations-code-scans-start), [start ingestion scans](/api-reference/v3/code-scans/organizations-code-scans-start-ingestion), and [remediate findings](/api-reference/v3/code-scans/organizations-code-scans-remediate); **View code scans** covers [listing scans](/api-reference/v3/code-scans/organizations-code-scans-list), [profiles](/api-reference/v3/code-scans/organizations-code-scans-profiles) and [their guidance](/api-reference/v3/code-scans/organizations-code-scans-profile), [findings](/api-reference/v3/code-scans/organizations-code-scans-findings), and [metrics](/api-reference/v3/code-scans/organizations-code-scans-metrics). See [Triggering Code Scans via the Devin API](/api-reference/v3/code-scans/triggering-code-scans) for the end-to-end flow.
## 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.devin.ai/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 > Devin > Commands](https://app.devin.ai/settings/devin). 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.devin.ai/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.devin.ai/work-with-devin/testing-and-recordings
How Devin tests your changes end-to-end after creating a PR and sends you video recordings as proof that they work
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.
To have Devin run testing after PR creation without needing to click the button, turn on **Pre-approve testing** in [Settings > Preferences](https://app.devin.ai/settings/preferences#pre-approve-testing). Devin will then test the app without asking for approval first.
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.
# Devin voice mode
Source: https://docs.devin.ai/work-with-devin/voice-mode
Use Devin voice mode to talk through ideas, pressure-test an approach, and hand off work. Learn how to start and control a call.
With voice mode, you can talk naturally with Devin to explore ideas, pressure-test approaches, and hand off work while you’re away from your keyboard.
## Start a call
Click the voice call button beside the message box on the home page in Agent mode or in an existing session, then allow microphone access. Any message you’ve typed is sent when you start the call.
## During a call
* **Mute microphone** pauses your microphone. Click **Unmute microphone** to speak again.
* Hold **Space** to talk while muted when you’re not typing.
* **Silence Devin** turns off Devin’s audio without muting your microphone. Click **Unsilence Devin** to hear Devin again.
* **End voice call** hangs up.
You can navigate within Devin while the call stays connected. Your conversation appears in the session history.
## Tips
* Don't be afraid to interrupt Devin's work, ask questions and clarify your thoughts as you have them.
* Feel free to interrupt Devin while it is talking.
* If you have preferences for how Devin should speak (e.g. speak faster or slower, communication style) just ask!
# Changelog (Stable)
Source: https://docs.devin.ai/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.
### Added
* Run Devin Cloud sessions from the CLI with `devin --cloud` or `/cloud`
* `/handoff` and `/pickup` bring a cloud session's pull request branch into a local session, offering to select a PR or clone its repository when needed.
* Use `devin ssh` or `/ssh` to connect to a Devin Cloud VM.
* ACP clients can select Devin models, thinking effort, and speed through session configuration controls.
* Agent shell commands expose `AI_AGENT=devin__agent` unless another agent already set that variable.
* Export agent events and metrics to an OpenTelemetry collector using the `otel` block in the user config or standard `OTEL_EXPORTER_OTLP_*` variables.
* Optional organization and enterprise plugins installed through Customize now load in the CLI, subject to the current organization.
### Changed
* ACP authentication can answer from cached team settings while account details refresh in the background, so returning users can start without waiting on those network calls.
* ACP reports a structured, retryable error when an agent's communication channel closes, allowing clients to reconnect rather than retry a prompt.
* In Bypass Permissions mode, file edits no longer open an editor review.
* `/loop` now runs each review in a fresh read-only subagent without clearing the working agent's conversation or session history.
* Rules are discovered recursively under `.devin/rules/` and `.windsurf/rules/`.
* Refreshing git plugins reuses unchanged refs and shared downloads, and refreshes stale plugins concurrently.
* Session-lock errors identify the process holding the lock, including over ACP.
### Fixed
* ACP clients can use MCP servers supplied in `session/new` or `session/load`, including HTTP and SSE servers; plugin operations also report their failure reasons instead of a generic internal error.
* Custom subagent profiles and skills can grant the `write` tool using `allowed-tools`, and permission rules recognize it.
* Cursor rules with string-valued `globs` load correctly.
* Esc in an expanded model picker returns to the family row, and the Lead list offers every lead even when the current configuration has no pairing.
* PowerShell commands with literal variable assignments prompt for approval of the script rather than a hashtable key; long script paths in allow options remain identifiable.
* Resizing terminals with long transcripts no longer causes a redraw storm, and wide Markdown tables no longer clip their last column.
* Skills from Claude and Windsurf directories report the correct provider; skills, rules, and custom subagents load in a stable order.
* On Windows, PowerShell command output no longer intermittently comes back empty or includes the echoed command, and restarting `devin forward` on the same port waits for the old forward to release it.
* Interrupting an agent parks running subagents for the next message rather than killing them, except for a running Fusion sidekick.
* Subagents start with global and workspace always-on rules, and the Subagents, Shells, and Cloud agents trays scroll when taller than the terminal.
* `/login` is hidden in cloud sessions so an API key cannot accidentally be sent as a cloud message. To switch accounts, use `devin auth login` and then `/clear`.
### Fixed
* A command deny such as `Exec(rm)` blocks the command even when a broader `ask` or `allow` rule covers the whole tool.
* `Exec(*)` in a permission rule matches every command.
### Changed
* GPT-6 Astra batches shell commands and file reads into fewer turns and prefers targeted commands over dumping whole files or running full test suites.
### Added
* New mode slash commands alongside `/ask` and `/plan`: `/code` returns to Code mode, `/smart` switches to Smart mode, and `/bypass` (alias `/bypass-permissions`) switches to Bypass Permissions. With a prompt they switch and then run it under the new mode.
* `/session-stats` now ends with a "by model" chart of the session's billing metric, with per-model totals
* Disable tools by name with `disabled_tools` in your user `config.json`, for example `"disabled_tools": ["webfetch", "web_search"]`.
* Set `agent.compaction_threshold_tokens` in the user config to trigger automatic compaction earlier than the context-window-based default.
* Added an `agent.codex_tools` setting (off by default) enabling GPT models to use the Codex tool set — shell commands for reading and searching, `apply_patch` for edits
* Beta: `shell.exec_shell` (`bash`/`zsh`/`fish`/`pwsh`) selects the shell the agent's `exec` tool uses, and the agent can now pick a shell per command instead of always getting the machine's default.
* `Ctrl+Y` pastes the text most recently deleted with `Ctrl+U`, `Ctrl+K`, `Ctrl+W`, `Alt+D`, or `Alt+Backspace` back at the cursor, with a footer hint until it is yanked back. Rebind it via `editor.yank`.
* Refusal fallback: when a provider refuses a request under its usage policy, Devin can switch to another model and retry the turn. Set `DEVIN_REFUSAL_FALLBACK` to a comma-separated list of models (or pass `--refusal-fallback` to `devin acp`); disabled unless configured.
* `PreToolUse` hooks receive a `tool_provenance` object identifying the skill or MCP server behind the call, and the config file or plugin that declared it.
* Terminals without kitty keyboard protocol support (e.g. Apple Terminal) see an "Alt+Enter for multiline prompts" tip.
* Skill list and search can target active plugin skills without changing their existing project-path behavior.
### Changed
* Model families remember the last configuration you selected, including reasoning level, effort, and fast settings.
* Shell commands that only read, search, or list files are titled like the matching tool call ("Read lines 10-20 in src/main.rs", "Searched for foo in src") and render as compact title-only cards when they succeed.
* Large diff previews show the last 50 diff lines behind a `[... N lines truncated ...]` marker so big edits no longer slow down rendering.
* Unchanged context lines in diffs have a subtle gray background, and in-progress tools use yellow hollow indicators.
* Reopening a local session streams the stored conversation to the client message by message and no longer keeps a second copy in memory, roughly halving the memory a large reopened session uses.
* `--model` now applies when resuming with `-c`/`--continue` or `-r`/`--resume`, switching the rest of the conversation to that model instead of being ignored.
* More specific command permission allows (e.g. allowing `git status`) can override a broader ask rule at the same configuration level.
* Usage-limit warnings follow the enterprise's configured request action, linking to its own intake tool or showing its guidance; enterprises without one keep the "Request more usage" link.
* `devin plugins install` on a Claude Code plugin *marketplace* now recognizes it and offers to install a plugin (with a picker for multi-plugin marketplaces) instead of failing to read a manifest, and a repository with no manifest at any supported location fails with "no plugin manifest found".
* MCP OAuth logins advertise `http://localhost:8765/callback` as the redirect URI (previously `http://127.0.0.1:8765/auth/callback`). If your identity provider allowlists Devin's redirect URI by exact string, update it to the new value.
* The startup workspace trust prompt, login selection screen, and login confirmations were reworked for clearer navigation and consistent Devin branding.
### Fixed
* The CLI no longer shows Devin as idle while a background subagent is still running: the turn stays active until it finishes, so the usual interrupt (esc esc or ctrl+c) cancels it, and its tool cards show live instead of being dumped into your next turn.
* Smart mode is never less permissive than Code mode: allow rules and auto-approved workspace edits are honored identically. Sensitive paths still always prompt, with the session's plan files exempt. Starting or resuming in Smart mode also no longer prints a spurious "Smart permission mode is not available" warning.
* Resuming a session and choosing its original directory no longer hangs when that directory has been deleted, and listing local sessions no longer fails entirely when a single stored row is unreadable.
* Server-side model errors show the Devin API's own explanation instead of a generic "Connection error", and server rate limits are no longer labeled "Quota exhausted".
* `cd`-prefixed commands whose target can resolve differently at runtime keep the fail-closed permission behavior, and on Windows a PowerShell command starting with a parenthesized expression offers the real command name to allow.
* `web_search` can now be used as a tool name in `permissions.deny` / `permissions.ask` / `permissions.allow`; previously it was rejected and web searches were always auto-approved.
* Skills under `.cursor/skills/` and `~/.cursor/skills/` are auto-loaded like `.claude/skills/`, skills reachable through more than one path (e.g. symlinked directories) load once instead of per alias, and skills dropped from context by compaction are discovered again when the agent next touches their trigger paths.
* Invalid saved plugin entries no longer prevent unrelated plugins from loading, plugins required only by a forbidden plugin no longer activate, and git plugin sources with `@` in repository paths keep a consistent identity across HTTPS and SSH URLs.
* `devin mcp login` succeeds against authorization servers that advertise RFC 9207 issuer identification, MCP connection setup times out instead of leaving later requests waiting on a stalled server, and MCP prompt commands no longer generate background requests every 15 seconds per conversation.
* `/compact` shows only a spinner until it finishes and queues prompts typed during compaction, `/fast ` runs the prompt after switching models, long `/btw` answers scroll with Up/Down, and you can revert the first prompt while Devin is active.
* Reduced the risk of local session database corruption with upstream SQLite fixes.
* Shared conversation titles show file mention names instead of local file paths.
* Debug exports preserve linked foreground and background subagent chains so trajectory viewers can open each agent's trace, and `/debug` links directly to the upload page for viewing the export.
* Removed the `e` / Shift+Enter "select+type" shortcut in the question tool. Explanations typed this way were silently dropped; use the "Other" option for custom text.
### Changed
* Reduced Devin's reliance on subagents.
* Added a background cache-refresh task to improve token efficiency during long-running tasks.
### Fixed
* Repaired a regression connecting to MCP servers via Streamable HTTP that was introduced in v3000.6.11
### Fixed
* MCP connection setup now times out instead of leaving later requests waiting on a stalled server, so a retry can establish a fresh connection.
* `devin worker start` no longer fails with `HTTP 403 Forbidden` when bootstrapping a personal outpost from an enterprise CLI login.
### Fixed
* MCP registry fetches now use the platform certificate store and configured proxy settings, so custom registries load correctly on networks with a corporate proxy or TLS inspection, and registry-allowed servers are no longer incorrectly blocked.
* Reduced rendering CPU usage for long text, code blocks, and tables in the terminal, including when only the spinner changes.
* Reduced allocation overhead when drawing terminal content.
### Fixed
* Read-only commands prefixed with `cd`, such as `cd /repo && find .`, now resolve relative paths against the target directory for permissions. Ambiguous paths and output redirects continue to fail closed.
* The CLI no longer grows in memory on every screen redraw while waiting on an open prompt or a long-running turn.
* A `pre_tool` hook that blocks a tool call now returns its reason to the agent and lets the turn and sibling tool calls continue.
* Windows shell sessions no longer risk hanging indefinitely when closed immediately after startup.
### Added
* New `devin rm ` deletes a session, with confirmation by default and `--force` for non-interactive use; deletion is refused while another Devin instance has the session open.
* New `devin desktop` shortcut opens Devin Desktop if installed, and a bare path such as `devin .` opens Devin Desktop on that path.
* New `devin doctor` command checks custom subagent profiles for incorrect frontmatter.
* New `/recap` command catches you up on the session with a short agent-generated summary of what was worked on, key decisions, and where things stand.
* New `/rename ` renames the current session.
* New Alt+P shortcut toggles Plan mode without clearing the input.
* `/handoff` now asks which OS the cloud session should continue in when your organization has more than one platform available, instead of silently reusing the last cloud session's environment.
* Ask and Plan modes can now use the read-only `webfetch` and `notebook_read` tools for research.
* Plugins are now compatible with the [Agent Plugins 1.0.0](https://github.com/agentplugins/agent-plugins-spec) format.
* Plan mode writes plans to a file so they always have a heading and summary paragraph.
* The subagent tray and detail view show which model a subagent is running on when it differs from the parent's model.
* Accounts billed in credits now see a model's credit multiplier in the model selector (e.g. `1.25 credits / message`) instead of only a relative cost label.
* The input footer shows a "ctrl+v to paste image in clipboard" hint while an image is on the system clipboard.
### Changed
* Instant slash commands (`/status`, `/context`, `/fast`, `/session-stats`, `/help`, etc.) now run immediately while the agent is working instead of queueing until the turn finishes, render their replies in scrollback instantly rather than through the typewriter, and pair each reply with its own command.
* Unknown slash commands now fail instantly with `Unknown command: /notacommand. Use /help to see available commands.`
* `/model`, `/models`, the model keyboard shortcuts, and the footer model picker now apply while Devin is working, so the next request uses the selected model.
* `/btw` now opens a side-chat panel that runs in parallel with the main agent: questions are answered from the conversation's context while the agent keeps working.
* `/usage` shows a richer panel: daily/weekly quota progress bars with reset times, an extra usage balance line when present, and more info on the current session.
* The session picker (`devin -r`, `/resume`, `devin ls`) shows all sessions by default with the current directory's sessions sorted to the top; Alt+G narrows to the current directory.
* The background shells tray (Ctrl+B) lists all running background commands.
* Command card titles show the meaningful command instead of the first shell token, skipping `cd`, environment prefixes, and wrappers like `sudo`/`env`
* Queued messages render in a distinct "N queued" section above the input box with `↑ edit` / `↵ send now` hints.
* Faster session startup, especially in large repositories with many rule and skill files.
* On Unix, cancelling or timing out a shell command now sends SIGTERM to the process group first and SIGKILL only after a 5-second grace period.
* Read-only git command detection is now shared across bash, PowerShell, and smart mode.
* `/bug` opens the bug submitter when run without a description, rejects submissions from outdated CLI versions, and shows a checklist receipt of what was sent (with the local zip path for zero-data-retention accounts).
* Presentation polish across the REPL: agent output is inset by one column with tighter tool cards, code blocks are indented two cells with balanced padding, inline code has padded backgrounds, `/help` aligns and dims descriptions, the interrupt hint turns a warning color, and the first-run welcome screen is a compact tips card.
* Broader Claude plugin compatibility: hooks are also loaded from `hooks/hooks.json`, hook commands additionally receive `CLAUDE_PROJECT_DIR` and `CLAUDE_PLUGIN_ROOT`, and subagent profiles accept the `tools` frontmatter field as an alias for `allowed-tools`.
* The model picker has been redesigned for improved price transparency and more intuitive navigation.
### Fixed
* Hitting a monthly usage limit now shows a "Usage limit reached" alert with a clickable "Request more usage" link instead of a raw permission-denied error, and the "Quota exhausted" alert links to usage settings.
* Background shells keep streaming live output to their command card after the turn ends — including after an interruption — and show the full output on completion instead of a 1000-character preview.
* Command cards carry the full retained terminal scrollback (up to \~3500 lines), show a scrollable \~100-line window while streaming, elide the middle of very large output with a marker instead of showing only a tail, and no longer lose chunks from commands that emit fast bursts.
* Shell commands with endless output no longer grow memory without bound.
* `--continue` now continues the most recent session in the current directory that is not already open in another process, instead of failing on a locked session.
* A single invalid value in `config.json` no longer discards all user settings.
* Permission rules now match correctly when a workspace, config, or granted directory name contains glob metacharacters such as `[`, `]`, `{`, `}`, `*`, or `?`.
* `SessionEnd` lifecycle hooks now run when a session ends, with a `reason` matching Claude Code's vocabulary.
* `Stop` hooks now receive `last_assistant_message` in their stdin payload, so they can read the agent's final response without parsing a transcript. Hooks contributed by a plugin also get `DEVIN_PLUGIN_ROOT`.
* Hooks from a second workspace directory now run in that workspace, and `DEVIN_PROJECT_DIR` always points at the hook's project root.
* Skills, rules, hooks, and subagent profiles that come from an installed plugin now appear in the Skills, Rules, Hooks, and Subagents lists, labeled with the plugin's name.
* Invoking a skill passes the whole `SKILL.md` to the model instead of truncating it to the tool-result budget, and `$ARGUMENTS` / `$1`–`$9` placeholders are interpolated with the arguments passed to `/skill-name`.
* Skills discovered mid-session are listed again after context compaction instead of disappearing for the rest of the session.
* Ask and Plan modes can use web search for read-only research when the tool is available.
* Pressing `x` on the tray's Subagents tab kills only the selected subagent instead of cancelling the whole turn.
* An interrupted auto-update can no longer leave the installation broken with `current` pointing at a missing version directory; `devin update` also repairs an already-dangling installation.
* Windows: multi-line pastes no longer split into separate prompts, `pty_for_noninteractive_exec` no longer makes every non-interactive command hang, cancelled commands kill the whole process tree, and Chrome discovery checks per-user installations.
* Terminal rendering fixes: multiline paste works in terminals without bracketed paste, selection lists scroll instead of overflowing short terminals, searchable pickers move the highlight to the adjacent visible row, wrapped inline code no longer leaves a stray highlighted cell, the live area flickers less when it resizes, streaming tool-call arguments animate smoothly again, and sending queued messages no longer shows a spurious cancellation prompt.
### 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.
* `/share` no longer uploads a conversation into a specific organization. Shared conversations are scoped to your account, so the link works for everyone in the account — including enterprise accounts — without choosing an organization first.
### Fixed
* Refused `/share` requests now report the server's actual reason, such as conversation sharing being disabled, instead of suggesting you log in again.
* 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
# Controls
Source: https://docs.devin.ai/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.
* **App Deploys** - The Devin Local agent does not support app deploys.
* **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.
Conversation sharing is also supported. In Devin Desktop, choose **Share conversation** from the actions menu below a completed turn; in Devin CLI or another ACP client, run `/share`. The agent uploads a sanitized transcript (secrets redacted, system prompts and tool definitions dropped) and returns a link to share with your team. Sharing is only offered when your organization allows conversation sharing, you are signed in with a Devin account (not a Windsurf-only account), and the client supports sharing.
### 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
The organization's conversation sharing control is honored: when sharing is disabled for the organization, the Devin Local agent does not offer **Share conversation** or `/share`.
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.
* **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.devin.ai/cli/enterprise/devin-auth
Authenticate to Devin CLI with your existing Devin account, and use custom roles with the Use Devin CLI permission to control enterprise access.
## 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 > Membership** and select the **Roles** tab
2. Click **Create role**, then select **Create for enterprise** or **Create for organizations**
3. Provide a descriptive name (e.g., "Devin CLI User")
4. Select the **Use Devin CLI** permission
5. Click **Save changes**
### Assigning the Role
* **Enterprise admins** or users with the **Manage Account Membership** permission can assign account-level roles in the **Members** tab of **Enterprise Settings > Membership**
* **Organization admins** or users with the **Manage Organization Membership** permission can assign organization-level roles from that organization's **Settings > Membership** 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.devin.ai/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
# Devin CLI Team Settings
Source: https://docs.devin.ai/cli/enterprise/team-settings
Configure team-wide Devin CLI settings for your enterprise, including model allowlists, the default model, MCP servers, and web search.
## 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 → Devin Desktop** (`app.devin.ai/org/{orgName}/settings/desktop`). 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 at any time. The team default only applies until a user picks a model themselves: once they select a different model (via `/model` or the model picker), that choice is saved to their user config (`agent.model`) and used for their new sessions going forward — they are not reset to the team default each time. This is intentional: users expect new sessions to start on the model they last chose.
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/desktop`.
### 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.devin.ai/cli/enterprise/windsurf-auth
Authenticate to Devin CLI with your existing legacy Windsurf Enterprise account, including per-user CLI access requirements and billing.
## 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
3. Devin CLI access is enabled for your user
Being able to use Windsurf's agentic tools does not guarantee access to Devin CLI. CLI access is a separate per-user setting controlled by your admin: a user's individual setting takes precedence, and users without one follow your team's default CLI access policy, which may be disabled. If CLI access is disabled for you, `devin auth login` can still succeed, but Devin CLI requests fail with `CLI access is disabled for this user - ask your admin for access`.
Admins can enable or disable CLI access for individual users with the SCIM `cliActive` attribute (see [SSO & SCIM](/desktop/accounts/sso-scim)) or, where available, with the **Disable CLI Access** toggle when editing a user in the [Team Members dashboard](https://windsurf.com/team/members).
### 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
# Configuration
Source: https://docs.devin.ai/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.devin.ai/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.devin.ai/cli/extensibility/hooks/overview
Configure Devin CLI hooks to run shell commands or LLM prompts on lifecycle events, block or rewrite tool calls, and inject context.
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 exiting with code `2` (or by printing a `"decision": "block"` JSON object); any other non-zero exit code is logged as an error and does not block — see [Exit Codes](#exit-codes).
***
## 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.devin.ai/cli/extensibility/index
Customize and extend Devin CLI with rules, skills, plugins, subagents, MCP servers, and hooks, or import configuration from other tools.
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 (permissions, imports)
│ ├── config.local.json # Personal overrides (gitignored)
│ ├── mcp_config.json # Project MCP servers
│ ├── mcp_config.local.json # Personal MCP servers and secrets (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) |
| `.github/skills/` (GitHub Copilot) | Skills |
| `opencode.json` (OpenCode) | MCP servers |
| `.zed/settings.json` (Zed) | MCP servers |
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,
"copilot": true,
"opencode": true,
"zed": true
}
}
```
Set any provider to `false` to disable importing from it. See [Configuration Import](/cli/reference/configuration/read-config-from) for every provider key and the full list of source files.
# MCP Configuration
Source: https://docs.devin.ai/cli/extensibility/mcp/configuration
How to add, configure, authenticate, and troubleshoot MCP servers in Devin CLI, including stdio, Streamable HTTP, and SSE transports.
## 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 such as 404 or 405, the CLI falls back to SSE on the same URL. Authentication errors (a 401 or insufficient-scope 403 with a `WWW-Authenticate` challenge) don't trigger the fallback — they're reported directly so you can authenticate. 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 non-authentication 4xx errors such as 404 or 405 ([per spec](https://spec.modelcontextprotocol.io/specification/2025-03-26/basic/transports/#backwards-compatibility)); 401 and insufficient-scope 403 responses with a `WWW-Authenticate` challenge are reported directly so you can authenticate. 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 a non-authentication 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 non-authentication 4xx responses. Connection errors, timeouts, and 5xx responses are reported directly without attempting SSE. Authentication-required responses — a 401, or a 403 for insufficient scope, that carries a `WWW-Authenticate` challenge — are also reported directly, so you can run `devin mcp login ` (or grant the required scope) instead of seeing an SSE attempt. See [Auth required / OAuth errors with remote servers](#troubleshooting).
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.devin.ai/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
# Devin CLI plugins
Source: https://docs.devin.ai/cli/extensibility/plugins/overview
Install, author, and govern plugins in the Devin CLI: plugin format, devin plugins commands, the manifest, and inheritance levels.
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. This page covers plugins in the CLI; for the web app — the Customize
page, organization and enterprise scopes, indexing, and MCP connections — see
the [Plugins guide](/product-guides/plugins).
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) in local Devin
sessions (the CLI and Devin Desktop) where the plugin is installed. Plugin hooks are
currently **best effort and fail open** — if a hook fails to load or run,
the session continues without it — so don't rely on them for crucial
guardrails yet.
* **MCP servers** — plugins can provide optional
[MCP servers](/cli/extensibility/mcp/overview) that start with the session.
Their tools are available to Devin. In the CLI, authenticate a plugin's
OAuth server with [`devin mcp login`](/cli/extensibility/mcp/configuration#troubleshooting);
cloud sessions use the connection made in the web app (see
[MCPs](/product-guides/plugins#mcps)). 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. Reference secrets as `${NAME}`;
literal values written into the config are stripped.
### 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;
append `#path/to/plugin` when the plugin lives below the
repository root:
```bash theme={null}
# From GitHub
devin plugins install acme/review-tools
# A plugin in a subfolder of a repo
devin plugins install acme/plugins#plugins/review
# From any git host
devin plugins install https://gitlab.com/acme/review-tools.git
# From a local folder (great for authoring) — on this machine only, linked to the folder
devin plugins install --local ./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. By default `install` records the plugin in your personal manifest in
Devin Cloud, so the same plugins load on every machine you sign in to (and in
your cloud sessions). Pass `--local` to install on the current machine only.
A local folder can't be recorded in your personal manifest, so install one with
`--local`, which links it on this machine. Managing plugins requires being signed in (`devin auth login`);
an enterprise can disable CLI plugins for its members, in which case installed
plugins aren't applied.
***
## 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, hooks, rules, 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 from your personal plugins (auto-installed required plugins are left in place)
devin plugins remove review-tools
# Remove from this machine only (fails for plugins in your personal plugins)
devin plugins remove review-tools --local
# Drop plugin requirements from repos no longer on disk and garbage-collect unused plugin content
devin plugins prune
```
`remove --force` removes a plugin even if another plugin or a governance
manifest still requires it; a governance-required plugin is reinstalled on the
next session in the requiring scope, and the CLI warns which enterprise,
organization, or repository configuration still requires it.
Local-folder plugins are linked directly to their source folder, so edits are live:
`devin plugins install --local ./my-plugin` → edit `skills//SKILL.md` → changes
apply on the next session, no `update` needed.
If the CLI has the plugin but Customize shows missing or stale contents, see
[Resolve indexing issues](/product-guides/plugins#resolve-indexing-issues).
`devin plugins update` refreshes local plugin content; **Reindex plugins** in
Customize refreshes the web listing. An install made with `--local` stays on
this device.
***
## 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 |
| `{ "source": "github", "repo": "owner/repo", "sha": "3f2a9c1…" }` | pinned to an exact commit — never changes until you edit the entry |
| `{ "source": "github", "repo": "owner/repo", "ref": "v2" }` | tracks a branch or tag — re-resolved on every refresh |
`sha` and `ref` work with every object form (`github`, `url`, `git-subdir`) and are mutually exclusive: a `sha` is a pin, a `ref` floats. Without either, the source tracks the repository's default branch.
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
enterprise admin.
2. **Org** — an org-level managed manifest, layered below its enterprise (an
org can add to what its enterprise declares, but can't overrule it). Cloud
sessions use the manifest of the session's organization; the CLI and Devin
Desktop use the manifest of your primary organization.
3. **Repo** — the `requiredPlugins` / `optionalPlugins` / `forbiddenPlugins` in a
checkout's `.devin/config.json`, discovered by walking up from your working
directory (in cloud sessions, from each cloned repository).
4. **User** — plugins you install yourself with `devin plugins install`
(synced through your personal manifest) or `--local` on this machine.
The CLI fetches the enterprise, org, and personal manifests from Devin Cloud
when you sign in; admins manage the first two from the web app (see the
[Plugins guide](/product-guides/plugins#the-manifest)).
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.
* A **pin conflict** — two manifests pinning the same plugin to different
`sha`s — should be resolved by aligning the pins or leaving the pin to the
higher-authority level.
* When a managed manifest can't be fetched at session start, that level fails
**open**: nothing from it is installed and its forbids aren't enforced for
that session.
# Quickstart: team marketplace
Source: https://docs.devin.ai/cli/extensibility/plugins/quickstart
Set up a shared Devin plugin marketplace for your team with reusable skills, rules, hooks, MCP servers, and governance.
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 --local . # install the meta-plugin from your checkout, on this machine only
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 `/:`. (Without `--local`, `install` adds the plugin to your personal plugins in Devin Cloud, which is what you want once it's pushed to a repo.)
## 4. Distribute it to everyone
An org or enterprise admin installs the repo from [**Customize → Plugins**](https://app.devin.ai/customize): **Add plugin → From repository**, enter `your-org/your-marketplace`, and pick the organization or enterprise scope. That adds one required plugin to the scope's managed manifest:
```json theme={null}
{
"requiredPlugins": ["your-org/your-marketplace"]
}
```
Everyone in scope gets the baseline automatically in cloud sessions, the CLI, and Devin Desktop. A private repo works as-is: cloud fetches through your Git integration; CLI users fetch with their own git credentials, so they need access to the repo too. See the [Plugins guide](/product-guides/plugins) for scopes, indexing, and MCP connections.
## 5. Evolve and govern
* Merging to your marketplace repo's default branch **is** the release — new sessions pick it up automatically, and **Reindex plugins** in Customize refreshes what the page shows. See [how updates roll out](/product-guides/plugins#how-updates-roll-out); pin to a `sha` when you want to control updates.
* 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 (**Plugin settings → Edit manifest** in Customize) 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
* [Plugins guide](/product-guides/plugins) — the web app side: Customize, scopes, indexing, MCPs
# Rules & AGENTS.md
Source: https://docs.devin.ai/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.devin.ai/cli/extensibility/skills/creating-skills
Full reference for the Devin CLI SKILL.md format: frontmatter options, allowed-tools auto-approval, permissions, and subagent skills.
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
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 | none | Tools that are auto-approved (no permission prompt) while the skill runs. Does **not** restrict tool availability — see [Auto-Approved Tools](#auto-approved-tools). Not applied when the skill runs as a subagent |
| `permissions` | object | inherit | Permission overrides for this skill. Not applied when the skill runs as a subagent |
| `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
---
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.
When a skill runs as a subagent, its `allowed-tools` and `permissions` frontmatter are **not** applied. The subagent runs with the tool set of its profile — `subagent_general` has access to all tools. To limit which tools a subagent skill can use, define a [custom subagent profile](/cli/subagents#custom-subagents) with `allowed-tools` and reference it with `agent:` instead of `subagent: true`.
### `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. A custom profile's `allowed-tools` is a true restriction (unlisted tools are unavailable to the subagent), so this is the way to run a skill with a limited tool set.
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
---
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
---
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
`deny` is the way to hard-block a tool for an inline skill. Tool-name entries such as `exec` or `edit` block the entire tool, and `mcp__server__tool` patterns block MCP tools — see [Tool-Based Permissions](/cli/reference/permissions#tool-based-permissions).
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).
Skill permissions apply only when the skill runs inline. They are not applied when the skill runs as a subagent (`subagent: true` or `agent:`).
***
## Auto-Approved Tools
`allowed-tools` lists tools that are auto-approved while the skill runs, so the agent can use them without a permission prompt:
```yaml theme={null}
allowed-tools:
- read
- grep
- glob
```
Each entry is equivalent to a `permissions.allow` entry for that tool name. Available tool names: `read`, `edit`, `grep`, `glob`, `exec`
You can also auto-approve MCP tools:
```yaml theme={null}
allowed-tools:
- read
- mcp__github__list_issues
- mcp__github__create_issue
```
`allowed-tools` is **not** a restriction. Tools that are not listed remain available to the skill and go through the normal permission checks (prompting the user, or running without a prompt if the session's permissions already allow them). Omitting `allowed-tools` changes nothing about which tools the skill can use — it only means no tool is pre-approved.
To actually prevent a skill from using a tool:
* For inline skills, add the tool name to `permissions.deny` (see [Permissions](#permissions)).
* For subagent skills, define a [custom subagent profile](/cli/subagents#custom-subagents) with `allowed-tools` and run the skill with `agent: `. On a subagent profile, `allowed-tools` restricts the tool set; on a skill, it does not.
***
## 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.
Use `permissions.deny` (or a custom subagent profile) to block tools. `allowed-tools` only skips prompts.
Invoke your skill and iterate on the prompt until the output is what you want.
# Skills Overview
Source: https://docs.devin.ai/cli/extensibility/skills/overview
Skills are reusable SKILL.md prompts and workflows for Devin CLI, invoked with a slash command or by the agent, with their own permissions.
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.
Pre-approve the tools a skill needs so it runs without permission prompts.
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. Tools listed in the skill's `allowed-tools` (if specified) are auto-approved, so they run without a permission prompt. Unlisted tools stay available and go through the normal permission checks
3. The skill's `permissions` (`allow`, `deny`, `ask`) are applied. Use `permissions.deny` to block a tool while the skill runs
4. The specified model is used (if different from the current one)
`allowed-tools` and `permissions` apply to skills that run inline. A skill that runs as a [subagent](/cli/extensibility/skills/creating-skills#running-skills-as-subagents) (`subagent: true` or `agent:`) gets its tool access from the subagent profile instead.
***
## 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.
# Commands & Flags
Source: https://docs.devin.ai/cli/reference/commands
Complete Devin CLI reference for global flags, subcommands such as devin auth, mcp, ssh, and forward, 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). |
| `--cloud` | | | Drive [Devin Cloud sessions](/cli/cloud) instead of the local agent. Requires a Devin account. |
| `--continue` | `-c` | | Resume the most recent session in the current directory |
| `--resume ` | `-r` | | Resume a specific session by ID. With `--cloud`, accepts a cloud session ID or URL. |
| `--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 --cloud # Start a Devin Cloud session
devin --cloud -r https://app.devin.ai/sessions/… # Resume a cloud 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 non-authentication 4xx errors such as 404 or 405 (per the [MCP spec](https://spec.modelcontextprotocol.io/specification/2025-03-26/basic/transports/#backwards-compatibility)). 401 and insufficient-scope 403 responses with a `WWW-Authenticate` challenge are reported directly so you can authenticate. 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 the local Devin configuration. It reports which [custom subagent](/cli/subagents#custom-subagents) profiles loaded, flags any `AGENT.md` definition whose frontmatter could not be parsed (such definitions are skipped at runtime), and warns about frontmatter keys Devin ignores. The command exits with a non-zero status if any check fails.
```bash theme={null}
devin doctor
devin doctor --json # Machine-readable output
```
### devin airgap doctor
Diagnose air-gapped configuration and model endpoint connectivity. In addition to the custom subagent check from `devin doctor`, it checks the license, local configuration paths, and the models file, and probes each configured model endpoint.
```bash theme={null}
devin airgap doctor
devin airgap doctor --json # Machine-readable output
```
`devin airgap doctor` is only present in air-gapped builds of the CLI.
### devin ssh
SSH into a [cloud session's](/cli/cloud) VM. Wraps the system `ssh` to the Devin SSH gateway and approves the connection with your logged-in credentials, so no browser round-trip is needed. See [SSH](/cli/ssh).
```bash theme={null}
devin ssh [--gateway ] [ssh options...]
```
| Argument | Description |
| ------------------------- | ------------------------------------------------------------------------------------- |
| `` | Session ID or session URL |
| `--gateway