Plugin Cookbook
Hands-on recipes for building xbot plugins. Every recipe starts with a working example drawn from the real plugin code in this repository (plugin/examples/, plugins/xbot-genui, plugins/xbot-git-fancy) and explains the API behind it.
| Recipe | What you build |
|---|---|
| Quick Start: Script Plugin | A git-info status widget in bash — no compilation |
| Quick Start: Go Plugin | A native Go plugin with tools, hooks, and a context enricher |
| Quick Start: Stdio Plugin | A Python plugin speaking NDJSON over stdio |
| Quick Start: Web Plugin | A frontend ESM view panel |
| Script Plugins | Full guide: widgets, env vars, triggers, sync hints |
| Go Plugins | Full guide: PluginContext, SDK helpers, UI bridges |
| Stdio Plugins | Full guide: protocol handlers in any language |
| Channel Plugins | Full channel adapters: tools, prompts, web UI |
| Web Plugins | Type-as-contract frontend plugins with @xbot/plugin-api |
| Configuration | Declarative plugin settings with defaults |
| Widgets | Status bar, info bar, and footer widgets |
| Hooks | Lifecycle events: deny, ask, defer, allow |
| Tools | Registering tools the agent can call |
| Event Bus | Plugin-to-plugin pub/sub |
| Storage | Persistent per-plugin key-value state |
| Permissions | The complete permission catalogue |
| Dependencies | Plugin dependency graphs and activation order |
| Debugging | Logs, profiler, hot reload |
| Testing | TestKit, mocks, and golden tests |
| Publishing | Distribution, checksums, migration |
New to xbot plugins? Follow the four Quick Start recipes in order. They cover the four runtimes supported by plugin.NewCompositeRuntimeFactory() (plugin/runtime_factory.go):
switch manifest.Runtime {
case RuntimeNative: // in-process Go
case RuntimeGRPC, RuntimeStdio: // external NDJSON process
case RuntimeScript: // periodic external script
}
Each runtime targets a different trade-off: script for zero-build widgets, native Go for tight integration, stdio for any language, and web for UI-only frontend extensions. A single plugin.json can combine them — see the built-in xbot.git-fancy plugin, which pairs a Go stdio backend with a React view.
~/.xbot/plugins/<plugin-id>/
├── plugin.json # manifest — id, runtime, entry, permissions, contributes
├── <entry file> # main.sh / main.go / main.py / web/index.js
└── data/ # runtime storage (created automatically)