Skip to main content
skill CX Codex

windsurf-webhooks-events — Claude Code skill: events and setup

The windsurf-webhooks-events skill guides you through building Windsurf extensions with the VS Code API and forwarding workspace events to an external service. Use it to track saves, editor changes, or terminal output.

MIT 1 installs ★ 2,935 updated 2026-10-29

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add jeremylongshore/tons-of-skills-marketplace --skill windsurf-webhooks-events -a claude-code
Open on GitHub

What windsurf-webhooks-events does

The skill walks through a Windsurf extension that responds to file saves, active-editor changes, and terminal output. It shows how to send workspace events as JSON to a webhook, with a delay for frequent events. The examples also cover extension settings and a status command.

You need Node.js 18+, npm, familiarity with the VS Code Extension API, and Windsurf for testing. Build with npm run compile and package the extension as a .vsix using npx vsce package. API compatibility depends on the VS Code version, so check engines.vscode against the Windsurf version you plan to target.

What it helps with

  • build a TypeScript extension for Windsurf
  • track file saves and active-editor changes
  • send workspace events to a webhook
  • respond to errors in terminal output

Example prompts for the agent

  • Build a TypeScript Windsurf extension that tracks file saves and displays the number of diagnostic errors.
  • Add webhook delivery for workspace events and make the URL configurable in extension settings.
  • Check terminal error handling and prepare a .vsix package for Windsurf.

How to install windsurf-webhooks-events

1Skills CLI (Vercel)

npx skills add jeremylongshore/tons-of-skills-marketplace --skill windsurf-webhooks-events -a claude-code

2Manually: put the files in place

~/.claude/skills/windsurf-webhooks-events/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/windsurf-webhooks-events/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about windsurf-webhooks-events

How do I install windsurf-webhooks-events in Claude Code?

Run npx skills add jeremylongshore/tons-of-skills-marketplace --skill windsurf-webhooks-events -a claude-code. The skill file will be at ~/.claude/skills/windsurf-webhooks-events/SKILL.md.

What does windsurf-webhooks-events do?

It guides development of Windsurf extensions based on the VS Code API, including tracking editor events and sending them to an external service through a webhook.

What do I need to build an extension with this skill?

You need Node.js 18+, npm, familiarity with the VS Code Extension API, and Windsurf for testing.

Source text

SKILL.md · MIT
---
name: windsurf-webhooks-events
description: 'Build Devin Desktop (formerly Windsurf) extensions and integrate with VS Code extension API events.

  Use when building custom Windsurf extensions, tracking editor events,

  or integrating Windsurf with external tools via extension development.

  Trigger with phrases like "windsurf extension", "windsurf events",

  "windsurf plugin", "build windsurf extension", "windsurf API".

  '
allowed-tools: Read, Write, Edit, Bash(npm:*), Bash(npx:*)
argument-hint: "[scope or requirements]"
version: 1.12.0
license: MIT
author: Jeremy Longshore <[email protected]>
tags:
- saas
- windsurf
- extensions
- vscode-api
- development
compatibility: Designed for Claude Code
---
# Windsurf Extension Development & Events

## Overview

Build compatible extensions on Devin Desktop's VS Code foundation to observe workspace events and integrate external tools. Keep telemetry, credential, network, and user-consent boundaries explicit instead of assuming every VS Code behavior is product-guaranteed.

## Prerequisites

- Node.js 18+ and npm
- VS Code Extension API familiarity
- `yo` and `generator-code` for scaffolding
- Windsurf IDE for testing

## Tool Use

- Use `Read` to inspect only the repository files and configuration needed for the request.
- Use `Write` only for a new artifact the user requested; never write credentials or unreviewed production configuration.
- Use `Edit` for bounded, reviewable changes and preserve unrelated user work.
- Use only the command-scoped `Bash` entries declared in frontmatter, with non-destructive checks before mutations.

## Instructions

### Step 1: Scaffold Extension

