Project Configuration

Each Band project can include a .band/config.json file at the repository root. This file defines shell commands that run during workspace lifecycle events. Commit it to the repository so that all team members share the same workspace setup.

File Location

The configuration file is read from <worktree-root>/.band/config.json first, falling back to <project-root>/.band/config.json. The fallback handles the common case where the config file lives on the main branch but is .gitignored, so new worktrees don't contain it.

Schema

Both setup and teardown are single shell command strings — not arrays. Each runs through bash -c, so use &&, ;, or a multi-line shell snippet to chain steps.

{
  "setup": "npm install && npm run db:migrate",
  "teardown": "npm run db:reset"
}

Setup Command

The setup command runs after a workspace is created via band workspaces create (or the dashboard equivalent). It executes inside the new worktree directory with /opt/homebrew/bin and /usr/local/bin prepended to PATH so Homebrew tools are reachable. A failed setup is reported in the dashboard but does not delete the workspace.

"setup": "npm install && npm run db:migrate && cp .env.example .env"

Use the setup command for dependency installation, database migrations, environment file creation, or any other initialization your project needs.

Teardown Command

The teardown command runs before a workspace is removed via band workspaces remove. It runs inside the worktree (which still exists at this point) and is non-fatal — a teardown failure is logged and the workspace is removed anyway.

"teardown": "docker compose down -v"

Full Example

{
  "setup": "npm install && npx prisma db push && cp .env.example .env.local",
  "teardown": "docker compose down -v"
}