terminal-monitoring

name	terminal-monitoring
description	Use when monitoring iTerm2 session activity, watching for state changes, subscribing to notifications, or implementing automated responses to terminal events.
allowed-tools	["Bash","Read","Grep"]

Terminal Monitoring

Guidance for monitoring iTerm2 sessions and responding to events.

When to Use

• Watching sessions for state transitions (idle → active → complete)
• Subscribing to iTerm2 notifications (keystrokes, prompts, screen changes)
• Implementing automated responses to terminal events
• Tailing session output in real-time
• Detecting when processes complete or need attention

When NOT to Use

• For one-time session queries (use session-orchestration instead)
• When you only need current state, not ongoing monitoring
• For simple command execution without feedback

Quick Start

# Tail session output (like tail -f)
it2 session tail -f "$SESSION_ID"

# Watch session for state transitions
it2 session watch "$SESSION_ID"

# Monitor all sessions
it2 session watch --all

# Subscribe to notifications
it2 notification monitor --type keystroke

Notification Types

Available Notification Types

# List available notification types
it2 notification list-types

Common types:

• keystroke - Key presses in sessions
• screen_update - Screen content changes
• prompt - Shell prompt events (requires shell integration)
• session_ended - Session termination
• variable_changed - iTerm2 variable modifications

Subscribing to Notifications

# Monitor keystrokes
it2 notification monitor --type keystroke

# Subscribe with JSON output for parsing
it2 subscribe screen_update --format json

Session Watching

Basic Watch

# Watch single session
it2 session watch "$SID"

# Watch with specific interval
it2 session watch "$SID" --interval 2s

Watch Patterns

The watch command detects:

• State transitions (idle, working, waiting)
• Process changes
• Screen stability
• Modal dialogs

Tail Mode

Follow session output like tail -f:

# Follow session output
it2 session tail -f "$SID"

# With line limit
it2 session tail -f "$SID" --lines 50

Process Monitoring

Job Monitoring

# Monitor jobs in a session
it2 job list "$SID"

# Watch for job completion
it2 job wait "$SID"

Shell Integration Events

If shell integration is enabled:

# Check shell integration status
it2 session has-shell-integration "$SID"

# Get prompt metadata
it2 session prompt "$SID"

# Search command history
it2 prompt search "git commit"

Automated Responses

Autorespond

Set up automatic responses to patterns:

# Auto-respond to prompts
it2 session autorespond "$SID" --pattern "Continue?" --response "y"

State-Based Actions

# Get suggested action
ACTION=$(it2 session suggest-action "$SID" --format json)

# Act based on state
STATE=$(it2 session get-state "$SID" --format json | jq -r '.state')
case "$STATE" in
  "idle") echo "Session ready for input" ;;
  "working") echo "Session busy" ;;
  "waiting") echo "Session needs attention" ;;
esac

Screen Monitoring

Detecting Changes

# Get current screen hash
HASH1=$(it2 session get-screen "$SID" | md5)
sleep 1
HASH2=$(it2 session get-screen "$SID" | md5)

if [ "$HASH1" != "$HASH2" ]; then
  echo "Screen changed"
fi

Content Matching

# Wait for specific content
while ! it2 session get-screen "$SID" | grep -q "Complete"; do
  sleep 1
done
echo "Task completed"

Event-Driven Monitoring

Using Subscribe

# Subscribe to events and process
it2 subscribe screen_update --session "$SID" --format json | while read event; do
  # Process each event
  echo "$event" | jq .
done

Best Practices

1. Use shell integration when available for richer monitoring
2. Prefer event subscriptions over polling for efficiency
3. Set reasonable intervals to avoid overwhelming the system
4. Handle disconnections gracefully in long-running monitors
5. Use JSON output for programmatic processing

Advanced Usage

See references/notifications.md for all notification types. See references/shell-integration.md for prompt/command tracking. See workflows/automated-testing.md for CI/CD integration.