```bash
# Install scaffolding tools
npm install -g yo generator-code

# Generate extension
yo code
# Select: New Extension (TypeScript)
# Name: my-windsurf-extension
```

### Step 2: Track Workspace Events

```typescript
// src/extension.ts
import * as vscode from "vscode";

export function activate(context: vscode.ExtensionContext) {
  console.log("Extension active in Windsurf");

  // Track file saves
  const saveListener = vscode.workspace.onDidSaveTextDocument(
    async (document) => {
      const diagnostics = vscode.languages.getDiagnostics(document.uri);
      const errors = diagnostics.filter(
        (d) => d.severity === vscode.DiagnosticSeverity.Error
      );
      if (errors.length > 0) {
        vscode.window.showWarningMessage(
          `${document.fileName}: ${errors.length} error(s) after save`
        );
      }
    }
  );

  // Track active editor changes
  const editorListener = vscode.window.onDidChangeActiveTextEditor(
    (editor) => {
      if (editor) {
        const lang = editor.document.languageId;
        const lines = editor.document.lineCount;
        console.log(`Opened: ${editor.document.fileName} (${lang}, ${lines} lines)`);
      }
    }
  );

  // Track terminal output
  const terminalListener = vscode.window.onDidWriteTerminalData((event) => {
    // Can monitor for specific patterns (errors, warnings)
    if (event.data.includes("ERROR") || event.data.includes("FAIL")) {
      vscode.window.showWarningMessage("Error detected in terminal output");
    }
  });

  context.subscriptions.push(saveListener, editorListener, terminalListener);
}
```

### Step 3: Send Events to External System

```typescript
// src/webhook.ts
import * as vscode from "vscode";

interface WorkspaceEvent {
  event: string;
  file?: string;
  language?: string;
  timestamp: string;
  metadata?: Record<string, unknown>;
}

async function sendEvent(event: WorkspaceEvent): Promise<void> {
  const webhookUrl = vscode.workspace
    .getConfiguration("windsurf-events")
    .get<string>("webhookUrl");

  if (!webhookUrl) return;

  try {
    await fetch(webhookUrl, {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify(event),
    });
  } catch (err) {
    console.warn("Webhook delivery failed:", err);
  }
}

// Debounce frequent events
const debounceMap = new Map<string, NodeJS.Timeout>();

function debouncedSend(event: WorkspaceEvent, delayMs = 2000): void {
  const key = `${event.event}:${event.file}`;
  clearTimeout(debounceMap.get(key));
  debounceMap.set(
    key,
    setTimeout(() => {
      sendEvent(event);
      debounceMap.delete(key);
    }, delayMs)
  );
}
```

### Step 4: Extension package.json

```json
{
  "name": "windsurf-events",
  "displayName": "Windsurf Events",
  "version": "1.0.0",
  "engines": { "vscode": "^1.85.0" },
  "activationEvents": ["onStartupFinished"],
  "main": "./dist/extension.js",
  "contributes": {
    "configuration": {
      "title": "Windsurf Events",
      "properties": {
        "windsurf-events.webhookUrl": {
          "type": "string",
          "description": "URL to send workspace events to"
        },
        "windsurf-events.trackSaves": {
          "type": "boolean",
          "default": true,
          "description": "Track file save events"
        },
        "windsurf-events.trackErrors": {
          "type": "boolean",
          "default": true,
          "description": "Track terminal error events"
        }
      }
    },
    "commands": [
      {
        "command": "windsurf-events.showStatus",
        "title": "Windsurf Events: Show Status"
      }
    ]
  }
}
```

### Step 5: Build and Install

```bash
# Build
npm run compile
# or: npm run build

# Package as .vsix
npx vsce package

# Install in Windsurf
windsurf --install-extension windsurf-events-1.0.0.vsix

# Or publish to marketplace
npx vsce publish
```

### Step 6: Test in Windsurf

