Band Band

Architecture

Band is composed of three main components: a desktop application, a web server, and a CLI. Each component has a distinct responsibility, and they communicate over HTTP and WebSocket.

System Overview

  • Desktop App (Tauri) — Window management, app launching, and native OS integration.
  • Web Server (Node.js) — Data management, state, API, and background processes.
  • CLI (Rust) — Command-line interface for scripting and automation.

Separation of Concerns

The web server handles data, state, and background processes exclusively. It never performs window management — no spawning editors, no AppleScript, no opening or focusing IDE windows.

Window management is the desktop app's responsibility. When a workspace is focused, the desktop app reads the configuration and handles launching editors, positioning windows, opening terminal tabs, and managing IDE focus. This separation ensures the web server can run headlessly (e.g., on a remote machine) while the desktop app manages the local desktop environment.

Git Worktree-Based Workspace Isolation

Each workspace is backed by a Git worktree. When you create a workspace, Band runs git worktree add to create an isolated working directory with its own branch. This provides:

  • File isolation — Each workspace has its own copy of the project files.
  • Branch isolation — Each workspace works on its own Git branch.
  • Concurrent work — Multiple agents can work on different tasks simultaneously without conflicts.
  • Efficient storage — Git worktrees share the object database, so disk usage is minimal.

Worktrees are stored in the Band home directory at ~/.band/worktrees/<project>/<workspace>.

SQLite for State

All application state is stored in a local SQLite database at ~/.band/band.db. This includes projects, workspaces, tasks, cron jobs, and tunnel configuration. SQLite was chosen for its simplicity, reliability, and zero-configuration nature — no external database server is needed.

tRPC API (HTTP + WebSocket)

The web server exposes a tRPC API that supports both HTTP (for request/response operations) and WebSocket (for real-time streaming). The API is used by:

  • The web dashboard (browser client).
  • The desktop app (Tauri frontend).
  • The CLI (via HTTP requests).
  • IDE extensions (for status reporting).

tRPC provides end-to-end type safety between the server and TypeScript clients, ensuring the API contract is enforced at compile time.

Agent Adapter Pattern

Band uses an adapter pattern to support different AI agents. Each agent implementation (e.g., Claude Code) is wrapped in an adapter that translates between Band's task model and the agent's specific interface. This allows Band to:

  • Start and stop agent processes.
  • Stream agent output to the dashboard in a uniform format.
  • Support multiple agent backends without changing the core system.

Status Protocol

Communication between IDE extensions and the Band dashboard uses a file-based status protocol. Each workspace has a .band/status.json file that the IDE extension writes to and the server watches. 

{'{'}
  "agent": "claude-code",
  "status": "working",
  "task": "Implementing dark mode toggle",
  "updatedAt": "2025-12-01T10:30:00Z"
{'}'}

This file-based approach was chosen for its simplicity and compatibility — any IDE extension or agent wrapper can write a JSON file, regardless of the programming language or runtime.

Data Flow

  1. User creates a task via dashboard, CLI, or cron job.
  2. Server stores the task in SQLite and spawns an agent process in the workspace.
  3. Agent works in the Git worktree, making file changes and running commands.
  4. Agent output is streamed via WebSocket to connected dashboard clients.
  5. IDE extension updates .band/status.json; server detects changes and broadcasts status.
  6. Desktop app handles window focus and positioning when the user switches workspaces.