claude-hud/docs/adr/004-session-handling.md

ADR 004: Session Handling

Status

Accepted

Context

Current problems with session handling:

1. HUD doesn't attach correctly when user runs /new
2. /exit and /resume leave HUD in stale state
3. Session ID not tracked consistently
4. No graceful handling of session switches

Users expect the HUD to "just work" regardless of how they navigate Claude Code sessions.

Decision

Track session ID in all events, detect changes, and reset state gracefully.

Session Lifecycle

┌─────────────────────────────────────────────────────────────┐
│                    Session States                            │
│                                                              │
│    ┌──────────┐                                             │
│    │  INIT    │ ─────────────────────────┐                  │
│    └────┬─────┘                          │                  │
│         │ SessionStart                   │                  │
│         ▼                                │                  │
│    ┌──────────┐     /new or /exit        │                  │
│    │  ACTIVE  │ ──────────────────►  ┌───┴───┐              │
│    └────┬─────┘                      │ RESET │              │
│         │                            └───┬───┘              │
│         │ Stop event                     │                  │
│         ▼                                │                  │
│    ┌──────────┐                          │                  │
│    │  IDLE    │ ◄────────────────────────┘                  │
│    └──────────┘                                             │
│                                                              │
└─────────────────────────────────────────────────────────────┘

Session ID Tracking

Every event includes session_id:

interface HudEvent {
  session_id: string;  // Always present
  hook_event_name: string;
  timestamp: number;
  // ... other fields
}

Session Change Detection

// hooks/useSession.ts
function useSession() {
  const [currentSession, setCurrentSession] = useState<string | null>(null);

  const handleEvent = useCallback((event: HudEvent) => {
    if (currentSession && event.session_id !== currentSession) {
      // SESSION CHANGED - reset all state
      resetAllState();
    }
    setCurrentSession(event.session_id);
  }, [currentSession]);

  return { currentSession, handleEvent };
}

State Reset on Session Change

When session changes, reset:

• Tool history (clear)
• Agent list (clear)
• Context tracking (reset to zero)
• Cost tracking (reset)
• Todos (clear)
• Modified files (clear)

Do NOT reset:

• Git status (session-independent)
• MCP status (session-independent)
• UI preferences (if any)

FIFO Reconnection Strategy

// lib/event-reader.ts
class EventReader {
  private sessionId: string;
  private reconnectAttempts = 0;
  private maxReconnectDelay = 30_000; // 30 seconds max

  private getReconnectDelay(): number {
    // Exponential backoff: 100ms, 200ms, 400ms, ... up to 30s
    const delay = Math.min(
      100 * Math.pow(2, this.reconnectAttempts),
      this.maxReconnectDelay
    );
    this.reconnectAttempts++;
    return delay;
  }

  private async reconnect(): Promise<void> {
    const delay = this.getReconnectDelay();
    await sleep(delay);

    // Check if FIFO still exists
    if (await this.fifoExists()) {
      await this.connect();
      this.reconnectAttempts = 0; // Reset on success
    } else {
      // Session ended, clean up
      this.emit('session_ended');
    }
  }
}

Handling /new, /exit, /resume

Command	Expected Behavior
/new	New session starts, HUD resets and attaches to new session
/exit	Session ends, HUD shows idle/disconnected state
/resume	Resume session, HUD reconnects to existing FIFO

Implementation: SessionStart Hook

# session-start.sh
# Check if HUD is already running for this session
existing_pid=$(cat "$PID_FILE" 2>/dev/null)
if kill -0 "$existing_pid" 2>/dev/null; then
  # Send signal to reconnect instead of spawning new
  kill -USR1 "$existing_pid"
else
  # Spawn new HUD instance
  spawn_hud
fi

UI Feedback for Session States

State	UI Indication
INIT	"Connecting..."
ACTIVE	Normal display
IDLE	"Idle" badge, dimmed metrics
DISCONNECTED	"Reconnecting..." with spinner
SESSION_CHANGED	Brief "New Session" indicator, then reset

Consequences

Positive

• Seamless transitions: /new /exit /resume just work
• No stale data: Session changes trigger clean reset
• User confidence: HUD always shows current session state
• Debuggable: Session ID in all events for tracing

Negative

• State loss on /new: Previous session data gone (acceptable)
• Brief disruption: Reset causes momentary blank UI
• Complexity: More state to manage

Edge Cases

1. Rapid /new /new /new: Each creates new FIFO, HUD follows last one
2. FIFO deleted externally: Reconnect logic handles gracefully
3. Claude Code crashes: SessionEnd may not fire, rely on FIFO absence
4. Multiple terminals: Each Claude instance has its own FIFO

Implementation Notes

1. Add session_id to all events in capture-event.sh
2. Create useSession hook for session state management
3. Emit 'session_changed' event when ID changes
4. All state hooks listen for session_changed to reset
5. Add reconnection logic to EventReader
6. Add session state indicator to StatusBar component