Project Management

Projects in Band represent git repositories that you want to manage with coding agent workspaces. Every project must be a valid git repository. Band does not create or modify your repositories — it simply registers them and manages worktrees within them.

Adding Projects

There are two ways to register a project with Band:

From the Dashboard UI

Click the + button in the top-right corner of the dashboard toolbar. A dialog will appear where you can select a directory. Band validates that the selected path is a git repository and detects the default branch automatically.

From the CLI

Use the band projects add command to register an existing git repository:

band projects add /path/to/your/repo
band projects add /path/to/your/repo --label my-label

The CLI detects the repository name and default branch. You can optionally assign a label at registration time using the --label flag.

Removing Projects

Removing a project from Band unregisters it from the dashboard. It does not delete the repository or any of its files. You can remove a project by:

• Right-clicking the project name and selecting Remove from list.
• Entering edit mode (via the settings menu) and clicking the trash icon next to the project.
• Using the CLI: band projects remove <name>

Reordering Projects

To reorder projects in the sidebar, open the settings menu and select Edit list. This enables edit mode, which shows drag handles next to each project name. Drag projects up or down to rearrange them. The new order is persisted automatically. Click Done editing when finished.

Labels and Filtering

Projects can be organized using color-coded labels. Labels are created in the Settings page, and then assigned to projects via the right-click context menu.

• Right-click a project name to see the Set label submenu.
• Select a label to assign it, or choose None to remove the label.
• Use the label filter dropdown in the toolbar to show only projects with a specific label.
• When labels are defined, projects are visually grouped by label with colored section headers.

You can also drag projects between label groups in edit mode to reassign labels quickly.

Project Configuration

Each project can have a .band/config.json file in its repository root. This file configures per-project behavior such as which applications to open when focusing a workspace, and setup/teardown scripts.

{
  "apps": [
    {
      "type": "vscode",
      "terminals": [
        { "name": "claude", "command": "band tasks watch && claude --continue" },
        { "name": "shell", "command": "", "split": "vertical" }
      ]
    },
    { "type": "iterm" },
    { "type": "chrome", "url": "http://localhost:3000" }
  ],
  "setup": "npm install",
  "teardown": "docker compose down"
}

The setup script runs automatically after a workspace is created. The teardown script runs before a workspace is removed. Both are non-fatal — if they fail, the operation continues.

Context Menu

Right-clicking a project name reveals additional actions:

• Set label — Assign or remove a color-coded label.
• Copy path — Copy the project's filesystem path to the clipboard.
• Open in Finder — Reveal the project directory in Finder.
• Remove from list — Unregister the project from Band.