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:

• Register Commands - Commands that can be triggered by shortcuts, menus, or other plugins
• 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 Custom Slates - Create custom file viewers and editors for specific file types
• Manage Persistent State - Store and retrieve plugin data across sessions
• Access Git Info - Query branch, status, and other git information
• Execute Shell Commands - Run shell commands and open external URLs
• Subscribe to Events - React to file changes and editor switches
• Access File System - Read, write, and search files in the workspace
• Show Notifications - Display info, warning, and error messages to users
• Manage Settings - Create configurable settings with a UI panel

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());
}

Entitlements

Plugins declare entitlements in their manifest. Entitlements are declarative - they inform users what capabilities a plugin claims to need, but are not enforced at runtime. Users should only install plugins from sources they trust.

Available entitlement categories:

• filesystem - File system access: read, write
• network - Network access: internet, domains[]
• process - Process spawning: spawn
• terminal - Terminal access: commands, read, write
• webview - Webview integration: scriptInjection
• ui - UI elements: statusBar, contextMenu, fileDecorations, notifications
• editor - Editor features: completions
• keybindings - Keyboard shortcuts: global