Merge pull request #108 from tddworks/hook

Claude Code Session Tracking: Real-time monitoring of Claude Code sessions via hooks.

Author: hanrw

CHANGELOG.md

@@ -7,6 +7,26 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.4.33] - 2026-02-14
+
+### Added
+- **Claude Code Session Tracking**: Real-time monitoring of Claude Code sessions via hooks. When Claude Code is running, ClaudeBar shows session status directly in the menu bar and popover:
+  - **Menu bar indicator**: A terminal icon appears next to the quota icon with phase-colored status (green = active, blue = subagents working, orange = stopped)
+  - **Session card**: Detailed session info in the popover showing phase, task count, active subagents, duration, and working directory
+  - **System notifications**: Get notified when a session starts ("Claude Code Started") and finishes ("Claude Code Finished — Completed 3 tasks in 2m 5s")
+- **Hook Settings**: New "Claude Code Hooks" section in Settings with a single toggle to enable/disable. Automatically installs/uninstalls hooks in `~/.claude/settings.json`.
+
+### Technical
+- Added `SessionEvent`, `ClaudeSession`, and `SessionMonitor` domain models for session lifecycle tracking
+- Added `HookHTTPServer` using Network.framework (`NWListener`) for localhost-only event reception on port 19847
+- Added `SessionEventParser` for parsing Claude Code hook JSON payloads
+- Added `HookInstaller` for auto-managing hooks in `~/.claude/settings.json` using the new matcher-based format
+- Added `PortDiscovery` for writing/reading `~/.claude/claudebar-hook-port`
+- Added `HookSettingsRepository` protocol and `UserDefaults` implementation
+- Added `com.apple.security.network.server` entitlement for `NWListener`
+- Added `AppLog.hooks` logging category
+- Added `LiveActivityManager` placeholder for future ActivityKit support (currently unavailable on macOS)
+
 ## [0.4.32] - 2026-02-12
 
 ### Added

Sources/App/ClaudeBarApp.swift

@@ -5,15 +5,31 @@ import Infrastructure
 import Sparkle
 #endif
 
+extension Notification.Name {
+    static let hookSettingsChanged = Notification.Name("com.tddworks.claudebar.hookSettingsChanged")
+}
+
 @main
 struct ClaudeBarApp: App {
     /// The main domain service - monitors all AI providers
     /// This is the single source of truth for providers and their state
     @State private var monitor: QuotaMonitor
 
+    /// Monitors Claude Code sessions via hook events
+    @State private var sessionMonitor = SessionMonitor()
+
+    /// The hook HTTP server that receives events from Claude Code
+    private let hookServer = HookHTTPServer()
+
+    /// Task for the hook server event loop (allows cancellation on toggle off)
+    @State private var hookServerTask: Task<Void, Never>?
+
     /// Alerts users when quota status degrades
     private let quotaAlerter = NotificationAlerter()
 
+    /// Sends session start/end notifications
+    private let sessionAlertSender = SystemAlertSender()
+
     #if ENABLE_SPARKLE
     /// Sparkle updater for auto-updates
     @State private var sparkleUpdater = SparkleUpdater()
@@ -78,6 +94,11 @@ struct ClaudeBarApp: App {
         )
         AppLog.monitor.info("QuotaMonitor initialized")
 
+        // Start hook server if hooks are enabled
+        if settingsRepository.isHookEnabled() {
+            startHookServer()
+        }
+
         // Note: Notification permission is requested in onAppear, not here
         // Menu bar apps need the run loop to be active before requesting permissions
 
@@ -92,36 +113,110 @@ struct ClaudeBarApp: App {
         ThemeMode(rawValue: settings.themeMode) ?? .system
     }
 
+    private func startHookServer() {
+        // Cancel any existing server task
+        hookServerTask?.cancel()
+        hookServer.stop()
+
+        hookServerTask = Task {
+            do {
+                let events = try await hookServer.start()
+                AppLog.hooks.info("Hook server started, listening for events")
+                for await event in events {
+                    await sessionMonitor.processEvent(event)
+                    await sendSessionNotification(for: event)
+                }
+            } catch {
+                AppLog.hooks.error("Failed to start hook server: \(error.localizedDescription)")
+            }
+        }
+    }
+
+    func stopHookServer() {
+        hookServerTask?.cancel()
+        hookServerTask = nil
+        hookServer.stop()
+    }
+
+    @MainActor private func sendSessionNotification(for event: SessionEvent) {
+        let projectName = (event.cwd as NSString).lastPathComponent
+
+        switch event.eventName {
+        case .sessionStart:
+            Task {
+                try? await sessionAlertSender.send(
+                    title: "Claude Code Started",
+                    body: "Session started in \(projectName)",
+                    categoryIdentifier: "SESSION_START"
+                )
+            }
+        case .sessionEnd:
+            let taskCount = sessionMonitor.recentSessions.first?.completedTaskCount ?? 0
+            let duration = sessionMonitor.recentSessions.first?.durationDescription ?? ""
+            let summary = taskCount > 0
+                ? "Completed \(taskCount) task\(taskCount == 1 ? "" : "s") in \(duration)"
+                : "Session ended after \(duration)"
+            Task {
+                try? await sessionAlertSender.send(
+                    title: "Claude Code Finished",
+                    body: "\(projectName) — \(summary)",
+                    categoryIdentifier: "SESSION_END"
+                )
+            }
+        default:
+            break
+        }
+    }
+
     var body: some Scene {
         MenuBarExtra {
             #if ENABLE_SPARKLE
-            MenuContentView(monitor: monitor, quotaAlerter: quotaAlerter)
+            MenuContentView(monitor: monitor, sessionMonitor: sessionMonitor, quotaAlerter: quotaAlerter) { enabled in
+                    if enabled { startHookServer() } else { stopHookServer() }
+                }
                 .appThemeProvider(themeModeId: settings.themeMode)
                 .environment(\.sparkleUpdater, sparkleUpdater)
             #else
-            MenuContentView(monitor: monitor, quotaAlerter: quotaAlerter)
+            MenuContentView(monitor: monitor, sessionMonitor: sessionMonitor, quotaAlerter: quotaAlerter) { enabled in
+                    if enabled { startHookServer() } else { stopHookServer() }
+                }
                 .appThemeProvider(themeModeId: settings.themeMode)
             #endif
         } label: {
-            // Show overall status (worst across all enabled providers) in menu bar
-            StatusBarIcon(status: monitor.selectedProviderStatus)
+            // Show overall status + active session indicator in menu bar
+            StatusBarIcon(status: monitor.selectedProviderStatus, activeSession: sessionMonitor.activeSession)
                 .appThemeProvider(themeModeId: settings.themeMode)
         }
         .menuBarExtraStyle(.window)
     }
+
 }
 
 /// The menu bar icon that reflects the overall quota status.
