Overview & quick start

A plugin is a directory with a beswarm.toml manifest in it. The manifest declares three kinds of things:

Section	What it is	Runs
`[commands.<name>]`	A short-lived argv command	On request — the Plugins panel or `beswarm plugin run` — or from a hook. In the background; output goes to the plugin's history.
`[hooks]`	Maps events to command names	When something happens in the session: an agent goes `blocked`, a tab opens, a TUI starts, …
`[views.<name>]`	An interactive argv command	In a new terminal tab: the Plugins panel or `beswarm plugin view`.

You can write commands in any language. There's no SDK: each run reads its context as JSON on stdin, and calls back into BeSwarm through its own CLI.

warning

There is no sandbox. A plugin runs as you, with full access to your files. Only add code you trust.

Quick start

Make a directory:

my-plugin/
├── beswarm.toml
└── hello.sh

beswarm.toml:

[plugin]
id = "me.hello"
name = "Hello"
version = "0.1.0"
requires = "0.1.0"
about = "My first plugin"
 
[commands.greet]
label = "Say hello"
run = ["sh", "hello.sh"]

hello.sh:

#!/bin/sh
ctx=$(cat)   # the run's context, as JSON
echo "Hello from session $BESWARM_SESSION"
echo "Context: $ctx"

Add it, then run it:

beswarm plugin add ./my-plugin       # validates the manifest and registers it
beswarm plugin list                  # check it's there, and see any warnings
beswarm plugin run greet             # needs a running TUI; prints a run id
beswarm plugin history me.hello      # status, exit code and output

In the TUI, open the Plugins panel, select the plugin and press ↵ (or double-click, or right-click) for its menu.

Hook it to an event

Commands become useful when hooks run them for you. Add a [hooks] table naming the command:

[hooks]
"agent.done" = "greet"

Run beswarm plugin add ./my-plugin again to pick up the change; from then on greet runs every time an agent finishes a turn. See Events for the full list.

What needs a running TUI

add, remove, on, off and list work on the registry directly, so no TUI is needed. run, view and history talk to a running TUI, and hooks only fire while one is open. They act on the session in $BESWARM_SESSION — set for every plugin run — else default; pass --session <name> to pick another.

The full command list is in the CLI reference.