Band Band

Workspace Management

Workspaces in Band are git worktree-based isolated environments for each branch you work on. Every workspace gets its own directory on disk with a full copy of the repository at the specified branch, allowing you to work on multiple branches simultaneously without switching contexts.

Creating Workspaces

You can create a new workspace from the dashboard or the CLI. Each workspace corresponds to a git worktree branch.

From the Dashboard

Click the + button next to a project name. A dialog appears with three fields:

  • Branch name — The name of the new branch (e.g., feature/auth).
  • Base branch (optional) — The branch to base the new worktree on. Defaults to the project's default branch.
  • Initial prompt (optional) — A task prompt for the coding agent. If provided, the agent starts working immediately after workspace creation.

From the CLI

# Create workspace and start an agent task immediately
band workspaces create my-app feat/login --prompt "Implement login page"

# Create workspace without starting a task
band workspaces create my-app feat/experiment

# Create from a specific base branch
band workspaces create my-app feat/api --base develop

Workspace creation is idempotent — creating an existing workspace simply returns its path without duplicating anything.

Workspace List

Workspaces appear nested under their parent project in the dashboard. Each workspace card displays:

  • Branch name — The git branch this workspace tracks.
  • Agent status indicator — A colored dot showing whether the coding agent is working or needs attention. See Agent Status.
  • Setup status — Shows whether the setup script is running, completed, or failed.
  • Git status — Indicates dirty files, unpushed commits, and sync state (ahead, behind, diverged).
  • CI status — Shows the current CI pipeline state (pending, running, success, failure, cancelled, merged).

Focusing a Workspace

Clicking a workspace opens it — Band positions and focuses the configured IDE windows for that workspace. The active workspace is highlighted with a left border accent. See Window Management for details on how windows are arranged.

Removing Workspaces

You can remove a workspace from the context menu (right-click) or via the CLI: 

band workspaces remove my-app feat/login

Before removal, Band runs the project's teardown script if one is defined in .band/config.json. The teardown script is non-fatal — removal proceeds even if it fails.

If the workspace has unmerged pull requests, dirty files, or unpushed commits, a confirmation dialog appears warning you about potential data loss. You must explicitly confirm deletion in these cases.

Workspace Context Menu

Right-clicking a workspace reveals additional actions:

  • Copy path — Copy the worktree path to clipboard.
  • Open in Finder — Reveal the worktree directory.
  • Run setup — Manually re-run the setup script (only shown if a setup script is defined).
  • Run teardown — Manually run the teardown script.
  • Git pull — Pull the latest changes for this branch.
  • Git push — Push local commits to the remote.
  • Delete workspace — Remove the workspace and its worktree (not available for the default branch).

Naming Conventions

Workspace names are derived from their branch names. Band supports standard git branch naming conventions including slashes for namespacing (e.g., feature/auth, fix/bug-123). Branch names must not contain control characters or path traversals (../).

Worktree directories are stored in the configured worktrees folder (default: ~/.band/worktrees), organized by project name and branch.