Live Activities Modifiers
Relevant source files
The following files were used as context for generating this wiki page:
Live Activities Modifiers in Buddi refer to the architectural patterns and view modifiers used to track, visualize, and interact with concurrent Claude Code sessions in real-time. These modifiers facilitate the integration between Claude Code events and the macOS notch UI, enabling dynamic updates for tool executions, thinking states, and permission requests.
The system relies on a Unix domain socket to receive events from Claude Code hooks, which are then processed by a central state manager to update the UI. This allows for a "live" monitoring experience where the notch expands or changes state based on the active terminal session's progress.
Sources: README.md:15-18, README.md:44-50
Architecture and Data Flow
The Live Activity system follows a unidirectional data flow from the terminal-based Claude Code tool to the Buddi macOS application. Events are emitted via hooks and parsed into a structured session state.
The flow ensures that any action taken in the terminal is immediately reflected in the Buddi interface, while user interactions in Buddi (like approving a tool) are sent back to the terminal through multiplexer control (tmux/cmux).
Sources: README.md:46, buddi/Buddi/Services/State/SessionStore.swift:18-35, buddi/Buddi/UI/Views/ChatView.swift:480-500
Session State Management
The SessionStore serves as the central manager for all live activities. It maintains a collection of SessionState objects, each representing an active Claude Code process.
Session Phases
Live activities transition through various phases based on incoming events:
| Phase | Description | Trigger Event |
|---|---|---|
idle | Claude is waiting for user input. | Session start or tool completion. |
processing | Claude is thinking or executing local logic. | PreToolUse or message submission. |
waitingForApproval | A tool requires manual permission to execute. | PermissionRequest hook. |
compacting | Claude is summarizing the conversation. | Specific internal maintenance event. |
Sources: buddi/Buddi/Services/State/SessionStore.swift:110-130, buddi/Buddi/Services/State/SessionStore.swift:348-360
Incremental Parsing
To maintain "live" performance, the ConversationParser utilizes incremental parsing of JSONL files. It tracks file offsets to only process new lines added since the last update, minimizing I/O overhead.
View Modifiers and UI Components
The UI responds to live activity updates through specialized view components that modify their appearance based on the session's current phase and tool status.
Tool Call Visualization
Tool executions are rendered with dynamic status indicators. A pulseOpacity animation is applied when a tool is in the running or waitingForApproval state to provide visual feedback of an active background process.
- Running: Displays a pulsing white/gray dot.
- Waiting: Displays an orange dot and provides "Allow" or "Deny" buttons.
- Success: Displays a green dot and enables result expansion.
- Error: Displays a red dot with error details.
Sources: buddi/Buddi/UI/Views/ChatView.swift:425-460, buddi/Buddi/UI/Views/ChatView.swift:515-540
Processing Indicators
When Claude is in the processing phase, the ProcessingIndicatorView is injected into the message list. This view includes a ProcessingSpinner and animated text (e.g., "Thinking...") that is removed once an assistant message or tool result is received.
Sources: buddi/Buddi/UI/Views/ChatView.swift:390-415
Tool Result Rendering
Live activities include the ability to render structured results for various Claude Code tools. These are updated as soon as the PostToolUse event or a corresponding tool_result is detected in the session logs.
| Tool | Modifier / View Content | Source File |
|---|---|---|
| Edit | SimpleDiffView showing LCS-computed line diffs. | ToolResultViews.swift:76 |
| Read | FileCodeView with line numbers and syntax-aware formatting. | ToolResultViews.swift:60 |
| Bash | CodePreview for stdout/stderr with return code interpretation. | ToolResultViews.swift:105 |
| WebSearch | List of search results with titles and snippets. | ToolResultViews.swift:230 |
Sources: buddi/Buddi/UI/Views/ToolResultViews.swift:15-50
Live Interaction Logic
Interaction with live activities is managed through multiplexer bridges. When a user interacts with a "Live Activity" modifier (such as clicking "Approve" in the notch), the command is routed through ToolApprovalHandler.
The app identifies the correct terminal pane by matching the TTY recorded during the session's HookEvent or by querying the process tree to find the parent multiplexer session.
Sources: buddi/Buddi/Services/Tmux/ToolApprovalHandler.swift:25-45, buddi/Buddi/UI/Views/ChatView.swift:645-675, buddi/buddiApp.swift:515-530
Summary
Live Activities Modifiers in Buddi create a highly responsive bridge between the Claude Code CLI and the macOS desktop environment. By combining incremental JSONL parsing, pulsing UI indicators, and direct multiplexer integration, the system provides a real-time monitoring and control interface that mirrors the activity and requirements of the underlying AI session.