+/// When a Claude Code session is active, shows a terminal icon with phase color.
 /// Uses theme's `statusBarIconName` if set, otherwise shows status-based icons.
 struct StatusBarIcon: View {
     let status: QuotaStatus
+    var activeSession: ClaudeSession? = nil
 
     @Environment(\.appTheme) private var theme
 
     var body: some View {
-        Image(systemName: iconName)
-            .symbolRenderingMode(.palette)
-            .foregroundStyle(iconColor)
+        if let session = activeSession {
+            // Active session: show terminal icon with phase color
+            HStack(spacing: 3) {
+                Image(systemName: "terminal.fill")
+                    .symbolRenderingMode(.palette)
+                    .foregroundStyle(sessionPhaseColor(session.phase))
+                Image(systemName: iconName)
+                    .symbolRenderingMode(.palette)
+                    .foregroundStyle(iconColor)
+            }
+        } else {
+            Image(systemName: iconName)
+                .symbolRenderingMode(.palette)
+                .foregroundStyle(iconColor)
+        }
     }
 
     private var iconName: String {
@@ -143,6 +238,10 @@ struct StatusBarIcon: View {
     private var iconColor: Color {
         theme.statusColor(for: status)
     }
+
+    private func sessionPhaseColor(_ phase: ClaudeSession.Phase) -> Color {
+        phase.color
+    }
 }
 
 // MARK: - StatusBarIcon Preview

Sources/App/Info.plist

@@ -38,5 +38,7 @@
     <true/>
     <key>SUAutomaticallyUpdate</key>
     <false/>
+    <key>NSSupportsLiveActivities</key>
+    <true/>
 </dict>
 </plist>

Sources/App/LiveActivity/LiveActivityManager.swift

@@ -0,0 +1,36 @@
+import Foundation
+import Domain
+import Infrastructure
+
+/// Placeholder for ActivityKit Live Activity integration.
+///
+/// ActivityKit types (`ActivityAttributes`, `Activity`) are currently marked as
+/// explicitly unavailable on macOS — even in macOS 26. When Apple adds macOS
+/// support for Live Activities, this manager can be activated to show session
+/// status as a system-level Live Activity.
+///
+/// In the meantime, session tracking is handled by `SessionIndicatorView`
+/// in the menu bar popover, which works on all macOS versions.
+///
+/// To activate when ActivityKit becomes available on macOS:
+/// 1. Create `Sources/HookActivityWidget/` with ActivityAttributes + Widget view
+/// 2. Add widget extension target to Project.swift
+/// 3. Uncomment the ActivityKit code below
+public final class LiveActivityManager: @unchecked Sendable {
+    public init() {}
+
+    /// Starts tracking a session. Currently a no-op on macOS.
+    public func startActivity(for session: ClaudeSession) {
+        AppLog.hooks.debug("Live Activity not available on macOS — using menu popover instead")
+    }
+
+    /// Updates tracking for a session. Currently a no-op on macOS.
+    public func updateActivity(for session: ClaudeSession) {
+        // No-op until ActivityKit is available on macOS
+    }
+
+    /// Ends tracking for a session. Currently a no-op on macOS.
+    public func endActivity() {
+        // No-op until ActivityKit is available on macOS
+    }
+}

Sources/App/Views/MenuContentView.swift

@@ -9,7 +9,9 @@ import Sparkle
 /// Uses the pluggable theme system for consistent styling across all themes.
 struct MenuContentView: View {
     let monitor: QuotaMonitor
+    let sessionMonitor: SessionMonitor
     let quotaAlerter: QuotaAlerter
+    var onHookSettingsChanged: ((Bool) -> Void)?
 
     @Environment(\.appTheme) private var theme
     @Environment(\.colorScheme) private var colorScheme
@@ -71,6 +73,13 @@ struct MenuContentView: View {
                             .padding(.bottom, 16)
                     }
 
+                    // Session Indicator (shown when Claude Code is active)
+                    if let session = sessionMonitor.activeSession {
+                        SessionIndicatorView(session: session)
+                            .padding(.horizontal, 16)
+                            .padding(.bottom, 8)
+                    }
+
                     // Main Content Area - no scroll, dynamic height
                     VStack(spacing: 12) {
                         metricsContent
@@ -98,6 +107,10 @@ struct MenuContentView: View {
         .frame(width: 400)
         .fixedSize(horizontal: false, vertical: true)
         .clipShape(RoundedRectangle(cornerRadius: 16))
+        .onReceive(NotificationCenter.default.publisher(for: .hookSettingsChanged)) { notification in
+            let enabled = notification.userInfo?["enabled"] as? Bool ?? false
+            onHookSettingsChanged?(enabled)
+        }
         .task {
             // Request alert permission once (after app run loop is active)
             if !hasRequestedNotificationPermission {

Sources/App/Views/SessionIndicatorView.swift

@@ -0,0 +1,91 @@
+import SwiftUI
+import Domain
+
+/// Displays the current Claude Code session status in the menu popover.
+/// Shown when there's an active session (SessionMonitor.activeSession != nil).
+struct SessionIndicatorView: View {
+    let session: ClaudeSession
+
+    @Environment(\.appTheme) private var theme
+
+    var body: some View {
+        HStack(spacing: 10) {
+            // Phase indicator dot
+            Circle()
+                .fill(phaseColor)
+                .frame(width: 8, height: 8)
+                .overlay(
+                    Circle()
+                        .fill(phaseColor.opacity(0.4))
+                        .frame(width: 14, height: 14)
+                )
+
+            VStack(alignment: .leading, spacing: 2) {
+                HStack(spacing: 6) {
+                    Text("Claude Code")
+                        .font(.system(size: 11, weight: .semibold, design: theme.fontDesign))
+                        .foregroundStyle(theme.textPrimary)
+
+                    Text(phaseLabel)
+                        .font(.system(size: 9, weight: .medium, design: theme.fontDesign))
+                        .foregroundStyle(phaseLabelColor)
+                        .padding(.horizontal, 6)
+                        .padding(.vertical, 2)
+                        .background(
+                            Capsule()
+                                .fill(phaseColor.opacity(0.15))
+                        )
+                }
+
+                HStack(spacing: 8) {
+                    if session.completedTaskCount > 0 {
+                        Label("\(session.completedTaskCount) tasks", systemImage: "checkmark.circle.fill")
+                            .font(.system(size: 9, weight: .medium, design: theme.fontDesign))
+                            .foregroundStyle(theme.textSecondary)
+                    }
+
+                    if session.activeSubagentCount > 0 {
+                        Label("\(session.activeSubagentCount) agents", systemImage: "person.2.fill")
+                            .font(.system(size: 9, weight: .medium, design: theme.fontDesign))
+                            .foregroundStyle(theme.textSecondary)
+                    }
+
+                    Text(session.durationDescription)
+                        .font(.system(size: 9, weight: .medium, design: theme.fontDesign))
+                        .foregroundStyle(theme.textTertiary)
+
+                    Spacer()
+
+                    // Working directory (last path component)
+                    Text(cwdShort)
+                        .font(.system(size: 9, weight: .medium, design: theme.fontDesign))
+                        .foregroundStyle(theme.textTertiary)
+                        .lineLimit(1)
+                }
+            }
+        }
+        .padding(12)
+        .background(
+            ZStack {
+                RoundedRectangle(cornerRadius: theme.cardCornerRadius)
+                    .fill(theme.cardGradient)
+
+                RoundedRectangle(cornerRadius: theme.cardCornerRadius)
+                    .stroke(phaseColor.opacity(0.3), lineWidth: 1)
+            }
+        )
+    }
+
+    // MARK: - Phase Display
+
+    private var phaseLabel: String { session.phase.label }
+    private var phaseColor: Color { session.phase.color }
+
+    private var phaseLabelColor: Color {
+        session.phase == .ended ? theme.textTertiary : session.phase.color
+    }
+
+    private var cwdShort: String {
+        (session.cwd as NSString).lastPathComponent
+    }
+}

Sources/App/Views/SessionPhaseColor.swift

@@ -0,0 +1,15 @@
+import SwiftUI
+import Domain
+
+extension ClaudeSession.Phase {
+    /// The display color for this session phase.
+    /// Single source of truth — used by StatusBarIcon, SessionIndicatorView, etc.
+    var color: Color {
+        switch self {
+        case .active: return .green
+        case .subagentsWorking: return .blue
+        case .stopped: return .orange
+        case .ended: return .gray
+        }
+    }
+}