Band Band

band chats

The band chats command group manages chat panes inside a workspace. A chat pane is an agent process bound to a workspace — it has its own conversation history and can run a different coding agent, model, or mode from any other pane in the same workspace. band chats send is the primary way to drive an agent from the CLI: it sends a message to the workspace's active chat panel, lazy-creating one if the workspace has none yet.

Default workspace and chat resolution

Every band chats subcommand auto-detects the workspace from the current working directory (matched against registered workspace paths) when no workspace is given, and resolves to the workspace's active chat panel when no chat ID is given. From inside a workspace, you typically just run band chats send --message "…" — no IDs to type. Pass an explicit ID only when you're outside the workspace's cwd or you want to target a specific chat.

List chats

List chat panes for a workspace (defaults to the cwd workspace).

band chats list
band chats list ws_abc123        # explicit workspace ID

Create a chat pane

band chats create                       # cwd workspace, default agent
band chats create --name "planning" --agent claude-code \
  --model claude-opus-4-20250514 --mode plan

Options:

  • workspace_id (positional, optional) — auto-detected from cwd if omitted.
  • --name — display name for the chat pane.
  • --agent — agent type (e.g. claude-code, codex, opencode).
  • --model — model override.
  • --mode — agent mode (e.g. plan, edit).

Send a message

The most common command. Sends a prompt to the chat pane and starts a new task. Output streams to the dashboard; use band chats watch to follow it from the CLI. 

# From inside a workspace directory: workspace and chat auto-resolved.
band chats send --message "Fix the failing tests"

# Outside the workspace's cwd
band chats send --workspace ws_abc123 --message "Fix the failing tests"

# Target a specific chat pane instead of the active one
band chats send chat_abc --message "Investigate the perf regression"

# Override agent / model / mode for one-off prompts
band chats send --mode plan --model claude-opus-4-20250514 \
  --message "Plan the migration to v2 of the auth API"

Options:

  • chat_id (positional, optional) — defaults to the workspace's active chat.
  • --message <text> — the message to send (required).
  • --workspace <id> — override the auto-detected workspace.
  • --max-turns, --mode, --model, --agent — per-message overrides.

Watch a chat's running task

Stream the chat's running task as raw NDJSON to stdout. Exits immediately with no output if the chat has no running task, so it's safe to invoke speculatively after band chats send. 

# Stream the cwd workspace's first chat pane
band chats watch

# Pipe through jq for live filtering — only text deltas
band chats watch | jq -r 'select(.type == "text-delta") | .delta'

# Target a specific chat
band chats watch chat_abc

Stop a chat's running task

Abort the running task in a chat pane. The agent process is signalled and the chat status flips to completed.

band chats stop                  # cwd workspace's first chat
band chats stop chat_abc

Remove a chat pane

Permanently remove a chat pane and its agent process.

band chats remove                # cwd workspace's first chat
band chats remove chat_abc

JSON output

band chats list --output json
band chats list --output json | jq '.chats[] | select(.status == "running")'

Chat status

  • waiting — Idle. The chat exists but no task is running.
  • running — Agent is actively working on a task.
  • completed — The last task finished successfully.
  • failed — The last task ended with an unrecoverable error.