Window Automation & Discovery
Relevant source files
The following files were used as context for generating this wiki page:
The Window Automation & Discovery system in Buddi is responsible for identifying, tracking, and manipulating terminal windows associated with Claude Code sessions. It primarily leverages the yabai window manager to query window metadata and perform focus actions. This system bridges the gap between background Claude processes and the user's graphical interface, allowing the app to automatically bring the correct terminal pane or window into focus when user interaction is required.
The system supports complex environments including terminal multiplexers like tmux and cmux. By analyzing process trees and sampling terminal content, Buddi can pinpoint the exact window, tab, or pane hosting a specific Claude session, even when multiple sessions are running concurrently across different terminal applications.
Architecture and Components
The architecture relies on a layered approach where high-level controllers orchestrate specialized services to discover processes and windows.
Component Overview
| Component | Responsibility |
|---|---|
YabaiController | High-level API for focusing windows based on Claude PIDs or working directories. |
WindowFinder | Interfaces directly with the yabai binary to query window states and identify terminal windows. |
ProcessTreeBuilder | Constructs a system-wide process map to link Claude instances to their parent terminal applications. |
TmuxTargetFinder | Locates specific sessions, windows, and panes within tmux or cmux environments. |
TmuxSessionMatcher | Samples terminal output to verify session identity when PID-based matching is insufficient. |
Sources: YabaiController.swift, WindowFinder.swift, ProcessTreeBuilder.swift
Discovery Flow
The following diagram illustrates how the system resolves a Claude PID to a physical window focus action.
The system first determines if the process is nested within a multiplexer. If so, it must switch the internal multiplexer state (pane/tab) before focusing the parent terminal window.
Sources: YabaiController.swift:19-48, ProcessTreeBuilder.swift:42-65
Window Management with Yabai
Buddi uses yabai as its primary engine for window discovery. It expects the yabai binary to be located in standard Homebrew paths (/opt/homebrew/bin/yabai or /usr/local/bin/yabai).
Window Data Structure
The YabaiWindow struct represents the metadata returned by a yabai -m query --windows command.
struct YabaiWindow: Sendable {
let id: Int
let pid: Int
let title: String
let space: Int
let isVisible: Bool
let hasFocus: Bool
}
Sources: WindowFinder.swift:11-20
Discovery Logic
WindowFinder provides utility methods to filter windows based on terminal characteristics:
- findWindows: Returns all windows belonging to a specific terminal PID.
- findTmuxWindow: Specifically looks for windows where the title contains "tmux".
- findNonClaudeWindow: Filters out windows that are identified as Claude-specific (often marked with a "✳" symbol in the title).
Sources: WindowFinder.swift:70-85
Multiplexer Integration (tmux & cmux)
Discovery in multiplexed environments is significantly more complex because multiple Claude sessions often share a single terminal PID.
Target Identification
The TmuxTargetFinder uses a combination of PID tree walking and working directory matching to find the correct "target string" (e.g., session:window.pane).
- PID Matching: It lists all panes and their internal PIDs using
tmux list-panes -a -F "#{session_name}:#{window_index}.#{pane_index} #{pane_pid}". It then usesProcessTreeBuilderto check if the Claude PID is a descendant of the pane's PID. - Directory Matching: As a fallback, it matches the
pane_current_pathto the Claude session's working directory. - Content Sampling: For
cmux, it may read the screen content (usingread-screen) to look for project-specific strings if metadata matching fails.
Sources: TmuxTargetFinder.swift:48-95, TmuxSessionMatcher.swift:23-45
Terminal Identification Hierarchy
When a tmux session is identified, the system must find which terminal emulator is currently attached to it. It follows this logic:
Process Tree Analysis
The ProcessTreeBuilder is the core utility for relationship discovery. It executes /bin/ps -eo pid,ppid,tty,comm to generate a flat map of the system's process hierarchy.
Key Capabilities
- Ancestry Verification:
isDescendant(targetPid:ofAncestor:tree:)allows the system to confirm if a Claude process is running "inside" a specific terminal ortmuxpane. - Multiplexer Detection:
isInTmuxandisInCmuxwalk up the parent chain (up to 20 levels) to detect the presence oftmuxorcmuxbinaries. - CWD Discovery: Uses
/usr/sbin/lsof -p [PID] -Fnto find the current working directory of a process, which is critical for matching sessions to filesystem-based project configurations.
Sources: ProcessTreeBuilder.swift:31-118
Summary
The Window Automation & Discovery module provides a robust mechanism for Buddi to interact with the user's workspace. By combining low-level process inspection (ps, lsof) with window manager queries (yabai) and multiplexer-specific commands, the system ensures that the "Buddy" can always find and focus the user's active development context. This integration is essential for the "Terminal" focus feature found in the ChatView, ensuring a seamless transition between the Buddi UI and the command line.