Plugin System

Plugins are “mini-apps” for xbot — show git status in the info bar, auto-display diff previews, run lint before commits, or send desktop notifications. No code changes required: just a JSON manifest and a script.

Tip

Let the agent do it. You don’t need to write config files. Say “add a plugin that shows the current git branch in the status bar” or “install a plugin that shows a diff after every file edit” — the agent creates plugin.json and the script, then reloads automatically.

New! The plugin system now has comprehensive documentation. See the Plugin System section for complete guides, API references, and cookbook tutorials.

The agent reloads plugins automatically after creating or modifying them. You can also reload manually:

A plugin is a directory with at least two files:

~/.xbot/plugins/my-plugin/
├── plugin.json     ← Plugin manifest (name, capabilities, triggers)
└── my-script.sh    ← The script that does the actual work

plugin.json:

{
  "id": "my-git",
  "name": "My Git Status",
  "version": "1.0.0",
  "description": "Shows current git branch and change status",
  "runtime": "script",
  "entry": "bash git.sh",
  "permissions": ["ui.contribute", "hooks.subscribe"],
  "contributes": {
    "ui": [{
      "id": "git-branch",
      "slot": "infoBar",
      "priority": 10,
      "triggers": ["PostToolUse:Shell*", "PostToolUse:FileReplace*"]
    }]
  }
}

git.sh:

#!/bin/bash
set -euo pipefail
branch=$(git rev-parse --abbrev-ref HEAD 2>/dev/null) || true
if [ -z "$branch" ]; then
  echo "dim|git: —"
  exit 0
fi
changes=$(git status --porcelain 2>/dev/null | wc -l | tr -d ' ') || changes=0
if [ "$changes" -gt 0 ]; then
  echo "warn|git:${branch} Δ${changes}"
else
  echo "ok|git:${branch} ✓"
fi

The output format is style|text. Available styles: dim, ok, warn, err, info, accent.

Plugins are opt-in. Enable in ~/.xbot/config.json:

{
  "plugins": {
    "enabled": true,
    "allow_unverified": false
  }
}

Warning

Security: Plugins run as scripts on your machine. Only install plugins from sources you trust. Keep allow_unverified disabled unless you know what you’re doing.

Show dynamic content in the TUI:

triggers control when a plugin’s widget runs:

Triggers support wildcards: Shell* matches all Shell tool calls.

When a script runs, these environment variables are automatically available:

{
  "id": "my-plugin",           // Required, globally unique ID
  "name": "My Plugin",         // Display name
  "version": "1.0.0",          // Semantic version
  "description": "What it does", // One-line description
  "author": "your-name",
  "runtime": "script",         // "script" | "native" | "grpc"
  "entry": "bash main.sh",     // Entry command (script type)
  "timeout": "30s",            // Execution timeout (Go duration string, max 5m)
  "permissions": [...],        // Required permissions
  "contributes": {             // What the plugin contributes
    "ui": [...],               // UI components (widgets)
    "tools": [...],            // Custom tools
    "hooks": [...]             // Lifecycle hooks
  }
}

Add refreshInterval to a widget for periodic auto-refresh — no trigger needed:

"ui": [{
  "id": "clock",
  "slot": "infoBar",
  "priority": 0,
  "refreshInterval": "30s",
  "triggers": ["SessionStart:"]
}]

toolHint widgets can set "sync": true to run synchronously when a tool completes, ensuring hints appear instantly:

"ui": [{
  "id": "diff",
  "slot": "toolHint",
  "sync": true,
  "triggers": ["PostToolUse:FileReplace*"]
}]

Need inspiration? Here are practical plugins you can create:

• Git branch widget — show current branch + dirty status in the info bar
• PR reminder — check for open PRs daily and notify
• Auto-lint — run make lint after every file edit
• Disk usage — show free disk space in the status bar
• Build status — display CI pass/fail badge
• Time tracker — track time spent per session
• Notification sound — play a sound when the agent finishes

Ask the agent: “Create a plugin that [your idea]” and it handles the rest.

• Hooks — lifecycle event hooks
• MCP — external tool integration
• Tips & Tricks — plugin usage patterns