Band Band

band workspaces

The band workspaces command group manages workspaces within projects. A workspace is an isolated working environment backed by a Git worktree. Each workspace gets its own branch and working directory, and acts as the scope for chat panes, terminals, browser tabs, and cronjobs.

List workspaces

Display all workspaces across all projects, or filter to a single project.

band workspaces list
band workspaces list my-app

Example output:

PROJECT     BRANCH            WORKSPACE ID    PATH
my-app      fix-auth-bug      ws_abc123       /Users/dev/.band/worktrees/my-app/fix-auth-bug
my-app      add-dark-mode     ws_def456       /Users/dev/.band/worktrees/my-app/add-dark-mode
api-server  update-deps       ws_ghi789       /Users/dev/.band/worktrees/api-server/update-deps

Create a workspace

Create a new workspace in a project. Band will create a Git worktree with a new branch and (if the project has a setup command in .band/config.json) run setup automatically. 

band workspaces create <project> <branch>

Both arguments are positional. Examples:

band workspaces create my-app fix-auth-bug
band workspaces create my-app add-dark-mode --base main
band workspaces create my-app review --prompt "Review this PR" --agent claude-code

The worktree is created at ~/.band/worktrees/<project>/<branch> by default (the parent directory is the configurable worktreesDir setting). The new branch is created from the project's default branch unless you pass --base.

Options:

  • project (positional, required) — name of a registered project.
  • branch (positional, required) — name of the branch to create.
  • --base <branch> — base branch (defaults to the project's default branch).
  • --prompt <text> — kick off a chat in the new workspace with this initial prompt.
  • --agent <id>, --model <name>, --mode <mode>, --max-turns <n> — agent overrides for the initial prompt.

Remove a workspace

Remove a workspace by <project> <branch>. This deletes the Git worktree directory, removes the workspace record from Band's database, and runs the project's teardown command if one is configured. 

band workspaces remove my-app fix-auth-bug

Running tasks in the workspace are aborted before removal. The Git branch itself is not deleted from the project repository — you can still merge or reference it.

JSON output

band workspaces list --output json

Example JSON output:

{
  "workspaces": [
    {
      "project": "my-app",
      "branch": "fix-auth-bug",
      "workspaceId": "ws_abc123",
      "path": "/Users/dev/.band/worktrees/my-app/fix-auth-bug"
    }
  ]
}

Notes

  • Branch names must be unique within a project.
  • Each workspace has its own isolated file system via Git worktrees, so concurrent agents on different branches don't conflict.
  • Workspaces persist across restarts — they are stored in SQLite and the worktree stays on disk.
  • Use band chats send from inside the workspace directory to drive an agent.