Band Band

Agent Status Monitoring

Band continuously monitors the status of coding agents running in your workspaces. Agent status is displayed as a colored indicator dot on each workspace card, giving you an at-a-glance view of what every agent is doing across all your projects.

Status Types

Each workspace's coding agent can be in one of three states:

  • Waiting (no indicator) — The agent is idle. No task is running and no agent activity has been detected. No indicator dot is shown in this state.
  • Working (animated dot) — The agent is actively executing a task. The indicator uses the bg-status-working color, typically a pulsing blue or green dot. This means the agent is reading files, writing code, running commands, or otherwise making progress on its assigned task.
  • Needs attention (static dot) — The agent has finished its current task or requires human input. The indicator uses the bg-status-needs-attention color, typically amber or orange. This state means you should review the agent's output and either provide input, approve changes, or start a new task.

How Status Is Detected

Band detects agent status through Claude Code hooks. When the Band dashboard installs hooks (prompted on first launch), it registers hook handlers that fire on key Claude Code lifecycle events.

The hooks use the band notify command to send status updates to the Band server: 

echo '{"hook_event_name":"Stop","cwd":"/path/to/worktree"}' | band notify

The Band server processes these notifications and updates the agent status for the corresponding workspace. Status changes are broadcast to the dashboard in real-time via server-sent events (SSE).

Hook Events

The following Claude Code hook events are monitored:

  • Start — The agent has begun working. Transitions the workspace to the working state.
  • Stop — The agent has stopped (task completed or exited). Transitions to the needs attention state.

Status Display

Agent status is displayed in two locations:

  • Workspace list — A small colored dot appears next to the branch name in the project list. This is always visible and provides a quick summary.
  • Workspace detail view — When viewing a workspace in the web interface, the status is shown alongside other workspace metadata.

Notification Sounds

Band can play a notification sound when an agent transitions from working to needs attention. This is useful when you have multiple agents running and want to know when one finishes without constantly watching the dashboard.

To enable notification sounds, go to Settings and toggle Notification sound on. You can choose from several built-in sounds and preview them before saving.

Installing Hooks

If Claude Code hooks are not installed, the dashboard shows a setup prompt at the bottom: 

Install Claude Code hooks for agent status detection  [Install]

Click Install to set up the hooks. This configures Claude Code to send lifecycle notifications to Band automatically. The hooks are installed globally and apply to all Claude Code sessions on your machine.

Troubleshooting

  • No status showing — Make sure Claude Code hooks are installed (check the dashboard for the install prompt). Verify the Band server is running.
  • Status stuck on "working" — This can happen if the agent process was terminated without sending a stop notification. Restarting the agent or creating a new task will reset the status.
  • Hooks prompt keeps appearing — Another tool may be overwriting the Claude Code hooks configuration. Check your Claude Code settings for conflicting hook definitions.