Onboarding & Permissions
Relevant source files
The following files were used as context for generating this wiki page:
- buddi/components/Onboarding/OnboardingView.swift
- buddi/components/Onboarding/WelcomeView.swift
- buddi/components/Onboarding/OnboardingFinishView.swift
- buddi/Buddi/Services/Tmux/ToolApprovalHandler.swift
- buddi/Buddi/Settings/ClaudeCodeSettings.swift
- buddi/Buddi/UI/Views/ChatView.swift
- buddi/buddiApp.swift
- README.md
The Onboarding and Permissions system in Buddi is designed to facilitate a seamless initial setup and manage ongoing interactions with Claude Code. This system ensures that the application has the necessary system-level access to provide notch-based utility features while establishing a secure communication channel between the Buddi application and the Claude Code CLI via Unix sockets and terminal multiplexers.
Sources: README.md:1-55, buddi/components/Onboarding/OnboardingView.swift:15-30
Onboarding Architecture
Buddi utilizes a linear step-based onboarding process managed by the OnboardingView. This view acts as a state machine, transitioning users through several critical configuration steps, including identity generation, hook installation, and macOS permission requests.
Onboarding Steps
The onboarding flow is defined by the OnboardingStep enumeration, which governs the sequence of views presented to the user.
| Step | Description | Implementation Component |
|---|---|---|
welcome | Initial landing screen for the application. | WelcomeView |
meetBuddy | Generates and displays a unique ASCII buddy based on system identity. | MeetBuddyOnboardingView |
hooksInstall | Installs communication hooks into the Claude Code environment. | HooksInstallOnboardingView |
cameraPermission | Requests access for the notch-based mirror feature. | PermissionRequestView |
calendarPermission | Requests access to display system calendar events. | PermissionRequestView |
remindersPermission | Requests access to display system reminders. | PermissionRequestView |
accessibilityPermission | Required for intercepting media/brightness events for the custom HUD. | PermissionRequestView |
musicPermission | Allows selection of the preferred music controller. | MusicControllerSelectionView |
finished | Completion screen that updates the firstLaunch flag. | OnboardingFinishView |
Sources: buddi/components/Onboarding/OnboardingView.swift:15-115, buddi/buddiApp.swift:570-600
Flow Diagram: Setup Process
This diagram illustrates the logical progression of a new user through the application's configuration.
Claude Code Integration & Hooks
A central requirement of Buddi is the installation of hooks to monitor Claude Code sessions. These hooks forward events—such as tool use, thinking states, and permission requests—to Buddi over a Unix domain socket (located at /tmp/buddi.sock).
- Hook Installation: The
HookInstallerclass is used to deploy these hooks. In the onboarding process, users are prompted to "Install Hooks" to enable session monitoring and tool approval. - Security: Hooks are local-only and only send session events to the Buddi application on the same machine.
- Status Monitoring: Users can verify the installation status of these hooks within the "Claude Code" section of the application settings.
Sources: buddi/components/Onboarding/OnboardingView.swift:189-225, buddi/Buddi/Settings/ClaudeCodeSettings.swift:40-65, README.md:44-50
Tool Approval System
When Claude Code requires permission to execute a tool (e.g., writing a file or running a bash command), the request is intercepted by Buddi and presented in the UI.
Tmux and Cmux Handling
Buddi supports multiple terminal multiplexers to send approval signals back to the active Claude session. The ToolApprovalHandler manages the sending of specific key sequences to these multiplexers.
| Action | Key Sequence | Multiplexer Target |
|---|---|---|
| Approve Once | 1 + Enter | tmux or cmux |
| Approve Always | 2 + Enter | tmux or cmux |
| Reject | n + Enter | tmux or cmux |
Sources: buddi/Buddi/Services/Tmux/ToolApprovalHandler.swift:19-45, buddi/Buddi/UI/Views/ChatView.swift:515-545
Sequence Diagram: Permission Approval
This diagram shows how a permission request travels from the CLI to the UI and back as an approval.
System Permissions Management
Buddi requires several macOS privacy permissions to function as a comprehensive notch utility. These are requested asynchronously during onboarding or via the Settings panel.
Permission Logic
The application uses various system frameworks to trigger permission prompts:
- Camera: Requested via
AVCaptureDevice.requestAccess(for: .video)to enable the webcam preview/mirror feature. - Calendar/Reminders: Requested via
CalendarService(likely a wrapper forEventKit) to display upcoming schedules. - Accessibility: Requires
AXIsProcessTrustedWithOptionsto intercept system media and brightness events, allowing the app to replace the native HUD with the Buddi HUD.
Sources: buddi/components/Onboarding/OnboardingView.swift:122-140, buddi/buddiApp.swift:395-400
Settings & Overrides
Post-onboarding, users can manage these permissions and customize their experience in the ClaudeCodeSettings view. This includes:
- Verifying Hook installation status.
- Checking the Unix Socket status (Active/Inactive).
- Configuring notification sounds for when Claude finishes processing.
- Customizing the Buddy character (Species, Eyes, Hat, Rarity) which overrides the default system-generated identity.
Sources: buddi/Buddi/Settings/ClaudeCodeSettings.swift:40-120
Conclusion
The Onboarding & Permissions system ensures that Buddi is correctly integrated with both the macOS environment and the Claude Code CLI. By automating hook installation and providing clear interfaces for system permissions and tool approvals, the system establishes the necessary infrastructure for real-time AI session monitoring and system-wide utility features.
Sources: README.md:44-55, buddi/components/Onboarding/OnboardingFinishView.swift:15-35