Plugin System

xbot’s plugin system provides VSCode-like extensibility through a unified architecture supporting multiple runtimes (native Go, stdio/gRPC, script, and future WASM). Plugins can contribute tools, hooks, widgets, context enrichers, commands, themes, channel providers, and web UI extensions.

• Multiple Runtimes: Native Go plugins, stdio/gRPC plugins (any language), script plugins (bash), and WASM (planned)
• Declarative Manifests: Each plugin declares its capabilities via plugin.json
• Permission System: Fine-grained capability control — plugins only access what they declare
• Hook System: Pre/post tool use, session lifecycle, user prompt, and custom events
• Widget System: CLI status bar, title bar, info bar, and footer widgets
• Web Plugin v2: Type-safe ESM frontend plugins with declarative UI contributions
• Channel Plugins: Full channel adapters (e.g., GenUI display_html) via stdio protocol
• Event Bus: Plugin-to-plugin pub/sub communication
• KV Storage: Per-plugin persistent key-value storage
• Hot Reload: Configuration-driven plugin activation/deactivation
• Auto-retry: Exponential backoff for failed plugins
• Dependency Resolution: Topological sort with cycle detection

• Getting Started — Create your first plugin in 5 minutes
• Architecture — How the plugin system works under the hood
• Plugin Manifest — Complete plugin.json specification
• Plugin Lifecycle — Activate, deactivate, and activation events
• PluginContext API — The plugin’s gateway to xbot
• Permissions — Capability-based security model
• Storage — Per-plugin KV storage
• Event Bus — Plugin-to-plugin communication
• Hooks — Lifecycle hooks and interceptors
• Widgets — CLI and Web UI widgets
• Tools — Register custom tools for the LLM
• Script Runtime — Bash script plugins
• Stdio Runtime Protocol — JSON-RPC protocol for any language
• Channel Plugins — Full channel adapters
• Configuration — User-configurable plugin settings
• Dependencies — Plugin dependency resolution
• Migration — Plugin data migration system
• Logging & Audit — Per-plugin logs and audit trail
• Hot Reload & Monitoring — Reload, config watching, auto-retry, health checks
• Web Plugin System — Frontend ESM plugin runtime
• Cookbook — Step-by-step development guides
• API Reference — Complete API reference
• Built-in Plugins — xbot’s bundled plugins

A minimal script plugin (plugin.json):

{
  "id": "my-plugin",
  "name": "My Plugin",
  "version": "1.0.0",
  "runtime": "script",
  "entry": "bash main.sh",
  "activationEvents": ["onStart"],
  "permissions": ["ui.contribute"],
  "contributes": {
    "ui": [
      {
        "id": "greeting",
        "slot": "statusBarRight",
        "description": "Show a greeting"
      }
    ]
  }
}

The script main.sh:

#!/bin/bash
echo "Hello from my plugin!"

Place both files in ~/.xbot/plugins/my-plugin/ and restart xbot. The greeting appears in the status bar.