```
1. Open Extension Development Host: F5 in Windsurf
2. A new Windsurf window opens with extension loaded
3. Open a file, save it, trigger events
4. Check Output panel > "Windsurf Events" channel
5. Verify webhook delivery (use https://webhook.site for testing)
```

## Output

Produce a reviewed VS Code-compatible extension change with event subscriptions, disposal lifecycle, authentication and secret storage, payload schema, retry behavior, local test evidence, package metadata, and marketplace compatibility notes. Do not log raw credentials or proprietary source.

## Error Handling

| Issue | Cause | Solution |
|-------|-------|----------|
| Extension not activating | Wrong `activationEvents` | Use `onStartupFinished` for always-on |
| Webhook fails | Network/URL issue | Queue locally, retry with backoff |
| High CPU usage | Too many listeners | Debounce frequent events (saves, edits) |
| API incompatibility | Windsurf vs VS Code version | Pin `engines.vscode` version |
| `vsce package` fails | Missing fields | Add publisher, repository, license |

## Examples

### Team Analytics Extension

```typescript
// Track AI acceptance rate per developer
vscode.languages.registerInlineCompletionItemProvider(
  { pattern: "**" },
  {
    provideInlineCompletionItems(document, position) {
      // Log completion requests (don't interfere with Supercomplete)
      console.log(`Completion at ${document.fileName}:${position.line}`);
      return []; // Return empty -- let Windsurf handle completions
    }
  }
);
```

### Quick Test Webhook

```bash
# Start a test webhook receiver
npx -y webhook-relay -p 3456
# Configure extension: windsurf-events.webhookUrl = "http://localhost:3456"
```

## Resources

- [Focused first-party references](references/official-docs.md)
- [VS Code Extension API](https://code.visualstudio.com/api)
- [VS Code Extension Publishing](https://code.visualstudio.com/api/working-with-extensions/publishing-extension)
- [Windsurf Marketplace](https://marketplace.windsurf.com)

## Related Skill

Continue with `windsurf-multi-env-setup` to package extension settings, event destinations, and environment-specific policies for repeatable team rollout.

© Jeremy Longshore · MIT · jeremylongshore/tons-of-skills-marketplace

Similar skills

All skills for Backend and APIs →

From the same set139

The whole set →
maintainx-webhooks-events maintainx-webhooks-events configures MaintainX webhook ingestion and work order event handlers in Express. Useful when connecting maintenance status changes to external systems. CX Codex +1 1installs lindy-webhooks-events The lindy-webhooks-events skill guides setup of Lindy AI webhook triggers and application callbacks. Use it to define event contracts, validate requests, and handle retries in a Lindy integration. CX Codex +1 1installs fireflies-webhooks-events fireflies-webhooks-events walks an agent through building a Fireflies Webhooks V2 receiver: raw-body HMAC check, event allowlisting, dedupe, and a 2xx reply fast enough for the 10-second window. CX Codex +1 1installs documenso-webhooks-events documenso-webhooks-events configures Documenso webhook endpoints and event handlers. Useful when tracking document signing status and automating downstream actions. CX Codex +1 1installs twinmind-webhooks-events twinmind-webhooks-events — a skill for TwinMind meeting events: transcription completion, action item extraction, and calendar sync notifications. CX Codex +1 1installs firecrawl-webhooks-events firecrawl-webhooks-events sets up Firecrawl webhook ingestion with raw HMAC-SHA256 signature verification, deduplication, and polling fallback. CX Codex +1 1installs coderabbit-webhooks-events coderabbit-webhooks-events is a Claude Code skill for designing Git-provider event automation around CodeRabbit reviews. It checks signatures and tests replay handling. CX Codex +1 1installs posthog-webhooks-events posthog-webhooks-events registers PostHog webhook destinations through the API, handles the incoming payloads, and runs bounded event queries with HogQL or the private API. CX Codex +1 1installs

Project sponsors

Companies that keep this analytics open