# Devin (Windsurf) Integration

Connect Devin (Windsurf) to Capsule Security for complete visibility into AI coding assistant activity, including prompts, tool execution, file access, and session context.

## Overview

This integration uses Cascade's hooks system to capture AI coding assistant activity. Hooks are shell commands that execute at specific points in Cascade's lifecycle, providing automated workflows and audit capabilities.

The integration is delivered as a single `hooks.json` that works on every operating system - each hook carries both a Unix command and a Windows PowerShell variant. Deployed at the cloud or system level, the hooks are merged ahead of user and workspace configurations and cannot be disabled by end users.

The following hooks are configured:

| Hook Event | Description |
|  --- | --- |
| **pre_user_prompt** | User prompts before submission, plus session context collection (skills, MCP servers, settings) |
| **pre/post_run_command** | Terminal command execution (before and after) |
| **pre/post_mcp_tool_use** | MCP tool invocations (before and after) |
| **pre/post_read_code** | File reads (before and after) |
| **pre/post_write_code** | File edits (before and after) |
| **post_cascade_response_with_transcript** | Completed agent responses with the full session transcript |


## Prerequisites

Before you begin, ensure you have:

- **Devin Desktop** (formerly Windsurf) installed on target devices
- A **Capsule Security** account with admin access
- For the **Cloud** deployment method: an **Enterprise plan** and the `TEAM_SETTINGS_UPDATE` permission in the Devin Desktop dashboard


## Step 1: Choose a Deployment Method

1. Log in to the **Capsule Security** portal
2. Navigate to **Settings > Integrations** and locate **Devin (Windsurf)**
3. The setup wizard offers two deployment methods - Capsule generates the hooks configuration for you, including an embedded authentication token scoped to your organization:


| Method | How it works | Best for |
|  --- | --- | --- |
| **Cloud (Team Settings)** (recommended) | Enforce the Capsule hooks org-wide through Windsurf's Team Settings - no files on devices for Mac/Linux | Organizations on a Windsurf Enterprise plan |
| **MDM / Managed Deploy** | Download `hooks.json` and deploy it to the system-level path via your MDM (Jamf, Intune, Kandji, …) | Device-managed fleets |


## Step 2: Deploy the Configuration

### Cloud (Team Settings)

1. In the wizard, choose **Cloud** and copy the hooks configuration JSON
2. In the **Devin Desktop dashboard**, go to **Team Settings → Cascade Hooks**, paste the configuration, and save
3. Hooks are distributed to all team members automatically and load when the application starts
4. For Windows fleets, download `CapsuleWindsurfHook.ps1` from the wizard and distribute it to `C:\ProgramData\Capsule\WindsurfHooks\` - the hooks configuration invokes the script from that directory (macOS and Linux hook commands are self-contained and need no companion files)


### MDM / Managed Deploy

1. In the wizard, choose **MDM** and select your platform to download the configuration:
  - **Mac** / **Linux**: a single `hooks.json` file
  - **Windows**: a `capsule-windsurf-managed.zip` archive containing `hooks.json` and the `CapsuleWindsurfHook.ps1` companion script
2. Deploy the files to the following system-level locations via your MDM:
| Platform | `hooks.json` | Companion script |
|  --- | --- | --- |
| macOS | `/Library/Application Support/Windsurf/hooks.json` | Not required |
| Linux | `/etc/windsurf/hooks.json` | Not required |
| Windows | `C:\ProgramData\Windsurf\hooks.json` | `C:\ProgramData\Capsule\WindsurfHooks\CapsuleWindsurfHook.ps1` |
3. System-level hooks take precedence over user and workspace hooks and cannot be disabled by end users without root permissions


See the platform guides for step-by-step MDM instructions:

- [Microsoft Intune](/guides/mdm-intune)
- [Jamf Pro](/guides/mdm-jamf)
- [Kandji](/guides/mdm-kandji)
- [JumpCloud](/guides/mdm-jumpcloud)
- [Microsoft SCCM](/guides/mdm-sccm)
- [ManageEngine Endpoint Central](/guides/mdm-manageengine)
- [Tanium](/guides/mdm-tanium)


## Step 3: Restart Devin Desktop

Hooks are loaded at application start. Close Devin Desktop completely on target devices and reopen it for the configuration to take effect.

## Step 4: Verify the Installation

1. Start a **Cascade** session and run a simple task to generate activity
2. Log in to the **Capsule Security** portal
3. Navigate to **Inventory > Agents** and confirm the agent appears
4. Click on the agent and review the audit logs to verify events are captured:
  - Session start event with skills and MCP server context
  - User prompt
  - Tool execution (commands, file reads/writes, MCP tools)
  - Agent responses


### Troubleshooting

If events are not appearing:

1. **Verify `hooks.json` is at the correct system-level location** for the platform (see Step 2), or that the Team Settings policy is saved and assigned
2. **Windows: verify the companion script** - `CapsuleWindsurfHook.ps1` must exist at `C:\ProgramData\Capsule\WindsurfHooks\`, where the hooks configuration invokes it
3. **Confirm the application was fully restarted** after deployment - hooks only load at start
4. **Check the merge order** - Cascade combines cloud, system, user, and workspace hooks per action; a user-level configuration cannot disable the managed hooks, but a malformed managed file is skipped silently
5. **JetBrains plugin users** - the Windsurf JetBrains plugin reads a separate user-level configuration (`~/.codeium/hooks.json`); this managed deployment covers Devin Desktop
6. **Contact Capsule Security support** if issues persist


## Security Considerations

Cascade hooks execute with the signed-in user's environment credentials. Before deploying the configuration:

1. **Review all hook commands** in the generated configuration
2. **Verify the endpoint URL** matches your organization's Capsule instance
3. **Protect authentication tokens** embedded in the configuration (never commit `hooks.json` to version control)


## Support

For help with this integration:

- **Email**: support@capsule.security
- **Include**: Your organization ID, integration status, and any error messages


## References

- [Cascade Hooks Documentation](https://docs.devin.ai/desktop/cascade/hooks)