Getting Started

This guide will walk you through creating your first Colab plugin.

Step 1: Create a Plugin Folder

Create a new folder for your plugin. You can place it anywhere, but for development it's convenient to keep it near your Colab installation:

mkdir my-colab-plugin
cd my-colab-plugin

Step 2: Create package.json

Create a package.json with the required colab-plugin field:

{
  "name": "my-colab-plugin",
  "version": "1.0.0",
  "description": "My first Colab plugin",
  "main": "index.ts",
  "keywords": ["colab-plugin"],
  "colab-plugin": {
    "displayName": "My Plugin",
    "description": "Does something cool",
    "main": "index.ts",
    "entitlements": {
      "network": {
        "internet": true,
        "domains": ["api.example.com"],
        "reason": "Fetches data from the example API"
      }
    },
    "activationEvents": ["*"]
  }
}

Manifest Fields

Field Description
displayName Human-readable name shown in the UI
description Brief description of what the plugin does
main Entry point file (TypeScript or JavaScript)
entitlements Declared capabilities the plugin needs (see below)
activationEvents When to activate: ["*"] for startup, or specific events

Entitlements

Entitlements declare what capabilities your plugin claims to need. These are displayed to users so they can make informed trust decisions.

Important: Entitlements are NOT enforced by Colab. Plugins run with full Bun runtime access. Entitlements are a trust signal - users should only install plugins from sources they trust.
Category Options
filesystem read, write, fullAccess
network internet, domains[]
process spawn (run shell commands)
terminal read, write, commands
webview scriptInjection, requestInterception
system environment, systemInfo
ai localModels, externalServices
sensitive credentials, clipboard
ui statusBar, contextMenu, fileDecorations, notifications
editor completions, hover, codeActions, diagnostics
keybindings global, editor

Each category can include a reason field to explain why the capability is needed.

Step 3: Create the Plugin Entry Point

Create index.ts with the activate and deactivate functions:

import type { PluginAPI, Disposable } from 'colab/src/main/plugins/types';

const disposables: Disposable[] = [];

export async function activate(api: PluginAPI): Promise<void> {
  api.log.info('My plugin is activating!');

  // Register a simple command
  const cmd = api.commands.registerCommand('myPlugin.sayHello', async () => {
    api.notifications.showInfo('Hello from my plugin!');
  });
  disposables.push(cmd);

  api.notifications.showInfo('My plugin loaded!');
}

export async function deactivate(): Promise<void> {
  for (const d of disposables) {
    d.dispose();
  }
  disposables.length = 0;
}

Step 4: Install the Plugin

In Colab, open the Plugins panel from the status bar. Click "Install from folder" and select your plugin folder. The plugin will be installed and automatically activated.

Development Tip: When installing from a local folder, Colab creates a symlink. Changes to your plugin code take effect after restarting Colab.

Step 5: Add More Features

Now that you have a working plugin, you can add more features:

Add a Terminal Command

const terminalCmd = api.terminal.registerCommand('hello', async (ctx) => {
  ctx.write('Hello from my plugin!\r\n');
  ctx.write(`Current directory: ${ctx.cwd}\r\n`);
});
disposables.push(terminalCmd);

Now users can type hello in any terminal!

Add a Status Bar Item

const statusItem = api.statusBar.createItem({
  id: 'my-status',
  text: 'My Plugin',
  tooltip: 'Click for info',
  alignment: 'right',
});
disposables.push(statusItem);

// Update it later
statusItem.update({ text: 'Updated!' });

Add Code Completions

const completions = api.editor.registerCompletionProvider(
  ['typescript', 'javascript'],
  {
    triggerCharacters: ['.'],
    provideCompletions(ctx) {
      if (!ctx.linePrefix.endsWith('myLib.')) {
        return [];
      }
      return [
        {
          label: 'doSomething',
          insertText: 'doSomething($1)',
          detail: 'Do something cool',
          kind: 'function',
        },
      ];
    },
  }
);
disposables.push(completions);

Next Steps

See the API Reference for the complete list of available APIs, or check out the Example Plugin for a full working example.

← Plugin Overview API Reference →