Band Band

Settings

The Settings page in Band lets you configure global preferences that apply across all projects and workspaces. Access it by clicking the gear icon in the dashboard toolbar and selecting Settings.

Settings are organized into sections. Each section has a dedicated page with a save button. A blue indicator dot appears on the save button when you have unsaved changes.

Appearance

Controls the visual theme of the Band dashboard:

  • System — Follows your operating system's light/dark mode preference. Updates automatically when your OS theme changes.
  • Light — Forces a light color scheme.
  • Dark — Forces a dark color scheme.

You can also cycle through themes using the theme toggle button in the dashboard toolbar without opening Settings.

General

The General section contains core configuration:

  • Worktrees folder — The directory where new git worktrees are created. Defaults to ~/.band/worktrees. You can change this to any directory, for example if you want worktrees on a faster drive or a specific location. Use the browse button to pick a folder via the native file picker.

Labels

Labels let you organize projects into color-coded groups. From this section you can:

  • Add labels — Click the Add label button to create a new label with a default name and color.
  • Edit labels — Change the name and color of any existing label. Click the color swatch to open a color picker.
  • Delete labels — Click the trash icon to remove a label. Projects assigned to a deleted label become unlabeled.

Once labels are created, assign them to projects via the right-click context menu on any project name in the dashboard. Use the label filter in the toolbar to show only projects with a specific label.

Coding Agent

Configure the coding agent used for background tasks:

  • Agent type — Select the coding agent. Currently supports Claude Code. Set to "None" to disable agent task submission.
  • Command (optional) — A custom command to launch the agent. For example, claude --dangerously-skip-permissions. Leave empty to use the default command for the selected agent type.

Workspace Settings (Defaults)

Define the default apps configuration that applies to workspaces when no project-level .band/config.json exists. This is entered as a JSON object.

Click Insert template to populate the field with a standard VS Code configuration: 

{
  "apps": [
    {
      "type": "vscode",
      "terminals": [
        {
          "name": "claude",
          "command": "band tasks watch && claude --continue"
        },
        {
          "name": "shell",
          "command": "",
          "split": "vertical"
        }
      ]
    }
  ]
}

This default opens VS Code with two terminal splits: one running the coding agent and another as a general shell. See Window Management for the full configuration reference.

Notifications

Configure audio notifications for agent events:

  • Notification sound toggle — Enable or disable playing a sound when an agent transitions from working to needs attention.
  • Sound selection — Choose from several built-in sounds. Selecting a sound plays a preview so you can hear it before saving.

Web Server

Configure the Band web server that powers the dashboard and provides the API:

  • Port — The port the web server listens on. Defaults to 3456. Changing this requires a restart.
  • Auto-start tunnel — When enabled, automatically starts a remote tunnel when the app launches, making your Band instance accessible from mobile devices or other machines.

Settings Storage

All settings are persisted in ~/.band/settings.json. You can view the current settings via the CLI: 

band settings
band settings --output json

While you can edit the file directly, it is recommended to use the Settings UI to avoid malformed JSON or invalid values.