Project Configuration

Each Band project can include a .band/config.json file at the repository root. This file defines how workspaces should be set up, which applications to open, and what scripts to run during workspace lifecycle events.

File Location

The configuration file lives at <project-root>/.band/config.json. It is committed to the repository so that all team members share the same workspace setup.

Schema

The top-level structure of the configuration file:

{'{'}
  "setup": ["npm install", "npm run db:migrate"],
  "teardown": ["npm run db:reset"],
  "apps": [
    {'{'}
      "preset": "cursor",
      "position": "left-half"
    {'}'},
    {'{'}
      "preset": "terminal",
      "position": "right-half",
      "commands": [
        {'{'}
          "command": "npm run dev",
          "name": "dev-server"
        {'}'},
        {'{'}
          "command": "npm run test:watch",
          "name": "tests",
          "split": true
        {'}'}
      ]
    {'}'}
  ]
{'}'}

Setup Scripts

The setup array contains shell commands that run when a workspace is created or first focused. These commands execute sequentially in the workspace directory.

"setup": [
  "npm install",
  "npm run db:migrate",
  "cp .env.example .env"
]

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

Teardown Scripts

The teardown array contains shell commands that run when a workspace is removed. Use these for cleanup tasks like stopping background services or resetting databases.

"teardown": [
  "docker compose down",
  "npm run db:reset"
]

Apps Array

The apps array defines which applications to open and how to position them when a workspace is focused. Each entry specifies a preset and optional positioning.

See App Presets for the full list of supported presets.

Position Values

• left-half — Left half of the screen.
• right-half — Right half of the screen.
• fullscreen — Full screen.
• top-half — Top half of the screen.
• bottom-half — Bottom half of the screen.

Terminal Presets

Terminal presets support a commands array that defines terminal tabs and splits.

{'{'}
  "preset": "terminal",
  "commands": [
    {'{'}
      "command": "npm run dev",
      "name": "dev-server"
    {'}'},
    {'{'}
      "command": "npm run test:watch",
      "name": "tests",
      "split": true
    {'}'}
  ]
{'}'}

• command — The shell command to run in the terminal.
• name — A label for the terminal tab.
• split — If true, opens as a split pane instead of a new tab.

Full Example

{'{'}
  "setup": [
    "npm install",
    "npx prisma db push",
    "cp .env.example .env.local"
  ],
  "teardown": [
    "docker compose down -v"
  ],
  "apps": [
    {'{'}
      "preset": "cursor",
      "position": "left-half"
    {'}'},
    {'{'}
      "preset": "terminal",
      "position": "right-half",
      "commands": [
        {"{"} "command": "npm run dev", "name": "dev" {'}'},
        {"{"} "command": "npm run test:watch", "name": "test", "split": true {'}'}
      ]
    {'}'}
  ]
{'}'}