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, its own working directory, and its own agent session.

List Workspaces

Display all workspaces across all projects, or filter by project.

band workspaces list

Example output:

ID   Project    Name             Branch                    Status
1    my-app     fix-auth-bug     ws/fix-auth-bug           active
2    my-app     add-dark-mode    ws/add-dark-mode          active
3    my-app     refactor-api     ws/refactor-api           idle
4    api-server update-deps      ws/update-deps            active

Create a Workspace

Create a new workspace in a project. Band will create a Git worktree with a new branch and set up the isolated environment. 

band workspaces create --project my-app --name fix-auth-bug

The workspace directory is created at .band/worktrees/<project>/<name> inside the Band home directory. A new Git branch is created from the project's current HEAD.

Options:

  • --project <name> — The project to create the workspace in (required).
  • --name <ws-name> — A descriptive name for the workspace (required).

Remove a Workspace

Remove a workspace by its ID. This deletes the Git worktree directory and removes the workspace record from Band's database. 

band workspaces remove 2

Active tasks in the workspace will be cancelled before removal. The Git branch created for the workspace is not deleted automatically — you can still merge or reference it.

JSON Output

band workspaces list --output json

Example JSON output:

[
  {'{'}
    "id": 1,
    "project": "my-app",
    "name": "fix-auth-bug",
    "branch": "ws/fix-auth-bug",
    "path": "/Users/dev/.band/worktrees/my-app/fix-auth-bug",
    "status": "active"
  {'}'}
]

Notes

  • Workspace names must be unique within a project.
  • Each workspace has its own isolated file system via Git worktrees.
  • Workspaces persist across restarts — they are stored in SQLite and the worktree stays on disk.
  • Use the dashboard or band tasks to assign work to a workspace.