Process Execution & Trees
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
Process Execution & Trees refers to the system within Buddi responsible for discovering, mapping, and interacting with system processes, specifically focusing on identifying Claude Code instances running within terminal multiplexers like tmux and cmux. This system allows Buddi to maintain a real-time understanding of the process hierarchy, enabling features such as window focusing, automated tool approval, and session monitoring.
By leveraging system commands such as ps and lsof, the project builds an internal representation of the process tree. This mapping is critical for determining if a process is a descendant of a multiplexer and for identifying the parent terminal application. This architectural layer serves as the foundation for the "Live session monitoring" and "Permission approvals" features described in the project's Claude Code Integration.
Sources: buddi/Buddi/Services/Shared/ProcessTreeBuilder.swift, README.md:14-22
Process Tree Construction
The core of the process management system is the ProcessTreeBuilder, which constructs a mapping of Process IDs (PID) to BuddiProcessInfo objects. This data structure captures essential process metadata required for tree traversal.
Architecture and Data Flow
The system executes the /bin/ps command with specific arguments (-eo pid,ppid,tty,comm) to retrieve a snapshot of all system processes. The output is parsed to populate a dictionary where the PID serves as the key.
The diagram above illustrates the flow from a build request to the creation of the synchronized process tree dictionary.
Sources: buddi/Buddi/Services/Shared/ProcessTreeBuilder.swift:34-60
Key Data Structures
| Structure | Type | Description |
|---|---|---|
BuddiProcessInfo | Struct | Contains pid, ppid, command, and tty for a single process. |
tree | [Int: BuddiProcessInfo] | The primary lookup table for process hierarchy traversal. |
Sources: buddi/Buddi/Services/Shared/ProcessTreeBuilder.swift:11-23, buddi/Buddi/Services/Shared/ProcessTreeBuilder.swift:42
Multiplexer Detection and Traversal
Buddi uses recursive-style traversal (limited by depth to prevent infinite loops) to identify the environment in which a Claude process is running. This is primarily used to check for the presence of tmux or cmux in a process's ancestry.
Traversal Logic
The ProcessTreeBuilder provides methods to walk up the tree from a given PID. It checks the command string of each ancestor against known multiplexer signatures.
- isInMultiplexer: Checks if either
tmuxorcmuxexists in the parent chain. - findTerminalPid: Searches upward until it finds a process recognized as a terminal application via the
TerminalAppRegistry. - isDescendant: Verifies if a specific PID is a child (at any depth) of an ancestor PID.
The flow shows the logic for identifying if a process is running inside a multiplexer by traversing parent IDs.
Sources: buddi/Buddi/Services/Shared/ProcessTreeBuilder.swift:63-108
Process-to-Multiplexer Mapping
To interact with Claude, Buddi must map a system PID to a specific target within a multiplexer (e.g., a tmux pane or a cmux surface).
Tmux and Cmux Target Discovery
The TmuxTargetFinder uses the process tree to correlate system PIDs with multiplexer internal IDs.
- Tmux Discovery: Lists all panes using
tmux list-panesand compares thepane_pidagainst the target PID's ancestors usingisDescendant. - Cmux Discovery: Enumerates all surfaces across workspaces. It matches processes by either checking the screen content for the working directory (via
read-screen) or by matching the surface title to the project name.
Sources: buddi/Buddi/Services/Tmux/TmuxTargetFinder.swift:43-71, buddi/Buddi/Services/Tmux/TmuxTargetFinder.swift:105-149
Working Directory Extraction
The system utilizes lsof to determine the current working directory of a process, which is used as a secondary matching mechanism when PIDs are unavailable or ambiguous.
Sources: buddi/Buddi/Services/Shared/ProcessTreeBuilder.swift:131-149
Interaction and Control
Once a process is mapped to a tree and a multiplexer target, the system can execute commands within that environment.
Automated Tool Approval
The ToolApprovalHandler translates UI actions (like clicking "Allow" in the notch) into keystrokes sent directly to the process running in the multiplexer.
| Action | Command Sent |
|---|---|
approveOnce | Sends "1" + Enter |
approveAlways | Sends "2" + Enter |
reject | Sends "n" + Enter (optionally followed by a message) |
Sources: buddi/Buddi/Services/Tmux/ToolApprovalHandler.swift:23-45
Window Management
The YabaiController integrates with the process tree to focus the specific terminal window hosting a Claude session. It finds the terminal PID by traversing up from the tmux client PID and then issues focus commands via yabai.
This diagram outlines the steps taken to bring the correct terminal window to the foreground based on the process tree analysis.
Sources: buddi/Buddi/Services/Window/YabaiController.swift:20-56
Conclusion
The Process Execution & Trees system provides Buddi with the necessary introspection to bridge the gap between a high-level macOS application and low-level CLI tools running in multiplexed terminal environments. By maintaining an accurate, depth-limited model of the process hierarchy, Buddi ensures that tool approvals, chat messages, and window focus actions are always directed to the correct Claude Code instance.