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

Plugins load from the installed package's plugins/ directory and from your project's ./plugins directory. Create a new Python file there:

# my_plugin.py
from kollabor_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 kollabor_tui.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

The SDK covers the full plugin lifecycle (initialize, register_hooks, get_status_line, process_command) and provides scaffolding plus custom tool registration via create_plugin_template, register_custom_tool, and execute_custom_tool:

from kollabor_plugins import KollaborPluginSDK, PluginFactory

class MyPlugin:
    def __init__(self, ...):
        # SDK for plugin templates and custom tools
        self.sdk = KollaborPluginSDK()

        # Plugin factory holds all instantiated plugins
        self.plugin_factory = PluginFactory()

    def list_other_plugins(self):
        """Get all instantiated plugins by name."""
        return self.plugin_factory.get_all_instances()

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.

terminal_pluginIntegration

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

Plugin Directory Structure

~/.kollab/
├── config.json                 # User configuration (plugin settings merge here)
├── agents/                     # Global agent definitions
└── projects/                   # Per-project data
    └── <encoded-path>/
        ├── conversations/      # Conversation history
        └── logs/               # Application logs