Activity Indicators

This page is the source of truth for spinner and blue-dot behavior.

Spinner

A spinner means an agent is actively working in that tab.

The authoritative source is the agent lifecycle hook:

ACTIVE:<tmux-session>
DONE:<tmux-session>

ACTIVE starts the spinner. DONE stops the spinner.

tmux session_activity is not a valid semantic spinner source. It changes for redraws, status updates, terminal output, and other non-agent events.

Blue Dot

A blue dot means the tab likely needs the user’s attention.

Common case:

1. User is not viewing a tab.
2. The tab receives a DONE lifecycle event.
3. ZigShell marks it idle and sets the blue dot.

The blue dot is cleared when the user views the tab.

Agent Glyph

Agent identity is separate from activity.

Glyph state	Meaning
Claude	Claude Code was detected in the session
Codex	Codex was detected in the session
Pi	Pi was detected in the session
None	No known agent detected

Agent glyph metadata may come from tmux metadata, process scanning, screen signatures, or explicit AGENT: notifications. It must not imply active work.

Missed DONE Fallback

Remote hooks can miss DONE because of tunnel drops, interrupted commands, or identity mismatches.

If ZigShell sees a tab marked active but the visible Claude TUI is clearly idle, it may clear the spinner. Current idle prompt signatures include:

• new task? /clear to save
• press up to edit queued messages

This fallback exists only to recover from missed DONE; it must not restart spinners.

Bad States

These are bugs:

• Spinner on a tab where Claude is visibly idle.
• Spinner started from tmux activity alone.
• Blue dot on the active tab.
• Activity from one tmux session applied to a prefix-matching session.
• Muted tabs staying sorted at the top because they are noisy.

Verification

Use the published inbox snapshot:

$inbox = Get-Content "$env:APPDATA\ZigShell\inbox-default.json" -Raw | ConvertFrom-Json
$inbox.shells | Where-Object { $_.act -eq 1 -or $_.att -eq 1 } |
  Select-Object name,sub,act,att,pv

Use visible titles first when reporting to the user. Put tmux ids in parentheses only when needed.