Your first session

This walkthrough starts a session, launches two agents on the same task group, waits for them, reads their output and cleans up.

Launch the TUI

beswarm

Bare beswarm launches the TUI, or attaches to the default session if it's already running. To keep projects apart, start a named session instead:

beswarm session start --name payments

Start two agents

From any tab — or any other terminal — start agents with unique names and a shared group:

beswarm agent kinds
beswarm --session payments agent start --name api --agent claude --group build \
  --prompt "Add rate limiting to /login" --wait
beswarm --session payments agent start --name tests --agent codex --group build \
  --prompt "Write tests for the rate limiter" --wait

Each agent start opens a new tab, waits until the agent is ready for input, sends the prompt and — with --wait — waits for that turn to finish.

See what they're doing

beswarm --session payments agent list
beswarm --session payments agent wait tests --until idle,done,blocked --timeout 300

If an agent is blocked, it's waiting on a permission prompt or chooser. Look at it before answering:

beswarm --session payments agent read --name tests --source visible
beswarm --session payments agent send-keys --name tests --keys down,enter

Read the result

beswarm --session payments agent read --name tests --source recent-unwrapped --lines 200

Clean up

beswarm --session payments agent close --group build

This stops every agent in the build group and closes its tabs.

Quit and come back

Quit the TUI whenever you like — the agents keep running. Reattach later:

beswarm session attach --name payments