Plugin System

Kollab CLI features a powerful plugin system that lets you extend functionality, add custom commands, and integrate with external services.

Overview

The plugin system provides:

Dynamic plugin discovery - automatically loads plugins from the plugins directory
Hook integration - plugins can register hooks for any event type
Cross-plugin communication - plugins can discover and communicate with each other via SDK
Full-screen plugins - create interactive full-screen experiences

Plugin Types

Standard Plugins

Full-Screen Plugins

Take complete control of the terminal for interactive experiences like the Matrix effect or file browsers.

Creating a Plugin

Create a new Python file in ~/.kollabor-cli/plugins/:

# my_plugin.py
from core.events import EventType, Hook, HookPriority

class MyPlugin:
    """Custom plugin for Kollab CLI."""

    def __init__(self, name, state_manager, event_bus, renderer, config):
        self.name = name
        self.state_manager = state_manager
        self.event_bus = event_bus
        self.renderer = renderer
        self.config = config

    async def register_hooks(self):
        """Register plugin hooks with the event bus."""
        hook = Hook(
            name="my_custom_hook",
            plugin_name=self.name,
            event_type=EventType.USER_INPUT_PRE,
            priority=HookPriority.NORMAL.value,
            callback=self.on_user_input
        )
        await self.event_bus.register_hook(hook)

    async def on_user_input(self, data, event):
        """Process user input before it's sent to the LLM."""
        message = data.get("message", "")
        # Your custom logic here
        return {"message": message, "processed": True}

Plugin Metadata

Full-screen plugins use a metadata class for configuration:

from core.fullscreen.plugin import FullScreenPlugin, PluginMetadata

class MyFullScreenPlugin(FullScreenPlugin):
    def __init__(self):
        metadata = PluginMetadata(
            name="my_plugin",
            description="A custom full-screen plugin",
            version="1.0.0",
            author="Your Name",
            category="utility",
            icon="*",
            aliases=["mp", "myplugin"]
        )
        super().__init__(metadata)

Field	Description	Required
`name`	Unique plugin identifier	Yes
`description`	Brief description of the plugin	No
`version`	Plugin version string	No
`author`	Plugin author name	No
`category`	Plugin category (general, utility, demo)	No
`aliases`	Alternative command names	No

Plugin SDK

Use the KollaborPluginSDK for cross-plugin communication and service registration:

from core.llm.plugin_sdk import KollaborPluginSDK
from core.plugins.factory import PluginFactory

class MyPlugin:
    def __init__(self, ...):
        # Initialize SDK for service registration
        self.sdk = KollaborPluginSDK()

        # Access plugin factory for discovery
        self.plugin_factory = PluginFactory()

    async def discover_plugins(self):
        """Discover other loaded plugins."""
        plugins = await self.plugin_factory.get_loaded_plugins()
        for name, plugin in plugins.items():
            print(f"Found plugin: {name}")

Built-in Plugins

hook_monitoring_pluginShowcase

Comprehensive example demonstrating all plugin ecosystem features: hook monitoring, plugin discovery, cross-plugin communication, and service registration.

save_conversation_pluginCore

Handles the /save command for exporting conversations to JSON or Markdown files.

resume_conversation_pluginCore

Enables resuming previous conversations from saved state.

query_enhancer_pluginEnhancement

Automatically enhances user queries with context and formatting improvements.

tmux_pluginIntegration

Provides tmux integration for session management and multi-pane workflows.

Plugin Directory Structure

~/.kollabor-cli/
├── plugins/                    # User plugins directory
│   ├── __init__.py
│   ├── my_custom_plugin.py
│   └── fullscreen/             # Full-screen plugins
│       └── my_fullscreen.py
├── config.json                 # Plugin configuration
└── state.db                    # Persistent state