Band Band

band worktrees

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

List worktrees

Display all worktrees across all repos, or filter to a single repo.

band worktrees list
band worktrees list my-app

Example output:

REPO     BRANCH            WORKTREE 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 worktree

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

band worktrees create <repo> <branch>

Both arguments are positional. Examples:

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

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

Options:

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

Remove a worktree

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

band worktrees remove my-app fix-auth-bug

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

JSON output

band worktrees list --output json

Example JSON output:

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

Notes

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