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 these 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 and pulses while the agent is making progress — reading files, writing code, or running commands.
• Needs attention (static dot) — The agent has finished its current task or requires human input (for example, it called AskUserQuestion or ExitPlanMode). The indicator uses the bg-status-needs-attention color. 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

Five Claude Code hook events are wired up on first launch (see apps/web/src/server/services/hooks.ts):

• UserPromptSubmit — A new prompt has been sent. Transitions to working.
• PreToolUse — A tool call is about to run. Stays working in general; switches to needs attention when the tool is AskUserQuestion or ExitPlanMode, since both require a human reply.
• PermissionRequest — The agent needs permission to proceed (e.g. an unapproved tool). Stays working; the dashboard surfaces the request inline.
• PostToolUse — A tool call has finished. Stays working.
• Stop — The agent has stopped (task completed or exited). Transitions to needs attention.

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.