Skills, prompts, tools & plugins

These commands scan local folders, so most work without a running session. The reload commands refresh a running TUI.

skill

beswarm skill list [--json]   # numbered 1..N; --json adds id and name
beswarm skill reload          # rescan in the running TUI
beswarm skill system          # print BeSwarm's own built-in skill

A skill is a directory with a SKILL.md directly under a root. Roots are scanned in order:

~/.beswarm/skills
~/.claude/skills
~/.agents/skills
~/.codex/skills

~/.beswarm/skills is always listed, even when empty; the other roots are skipped when missing or empty.

skill system prints the skill that teaches an agent to drive sessions, workspaces, agents and terminals from the command line. It's built into the binary — hand it to an orchestrating agent that doesn't already have a BeSwarm skill.

Pass one to an agent with agent start --skill <dir> or --skill-id <id>.

prompt

beswarm prompt list [--json]  # numbered 1..N (the ids for --prompt-id); --json adds a preview
beswarm prompt reload

A prompt is any file directly under ~/.beswarm/prompts — extensions aren't filtered. The Prompts panel polls about every second while open; reload is for scripts that just wrote one. Not the same as agent prompt.

tool

beswarm tool list [--all|--local|--remote] [--json]

Lists the MCP servers the Tools panel shows, numbered Local then Remote; ids are the same in every scope. The default is --all (Local + Remote). The scope flags are mutually exclusive. Reads straight off disk, so no session is needed.

--local reads the agent MCP configs declared in mcp_sources.toml, plus ~/.beswarm/tools scanned recursively: a JSON or TOML file declaring MCP servers is listed as those servers, and any executable file as a tool of its own.
--remote reads the registry the Remote sub-tab edits, under ~/.beswarm.
--json prints a local array of groups (agent, label, servers with id, name, detail, path) and a remote array (id, name, protocol, url); only the keys in scope are present.

artifact

beswarm artifact list [--json]  # name, size, path — newest first; --json adds group, size in bytes
beswarm artifact path [--json]  # the directories list scans; --json adds each group name

An artifact is a file an agent left behind — a report, a diff, a generated doc. artifact list treats the current directory as the workspace and scans its artifacts/ and reports/ folders (two levels deep, dotfiles skipped), plus ~/.beswarm/artifacts, which every workspace lists under the global group.

To surface output in the Artifacts panel, have agents write it to one of those directories.

plugin

beswarm plugin list [--json]                            # added plugins: commands, views, hooks, warnings
beswarm plugin add <dir>                                # validate <dir>/beswarm.toml and add the plugin
beswarm plugin remove <plugin_id>                       # remove it; its files are left alone
beswarm plugin on <plugin_id>                           # let its commands and hooks run
beswarm plugin off <plugin_id>                          # stop them
beswarm plugin run <[plugin_id:]command>                # start a command in the running TUI
beswarm plugin view <[plugin_id:]view>                  # open a view in a new terminal
beswarm plugin history [plugin_id] [--limit <n>] [--json]   # recent runs with their output

A plugin is a directory holding a beswarm.toml that declares [commands.<name>] (short-lived argv commands), [hooks] (events mapped to command names) and [views.<name>] (interactive commands opened in a new terminal). To write one, see the Plugins guide.

warning

Plugins run as you, with no sandbox. Add only code you trust.

Subcommand	What it does
`list`	Every added plugin with its status, commands (hidden ones marked), views, hooks and warnings. Reads the registry itself, so no session is needed.
`add`	Validates the manifest — `<dir>/beswarm.toml`, or the file itself — and adds the plugin, replacing one with the same id. Prints any warnings. Add again after editing the manifest.
`remove`	Takes the plugin out of the registry. Its files are left alone.
`on` / `off`	Enables or disables its commands and hooks.
`run`	Starts a command in the running TUI and prints its run id — not the result; read that with `history`. Run from inside a terminal, the command's context is that terminal; otherwise the focused one.
`view`	Opens a view in a new terminal of the running TUI (a tab, or a split per its `placement`) and prints the terminal's id. Context as for `run`.
`history`	Recent runs, oldest first, with their status, exit code and the tail of their output. `--limit <n>` keeps the newest `n`.

<command> and <view> are a name, or <plugin_id>:<name> when two plugins share it.

add, remove, on, off and list work on the registry at ~/.beswarm/plugins/registry.json, so they need no session. run, view and history talk to the running TUI, on the session in --session, else $BESWARM_SESSION (set for every plugin run), else default.

beswarm plugin add ~/code/notes-plugin
beswarm plugin list
beswarm plugin run save
beswarm plugin run example.notes:save
beswarm plugin view board
beswarm plugin history example.notes --limit 5

Error codes: plugin_not_found, plugin_disabled, plugin_unavailable (its manifest is gone; add it again), plugin_action_not_found (no such command or view), plugin_action_ambiguous (use <plugin_id>:<name>), plugin_platform_unsupported, plugin_command_limit_reached (the plugin already has 4 runs going), plugin_view_already_open (a single view of that plugin is open; it gets focus instead).

sound

beswarm sound list
beswarm sound play --sound <sound_id>|<name>|default [--wait]
beswarm sound set-default --sound <sound_id>|<name>

The sounds ship inside the binary, and these commands read the session's saved state, so no running TUI is needed; --session picks whose default to use. sound list marks the session default with *; "no sound" is listed without an id. --wait keeps the process alive until playback ends. Set a default with the session's TUI closed, or it's overwritten on the next save. On Linux, sounds play through pw-play, paplay or aplay, whichever is installed.