Background Monitor

Overview

The background attach monitor keeps audio notifications running while you’re attached to a tmux session. Without it, notifications would stop when the TUI yields terminal control to tmux. A companion CLI command, navi status, provides session summaries for your tmux status bar.

Quick Start

Background Notifications

No configuration needed — the monitor starts automatically when you press Enter to attach to a session in navi. When you detach (Ctrl-B D), it stops and hands state back to the TUI.

tmux Status Bar

Add to your ~/.tmux.conf:

set -g status-right '#(navi status)'
set -g status-interval 5

This shows sessions needing attention (e.g., 1 waiting, 2 permission) in your tmux status bar, refreshing every 5 seconds.

How It Works

Monitor Lifecycle

User presses Enter to attach
    │
    ▼
TUI calls startAttachMonitor()
    │
    ├── Copies lastSessionStates to monitor (state handoff)
    ├── Creates context with cancel function
    └── Launches goroutine polling ~/.claude-sessions/*.json
    │
    ▼
tea.ExecProcess hands terminal to tmux
    │
Monitor runs in background (500ms polling)
    │
    ├── Reads session status files
    ├── Compares against known states
    └── Fires audio.Notifier on transitions
    │
    ▼
User detaches from tmux (Ctrl-B D)
    │
    ▼
TUI receives attachDoneMsg
    │
    ├── Cancels monitor context (goroutine exits)
    ├── Recovers final states from monitor.States()
    └── Assigns back to lastSessionStates
    │
    ▼
TUI resumes polling — no duplicate notifications

State Handoff

The key design feature is seamless state handoff between the TUI and monitor:

1. Before attach: TUI passes its lastSessionStates map to the monitor via Start(ctx, initialStates)
2. During attach: Monitor tracks all transitions independently and fires notifications
3. After detach: TUI calls monitor.States() to recover the final state, then assigns it back to lastSessionStates

This ensures no transition is missed or double-notified across the TUI ↔ monitor boundary.

navi status Command

A one-shot CLI command that reads session status files and prints a summary.

Usage

navi status              # Priority sessions only (waiting, permission)
navi status --verbose    # All statuses with non-zero counts
navi status --format=tmux  # Plain text (same as default, for tmux compatibility)

Output Examples

# Default — only sessions needing attention:
$ navi status
1 waiting, 2 permission

# Nothing needs attention:
$ navi status
(empty output)

# Verbose — all non-zero statuses:
$ navi status --verbose
3 working, 1 waiting, 2 permission, 1 idle

Flags

Flag	Default	Description
--verbose	false	Include all non-zero status counts
--format	"plain"	Output format: "plain" or "tmux"

Exit Codes

Code	Meaning
0	Success
1	Flag parsing or I/O error

Status Display Order

Mode	Statuses Shown
Default	waiting, permission only
Verbose	working → waiting → permission → idle → stopped

Configuration

The background monitor uses the same audio configuration as the TUI (~/.config/navi/sounds.yaml). See Audio Notifications for configuration details.

The monitor polls at the same interval as the TUI (500ms) and reads from the same session directory (~/.claude-sessions/).

Related Features

• Audio Notifications — Sound and TTS configuration used by the monitor
• Session Monitoring — The session polling system that provides status data