Session Monitoring

Relevant source files

The following files were used as context for generating this wiki page:

• buddi/Buddi/Services/Session/ClaudeSessionMonitor.swift
• buddi/Buddi/Services/State/SessionStore.swift
• buddi/Buddi/Models/SessionState.swift
• buddi/Buddi/Models/SessionEvent.swift
• buddi/Buddi/Models/SessionPhase.swift
• buddi/Buddi/Services/Session/ConversationParser.swift
• buddi/Buddi/Services/Session/AgentFileWatcher.swift

Session Monitoring is the core system responsible for tracking the lifecycle, state, and real-time activity of Claude Code sessions within Buddi. It acts as a bridge between the CLI tool and the macOS notch interface, ensuring that tool executions, thinking processes, and conversation history are accurately reflected in the UI.

The system relies on a reactive architecture where events from Claude Code hooks, JSONL log files, and user interactions are processed through a central state manager. This monitoring allows Buddi to provide features such as live chat updates, permission approval prompts, and subagent tracking.
Sources: README.md:31-37, buddi/Buddi/Services/State/SessionStore.swift:10-15

System Architecture

The session monitoring architecture follows a unidirectional data flow pattern. All state mutations are centralized within a thread-safe actor, ensuring consistency across concurrent sessions.

Core Components

Component	Responsibility
ClaudeSessionMonitor	MainActor wrapper that publishes state for SwiftUI and manages high-level lifecycle.
SessionStore	Central actor-based state manager; the single source of truth for all sessions.
ConversationParser	Asynchronously parses Claude's .jsonl files to extract messages and tool results.
HookSocketServer	Receives real-time events (PreToolUse, PermissionRequest) via Unix domain sockets.
AgentFileWatcher	Monitors specific subagent log files for nested tool activity.

Sources: buddi/Buddi/Services/Session/ClaudeSessionMonitor.swift:15-20, buddi/Buddi/Services/State/SessionStore.swift:17-25, buddi/Buddi/Services/Session/ConversationParser.swift:21-25, buddi/Buddi/Services/Session/AgentFileWatcher.swift:18-20

Session Data Flow

The following diagram illustrates how external events from Claude Code are transformed into UI updates within Buddi.

This flow ensures that real-time signals (sockets) and authoritative data (logs) are reconciled into a single SessionState.
Sources: README.md:54-58, buddi/Buddi/Services/State/SessionStore.swift:50-100, buddi/Buddi/Services/Session/ClaudeSessionMonitor.swift:34-68

Session Lifecycle and Phases

Every session is governed by a strict state machine defined in SessionPhase. Transitions are validated to ensure the session moves logically between states like idle, processing, and waitingForApproval.

Phase Definitions

Phase	Description
idle	Waiting for user input or new activity.
processing	Actively running tools or generating responses.
waitingForInput	Claude has finished a turn and awaits the user in the terminal.
waitingForApproval	A tool execution is paused pending user permission.
compacting	Claude is summarizing context to manage token limits.

Sources: buddi/Buddi/Models/SessionPhase.swift:55-75

Transition Logic

The SessionPhase enum includes a canTransition(to:) method that prevents invalid state changes. For example, a session cannot transition out of an ended state.
Sources: buddi/Buddi/Models/SessionPhase.swift:80-130

State Management (SessionStore)

The SessionStore actor is the primary engine for session monitoring. It processes a variety of SessionEvent types to update the SessionState for each active sessionId.

Event Processing

The process(_ event: SessionEvent) function handles:

• Hook Events: Real-time signals from the Claude CLI (e.g., PreToolUse, Stop).
• File Updates: Incremental data parsed from the session's .jsonl file.
• Permission Actions: User-driven approval or denial of tool use.
• Subagent Tracking: Monitoring nested "Task" tool executions.

Sources: buddi/Buddi/Services/State/SessionStore.swift:50-110

Tool and Subagent Monitoring

Buddi tracks tools through their lifecycle, from PreToolUse to completion. For complex "Task" tools, SessionStore utilizes SubagentState to manage nested tool calls.

Conversation Parsing

The ConversationParser provides the historical context and detailed message content for the monitor. It is optimized for performance using an incremental parsing strategy.

Incremental Parsing Strategy

Instead of re-reading large log files, the parser maintains an IncrementalParseState for each session, which tracks the lastFileOffset. On subsequent updates, it only reads new bytes from the file.

Key features of the parser include:

• Summary Extraction: Finds the latest "summary" type in the JSONL to provide a session title.
• Role Detection: Identifies if the last message was from the user, assistant, or a tool.
• Clear Reconciliation: Detects the /clear command in logs to reset the local chat UI while maintaining the session connection.

Sources: buddi/Buddi/Services/Session/ConversationParser.swift:34-45, buddi/Buddi/Services/Session/ConversationParser.swift:234-260, buddi/Buddi/Services/State/SessionStore.swift:425-445

Permission Handling

Monitoring permissions is a critical safety feature. When Claude requests a tool execution that requires approval, the monitor transitions the session to .waitingForApproval.

1. Detection: HookSocketServer receives a PermissionRequest event.
2. Context: A PermissionContext is created, containing the toolUseId, toolName, and formatted input.
3. UI Interaction: The session is flagged as needsAttention, triggering an expanded view in the notch or chat.
4. Resolution: The ClaudeSessionMonitor sends the user's decision back to the CLI and notifies the SessionStore to transition the phase back to .processing (if allowed) or .idle (if denied).

Sources: buddi/Buddi/Services/Session/ClaudeSessionMonitor.swift:75-105, buddi/Buddi/Models/SessionPhase.swift:14-45, buddi/Buddi/Services/State/SessionStore.swift:277-310

Conclusion

Session Monitoring in Buddi is a robust, multi-channel system that ensures developers have full visibility and control over Claude Code's actions. By combining real-time socket events with persistent log parsing and a strict state machine, Buddi maintains a reliable and reactive interface for AI-driven development.
Sources: buddi/Buddi/Services/State/SessionStore.swift:10-15, buddi/Buddi/Models/SessionPhase.swift:8-12