agent

beswarm agent inspects and drives the coding agents in a session. Most subcommands talk to a running session over its control socket; kinds, manifests and explain <agent> --file work without one.

Run beswarm agent with no subcommand to print the manual for your installed version.

Inspect

beswarm agent list [--json]
beswarm agent get <target> [--json]
beswarm agent read --name <name> [--source <source>] [--lines <n>] [--ansi]

list orders agents by tab, like the tab bar, and includes agents still launching.

read sources:

Source	What it returns
`visible`	What the user sees.
`recent`	The last `--lines` lines (default 80, max 1000). The default source.
`recent-unwrapped`	The same with soft wraps rejoined. Use it for anything that parses the text.
`detection`	Exactly what the detector reads.

Add --ansi when colors and styling matter.

Start

beswarm agent start --name <name> [--agent <kind>] [<terminal> | --new] [--group <group>]
                    [--skill <dir> | --skill-id <id>] [--model <model>]
                    [(--prompt <text> | --prompt-id <id>) [--wait] [--timeout <s>]]
                    [-- <args>...]

Without a terminal id (or with --new, which says so explicitly) it opens a new tab. A given terminal must be at a shell prompt. A new tab is refused (invalid_request) while a worktree is selected in the sidebar; pass the worktree's terminal id instead.
It waits until the agent is ready for input. The new tab takes focus unless --no-focus is given.
--agent default, or omitting --agent, launches the session's default agent.
--model <model> is passed to the agent as its own --model <model> flag, ahead of any -- args. Omit it and the agent uses its default model.
--skill <dir> tells the agent to read and follow that skill (the folder must contain SKILL.md; a leading ~/ is expanded); that turn finishes before any --prompt is sent.
--wait applies to the --prompt turn, or to the skill turn when there's no prompt.
--auto-skills (requires --prompt) asks the agent to find a suitable skill in beswarm skill list.
--prompt-id and --skill-id use ids from beswarm prompt list and beswarm skill list.
Autoload skills and prompts are only sent with --autoload.
Native agent arguments go after --.

beswarm agent start --name api --agent claude --prompt "fix the build" --wait
beswarm agent start --name api --agent pi --model <model> --prompt "Research X" --wait
beswarm agent start --name api --skill-id 2 --prompt-id 3

Prompt and wait

beswarm agent prompt --prompt "Review the diff" --name api --wait --timeout 600
beswarm agent prompt --prompt-id 3 --name api --wait
beswarm agent wait api --until idle,done,blocked --timeout 300

--wait first confirms the agent took the prompt, then waits for the turn to end. --until defaults to idle,done,blocked; wait exits 1 with timeout if none is reached. A timeout doesn't prove the prompt was never delivered — don't blindly resend it.

Answer a blocked agent

beswarm agent read --name api --source visible
beswarm agent send-keys --name api --keys down,enter

Keys are ctrl+c, enter, down, f5 or a single character, comma-separated or as repeated --keys. Every key is parsed before any is sent, so a bad name sends nothing.

Stop, close, rename, focus

beswarm agent stop --name <name> [--timeout <s>]
beswarm agent close --group <group> [--timeout <s>]
beswarm agent rename <target> <name>
beswarm agent focus <target>

stop sends SIGTERM to the agent's foreground process group, then SIGKILL after the timeout (default 5s). The tab stays at a shell prompt; follow with terminal close to close it too.
close --group stops every agent in the group and closes its terminals. --group default closes everything nobody grouped. One member failing doesn't abandon the rest.
rename with an empty name clears it.

Detection

beswarm agent kinds
beswarm agent manifests
beswarm agent explain <agent> [--file <path>] [--json]
beswarm agent explain --target <target> [--json]

explain <agent> reads the screen snapshot from --file or stdin. --target runs it against a live agent, using exactly the bytes its detector sees.

See Agents & statuses.

Targets and exit codes

<target> is a terminal id or an agent name — never an agent kind.
Exit codes: 0 success, 1 a command that ran and failed (for example timeout), 2 usage error.
--json on list, get and explain prints the full result as JSON; failures name a code a script can branch on.