Band Band

Running Your First Task

A "task" in Band is a message you send to a coding agent in one of a workspace's chat panes. When you send the message, Band dispatches it to the agent, which works inside the workspace's git worktree. You can watch the agent's progress in real time from the dashboard or your terminal.

Prerequisites

Before sending your first message, make sure you have:

  • A registered project in Band.
  • A workspace created for that project.
  • A coding agent (such as Claude Code, Codex, or OpenCode) installed and detected by Band.

Send a message via the dashboard

  1. Open the Band dashboard and select a workspace from the sidebar.
  2. In the workspace view, focus the chat panel.
  3. Type your prompt describing what you want the agent to do.
  4. Press Enter (or click Send) to dispatch the message.

Band lazy-creates a "Chat" pane the first time a workspace receives a message, then reuses it for follow-ups. The agent's output streams into the pane in real time.

Send a message via the CLI

To submit a prompt from your terminal, change into the workspace directory and use band chats send. The workspace and chat pane are auto-detected from your current working directory: 

cd ~/.band/worktrees/my-app/feat-validation
band chats send --message "Add input validation to all API endpoints"

If you're not inside the workspace's directory, pass the workspace ID explicitly: 

band chats send --workspace ws_abc123 --message "Add input validation to all API endpoints"

A common one-shot pattern is to create a workspace and kick off the agent in a single command. band workspaces create accepts a --prompt flag that creates the worktree, registers the workspace, and queues the message in its first chat pane: 

band workspaces create my-app feat/validation \
  --prompt "Add input validation to all API endpoints"

Chat status

Every chat pane goes through these states (visible as colored dots in the sidebar):

  • Waiting — The chat is idle. No task is running.
  • Running — The agent is actively working on a message.
  • Completed — The last task finished successfully.
  • Failed — The last task ended with an unrecoverable error.

Claude Code chats also display needs attention when the agent calls AskUserQuestion or ExitPlanMode. See Agent Status for the full hook flow.

Watching progress

The dashboard shows chat output in real time. From the CLI, you can stream the same NDJSON event feed with band chats watch: 

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

# Filter for text deltas only
band chats watch | jq -r 'select(.type == "text-delta") | .delta'

# Target a specific chat pane
band chats watch chat_abc

band chats watch exits immediately if no task is running, so it's safe to invoke right after band chats send.

Managing chats

band chats list                       # chats in the cwd workspace
band chats list --output json | \
  jq '.chats[] | select(.status == "running")'   # filter by status
band chats stop                       # abort the current task in the active chat
band chats remove                     # delete the chat pane (kills the agent)

Running multiple tasks in parallel

Because each workspace is an isolated git worktree, you can run multiple agents across different workspaces simultaneously without file conflicts: 

band workspaces create my-app feat/auth  --prompt "Implement OAuth2 login flow"
band workspaces create my-app feat/api   --prompt "Add pagination to all list endpoints"
band workspaces create my-app fix/tests  --prompt "Fix the 12 failing integration tests"

You now know the core Band workflow: register a project, create a workspace, and chat with an agent inside it. From here you can explore project configuration with .band/config.json, remote tunnels, and cronjobs.