Using the TUI

Bare beswarm opens the TUI: a sidebar on the left, terminals on the right. Everything here can also be driven from the CLI; this page covers the mouse and keyboard side.

Layout

Area	What it holds
Sidebar, top	Two tabs: Workspaces (each workspace, with its worktrees as sub-items) and Artifacts.
Sidebar, bottom	Five panels: Agents, Skills, Tools, Prompts and Plugins, over a status bar counting agents `working`, `blocked` and `idle`.
Terminal area	The selected workspace's tab bar, and the panes of the current tab.
Menu	Opened from the sidebar footer, the title bar or `f9`: Settings and Reload.

Most things have a right-click menu. Right-click a panel's own tab for Filter.

Keybindings

The same list is in Settings → Keybinds.

Key	Action
`ctrl+t`	New tab
`ctrl+w`	Close pane (closes the tab if it's the last pane)
`ctrl+←` / `ctrl+→`	Previous / next tab
`alt+←` / `alt+→`	Adjust sidebar width
`f1`	Toggle focus between sidebar and terminal
`f2`	Hide / show sidebar
`f9`	Open menu
`ctrl+q`, `f10`	Close the TUI (agents keep running)

Panes

Key	Action
`f5`	Split right
`f6`	Split down
`f7`	Zoom pane
`f4`	Next pane
click	Focus pane
drag border	Resize panes
right-click	Pane menu: Rename pane, Split right, Split down, Close pane

Key	Action
`↑` / `↓`, `j` / `k`	Move up / down
`↵`	Open workspace
`tab`	Switch between workspace list and bottom panel
`←` / `→`	Switch bottom panel tab
`/`	Search workspaces, artifacts or the bottom panel
`pgup` / `pgdn`	Scroll sidebar
`[` / `]`	Resize the sidebar split

Clipboard

Drag to select terminal text; releasing copies it. cmd+v / ctrl+v pastes into the terminal.

Workspaces and worktrees

A workspace or worktree with a working agent shows a blinking yellow dot in front of it, as does the collapsed sidebar.

Right-click a workspace for Rename, Tags and Close. On a git repository you also get New worktree and Open worktree; see Worktrees. When a plugin adds commands or views to this menu (menu = "workspace" in its manifest), a last Plugins › row lists those plugins, each with its items.

A ⑂ after a repository's branch means it has linked worktrees, whether or not any is open in a tab.

A worktree with open terminals shows as a sub-item on two rows: its name, then its pane's current directory. Right-click it for Close (terminals only, the checkout stays) or Remove worktree. A worktree keeps the one terminal it was opened with, so New tab is refused there; split the pane instead.

Switching to another workspace or worktree and back returns you to the pane you last used there.

Right-click a terminal tab for New tab, Rename, Open Folder (the tab's current directory in the system file manager) and Close.

Agents panel

Lists every recognized agent in the session with its status.

An agent started from inside another agent's terminal — for example an orchestrator running beswarm agent start — is nested under it. Agents with sub-agents get a button after the status: ▼ shows them, ▲ folds them away.

Double-click a count in the status bar under the panels (2 working, 1 blocked, 3 idle) to jump to the next agent in that state; repeat to cycle through them in panel order.

Right-click an agent for Close. It closes the agent's tab and every agent nested under it; the confirmation says how many sub-agents go with it.

Skills panel

Skills are grouped under the root they were found in (skill roots). Click a skill for Run, View and Manage ›, which holds Tags and Autoload:

Item	What it does
Run	Tells the agent in the focused pane to read and follow the skill. With no agent there, it asks, then launches the default agent with the skill.
View	Opens `SKILL.md` in a pager in a new tab.
Tags	Tag the skill.
Autoload	Send this skill to agents as they start (see Autoload). Shows `✓` when on.

A * in place of a skill's bullet means it was autoloaded into the agent in the focused pane.

Right-click a root header, such as ~/.beswarm/skills, for Filter, Open Folder (system file manager) and Open in Terminal (new tab in that folder).

Prompts panel

Lists the files in ~/.beswarm/prompts. Click a prompt for Run, Copy, Autoload and Manage ›, which holds Edit, Rename, Tags and Remove. Double-click runs it.

Run with an agent in the focused pane submits the prompt's text to it.
Run in a pane with no agent asks first, then types beswarm agent start --agent default --name <name> --prompt … into the pane. The new agent opens in its own tab, named after the prompt file. A pane running something other than its shell, such as a plugin view, gets a new tab in the selected workspace instead.
Edit opens the file in $EDITOR (or vi) in a new tab.
Remove deletes the file after a y/n confirmation.

Right-click the empty panel or the Prompts tab for Filter, Open Folder (system file manager), Open in Terminal (new tab in ~/.beswarm/prompts) and Add.

Tools panel

MCP servers, in two sub-tabs: Local (agent MCP configs and ~/.beswarm/tools) and Remote (servers you add by URL). See tool list. A Local entry's menu is View, Inspect and Manage ›, which holds Add to agent, Remove from agent and Remove.

Item	What it does
View	Opens the file the entry was read from in a new tab. Double-click does the same.
Inspect	Asks the server what it offers.
Add to agent / Remove from agent	Types the agent's own command into the focused pane, so its CLI does the work.
Remove	Unregisters the entry.
Update, Test Connection	Remote only: edit the entry, or probe the server.

Right-click Local or Remote for Filter and Add. Local Add opens a file browser; Remote Add opens a form.

Plugins panel

Lists each added plugin as one item: a header with its name and version — plus off, missing (its directory is gone) or a warning count when they apply — then its labelled commands and views. ↵, a double-click or a right-click opens its menu: Run: … for each labelled command, Open: … for each view (in a new tab, or a split per its placement), then Manage ›, which holds Turn on / Turn off, Reload, History, Details and Remove. Remove asks for confirmation first.

Drag a plugin to reorder the panel; the order is saved in the registry.

Right-click the Plugins tab for Filter (or press /), Open Folder and Open in Terminal on ~/.beswarm/plugins, and Add plugin…, which asks for a plugin's path.

Artifacts

The sidebar's Artifacts tab lists files agents left in the workspace's artifacts/ and reports/, plus the global ~/.beswarm/artifacts. Click one for View (pager in a new tab) or Remove (deletes it after a confirmation).

Right-click the Artifacts tab for Filter, Open Folder and Open in Terminal on the global artifacts folder.

Settings

Open the menu (f9) → Settings.

Tab	What it holds
General	Show the splash screen on start; show memory usage (BeSwarm and every tab's processes) in the title bar.
Agents	The default agent, the agents installed on your `PATH`, and the Autoload switches and list.
Theme	21 themes, dark and light.
Sound	The sound played when an agent finishes a turn or blocks — or "no sound".
Keybinds	The keybinding reference.

Menu → Reload re-reads saved settings, the skill and prompt roots, and agent detection manifests, including any manifest override.

Autoload

Skills and prompts ticked Autoload go out as one message to each agent once it has started and is ready for input. Under Settings → Agents:

Auto learn BeSwarm's skills leads every autoload message with BeSwarm's own skill, so the agent knows how to drive BeSwarm.
Auto Load for default agent only limits autoload to the default agent.
The Auto Load list shows what's ticked; remove entries there.

beswarm agent start skips autoload unless you pass --autoload.