Running Your First Task

A task in Band is a prompt sent to a coding agent that runs inside a specific workspace. When you create a task, Band dispatches your prompt to the agent, which then 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 creating a task, make sure you have:

• A registered project in Band.
• A workspace created for that project.
• A coding agent (such as Claude Code) installed and configured on your machine.

Create a task via the dashboard

1. Open the Band dashboard and select a workspace from the sidebar.
2. In the workspace view, find the task input area.
3. Type your prompt describing what you want the agent to do.
4. Click Submit to dispatch the task.

The task appears in the workspace view and begins executing immediately. You can see the agent's output streaming in real time as it works through your prompt.

Create a task via the CLI

To submit a task from your terminal, use the band tasks create command with the workspace ID and a prompt:

band tasks create <workspace_id> --prompt "Fix the failing tests in the auth module"

The command returns the task ID, which you can use to watch or manage the task. In most cases, you want to create a workspace and start a task at the same time. The workspaces create command supports a --prompt flag that does both in a single step:

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

This is the recommended approach — it creates the workspace, sets up the worktree, and immediately dispatches the task so the agent starts working without delay.

Task lifecycle

Every task goes through a defined set of states:

• Running — The agent is actively working on the task. You can see its output streaming in real time.
• Completed — The agent finished the task successfully. You can review the changes it made in the workspace.
• Failed — The agent encountered an error and could not complete the task. Check the output log for details.

Watching task progress

The dashboard shows task output in real time as the agent works. From the CLI, you can stream the output using the watch command:

band tasks watch <task_id>

Or watch the latest task for a specific workspace:

band tasks watch --workspace ws_abc123

The watch command streams output to your terminal until the task completes or you press Ctrl+C.

Managing tasks

The CLI provides commands to list, cancel, and re-run tasks:

band tasks list                    # all tasks
band tasks list --status running   # only running tasks
band tasks cancel <task_id>        # stop a running task
band tasks rerun <task_id>         # re-run a completed or failed task

Running multiple tasks in parallel

Because each workspace is an isolated git worktree, you can run multiple tasks 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 dispatch a task. From here you can explore project configuration with .band/config.json, remote tunnels, and team workflows.