Plugin Overview

Colab's plugin system allows you to extend the editor with custom functionality. Plugins are standard npm packages with a special colab-plugin field in their package.json.

What Can Plugins Do?

Colab plugins can:

• Inject Webview Scripts - Run JavaScript in web browser tabs
• Add Terminal Commands - Register custom commands users can type in the terminal
• Provide Code Completions - Add autocomplete suggestions in the editor
• Add Status Bar Items - Display information in the status bar
• Decorate Files - Add badges and colors to files in the file tree
• Add Context Menu Items - Add right-click menu options
• Register Keyboard Shortcuts - Add global or context-specific keybindings
• Register Commands - Commands that can be triggered by shortcuts or other plugins

Plugin Architecture

Plugins run directly in the main Bun process (v1). This gives plugins full access to Node.js/Bun APIs while providing a structured API surface for interacting with Colab.

Plugin Lifecycle

Plugins have two main lifecycle functions:

// Called when the plugin is activated
export async function activate(api: PluginAPI): Promise<void> {
  // Register features, start services
}

// Called when the plugin is deactivated
export async function deactivate(): Promise<void> {
  // Clean up resources
}

The Disposable Pattern

All plugin registrations return a Disposable object with a dispose() method. Store these and call them in deactivate() to properly clean up:

const disposables: Disposable[] = [];

export async function activate(api: PluginAPI) {
  // Each registration returns a Disposable
  const cmd = api.commands.registerCommand('myCommand', handler);
  disposables.push(cmd);
}

export async function deactivate() {
  // Clean up all registrations
  disposables.forEach(d => d.dispose());
}

Permissions

Plugins declare permissions in their manifest. In v1, permissions are honor-system based (not enforced). Declared permissions include:

• fs - File system access: 'none' | 'readonly' | 'readwrite'
• network - Network access: 'none' | 'allow'
• terminal - Terminal access: 'none' | 'readonly' | 'readwrite'
• git - Git operations: 'none' | 'readonly' | 'readwrite'
• clipboard - Clipboard access: 'none' | 'read' | 'readwrite'
• notifications - Show notifications: true | false