band-chat

Band Chats

All chat operations live under a single band chats <subcommand> group: list/create/send/watch/stop/remove.

The primary way to drive a coding agent from the CLI is band chats send — it sends a message to a workspace's active chat panel (auto-detected from cwd) and lazy-creates a "Chat" panel if the workspace has none.

Chat panes are agent processes attached to a Band workspace. Each chat pane has its own conversation history and can run a different agent, model, or mode.

This skill is focused on chat pane management only. For broader operations see the sibling skills:

• band — workspaces, projects, cronjobs, tunnel, settings.
• band-terminal — terminal sessions inside a workspace.
• band-browser — browser tabs inside a workspace.

Prerequisites

The Band server must be running (started by the Band dashboard app). Connects to http://localhost:3456 by default. See the band skill for general setup and the workspace lifecycle.

JSON Output

All commands support --output json (or BAND_OUTPUT=json env var) for structured output.

• Success: JSON object to stdout, exit code 0
• Error: {"error": "message"} to stderr, exit code 1

Commands

List chat panes for a workspace

band chats list [workspace_id]

Text output: ID\tNAME\tAGENT\tSTATUS\tLABELS (space-padded table; LABELS renders as k=v,k=v and is empty when the chat has no labels). JSON output: {"chats": [{"id": "...", "name": "...", "agent": "...", "status": "...", "labels": {"k": "v"}}]}. The band: key prefix is reserved for server-internal labels (e.g. band:cronId set by the cronjob scheduler when it owns a chat) and is not user-settable.

Create a new chat pane in a workspace

band chats create [workspace_id] [--name <string>] [--agent <string>] [--model <string>] [--mode <string>] [--label <string>]

Creates a new independent chat pane with its own agent process. Returns the chat ID. JSON output: {"chat": {"id": "...", "name": "...", "agent": "...", "status": "idle", "labels": {"k": "v"}}}