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.

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