Session Monitoring

Overview

Session monitoring is the core of navi. It tracks all running Claude Code sessions in real time, displaying their status, working directory, and current message in a styled terminal interface.

How It Works

Hook-Based Status Updates

When Claude Code fires events (user prompt, tool approval, stop, etc.), hook scripts write status information to JSON files in ~/.claude-sessions/. Each session gets its own JSON file keyed by tmux session name.

The main hook script (notify.sh) receives a status argument and writes a JSON file:

{
  "tmux_session": "my-session",
  "status": "working",
  "message": "Implementing the login feature",
  "cwd": "/home/user/projects/app",
  "timestamp": 1738972800
}

Polling

Navi polls ~/.claude-sessions/*.json every 500ms to detect changes. Each poll cycle:

Reads all JSON status files from the sessions directory
Cross-references with tmux list-sessions to detect stale entries
Removes entries for sessions that no longer exist in tmux
Sorts sessions by priority — attention-needed statuses first (waiting, permission), then by timestamp

Session Statuses

Status	Icon	Color	Meaning
waiting	⏳	Yellow	Awaiting user input
permission	❓	Magenta	Needs tool approval
working	⚙️	Cyan	Actively processing
done	✅	Green	Task completed
idle	⏸	Gray	Agent is idle
stopped	⏹	Gray	Session stopped
error	❌	Red	Error occurred
offline	⏹️	Gray	Disconnected
unknown	○	Dim	Unknown or stale

Display

Each session row shows:

Status icon with color
Session name
Age (e.g., ”12s ago”, “3m ago”)
Working directory (dimmed)
Current message (dimmed, italic, truncated)

Sessions that need attention (waiting, permission) sort to the top automatically.

Session Management — Interact with monitored sessions
Session Metrics — Token and time tracking per session
Agent Teams — Team member status display