Settings & Configuration
Relevant source files
The following files were used as context for generating this wiki page:
The Settings & Configuration system in Buddi provides a centralized interface for managing application behavior, visual appearance, and third-party integrations. It is built using SwiftUI and leverages the Defaults library for persistent storage of user preferences across app sessions.
The system is architected around a singleton window controller that manages a multi-tabbed settings view. This ensures a consistent user experience while allowing modular configuration for various sub-systems including Claude Code integration, Media playback, Calendar events, and System HUD replacements.
Sources: buddi/components/Settings/SettingsWindowController.swift, buddi/components/Settings/SettingsView.swift:23-45
Architecture and UI Structure
The configuration UI is managed by the SettingsWindowController, which follows a singleton pattern. It transitions the application between .accessory and .regular activation policies to ensure the settings window behaves as a standard document window when visible.
Sources: buddi/components/Settings/SettingsWindowController.swift:14-26, buddi/components/Settings/SettingsWindowController.swift:70-75
Window Management Flow
The following diagram illustrates the process of opening the settings window and how the application changes its system-level presence.
Navigation and Categories
The primary interface uses a NavigationSplitView with a sidebar containing categories for different configuration domains.
Sources: buddi/components/Settings/SettingsView.swift:31-65
| Category | Icon | Purpose |
|---|---|---|
| General | gear | System features, notch sizing, and hover behavior. |
| Claude Code | terminal | Integration hooks, socket status, and Buddy customization. |
| Appearance | eye | Visual themes, Lottie visualizers, and mirror settings. |
| Media | play.laptopcomputer | Source selection (Music/Spotify/YT) and playback behavior. |
| HUDs | dial.medium.fill | System volume/brightness overlay replacements. |
| Advanced | gearshape.2 | Custom accent colors and window behavior tweaks. |
| Sources: buddi/components/Settings/SettingsView.swift:33-64 |
Core Configuration Modules
Claude Code Integration
This section handles the link between Buddi and the Claude Code CLI. It monitors the Unix socket and manages the installation of hooks required for event forwarding.
Sources: buddi/Buddi/Settings/ClaudeCodeSettings.swift:42-64
- Hook Installation: Checks if
HookInstallerhas registered hooks to forward events via/tmp/buddi.sock. - Buddy Customization: Allows overriding the species, eyes, hat, and rarity of the user's "Buddy" character.
- Notification Sounds: Configures the audible alert played when Claude finishes processing tasks.
Sources: buddi/Buddi/Settings/ClaudeCodeSettings.swift:45-56, buddi/Buddi/Settings/ClaudeCodeSettings.swift:103-125
Notch and Display Behavior
The General settings control how the Buddi interface interacts with macOS displays and the physical notch.
Sources: buddi/components/Settings/SettingsView.swift:125-188
- Display Management: Options to show the notch on all displays or automatically switch to the active display.
- Sizing Modes: Users can choose between
matchRealNotchSize,matchMenuBar, orcustomheight for both notch and non-notch displays. - Hover Logic: Controls the
minimumHoverDuration(default 0.3s) before the notch expands.
Sources: buddi/models/Constants.swift:65-75, buddi/components/Settings/SettingsView.swift:145-165
HUD Replacement Logic
Buddi can replace standard macOS HUDs (Volume/Brightness). This requires Accessibility authorization to intercept system events.
Sources: buddi/components/Settings/SettingsView.swift:388-410
Persistence Layer
User preferences are stored using keys defined in the Defaults.Keys extension. This ensures type safety and default value management throughout the codebase.
Sources: buddi/models/Constants.swift:55-155
Key Global Configurations
| Key | Type | Default | Description |
|---|---|---|---|
openNotchOnHover | Bool | true | Expands UI when the mouse enters the notch area. |
enableHaptics | Bool | true | Provides physical feedback on interaction. |
useCustomAccentColor | Bool | false | Toggles between system and user-defined colors. |
mediaController | Enum | nowPlaying | Selects the active music source. |
shelf | Bool | true | Enables the file staging and sharing area. |
| Sources: buddi/models/Constants.swift:65, buddi/models/Constants.swift:76, buddi/models/Constants.swift:146, buddi/models/Constants.swift:150, buddi/models/Constants.swift:129 |
Advanced Customization
Custom Accent Colors
The Advanced tab allows users to deviate from the system accent color. Custom colors are archived as Data using NSKeyedArchiver to be stored in standard user defaults.
Sources: buddi/components/Settings/SettingsView.swift:965-985
Lottie Visualizers
Buddi supports custom Lottie animations for the music live activity. Users can add new visualizers by providing a URL to a Lottie JSON file and setting a playback speed.
Sources: buddi/components/Settings/SettingsView.swift:745-780, buddi/models/Constants.swift:23-28
Conclusion
The Settings & Configuration module is the backbone of Buddi's adaptability. By utilizing a modular SwiftUI design and the Defaults persistence layer, it provides users with deep control over the application's integration with Claude Code and macOS system features while maintaining a lightweight resource footprint.