stonerl/thaw

1. What this repo is

Thaw is a macOS menu bar management app, split into a primary GUI app and a small helper/service target. The core product hides, shows, reorders, and restyles menu bar items, with extra features like hotkeys, search, profiles, and automation.

2. Top-level runtime shape

The main executable is the Thaw app target. It owns app state, settings, navigation, onboarding, permissions UI, notifications, and the visible menu bar controls. A separate MenuBarItemService process handles low-level menu bar item discovery and monitoring so the GUI app does not do all of that work in-process.

3. System event ingestion

Input comes from macOS event infrastructure: event taps, HID event monitoring, local event monitors, and hotkey handling. These feed the app’s interaction model for showing hidden items, toggling sections, invoking search, and responding to mouse/keyboard gestures. Accessibility and related permissions are first-class because the app needs to inspect and manipulate other apps’ menu bar items.

4. Menu bar item discovery boundary

MenuBarItemService is the system-facing boundary for enumerating and tracking menu bar items. It includes a listener and PID cache, and the app connects to it through MenuBarItemServiceConnection. This is the most important process boundary in the architecture: the service observes the OS/menu bar space, while the main app consumes item metadata and turns it into layout decisions.

5. Item model and layout engine

The Thaw/MenuBar/MenuBarItems subsystem contains the core layout logic. LayoutSolver and LayoutReconciler decide where each item belongs, how hidden/always-hidden sections are formed, and how changes are applied over time. Supporting pieces like PendingLedger, tag types, and image caches track unresolved moves, identities, and item rendering state.

6. Menu bar presentation layer

Rendering is split into dedicated visual components: LayoutBar for arranged menu bar content, IceBar for the separate bar shown below or around the menu bar, and overlay/panel types for transient UI. The ControlItem views and icons represent the app’s own controls inside the bar. The layout UI is clearly separated from the discovery and reconciliation logic.

7. Appearance customization subsystem

Appearance is handled by a dedicated set of managers, editor panels, and configuration models. This covers tint, gradients, shadows, borders, shapes, and dark/light variants. The MenuBarAppearanceManager and the versioned configuration types indicate persistence/migration of appearance settings over time rather than a purely ephemeral UI state.

8. Settings and profiles

The settings system is broad and modular: general, advanced, automation, hotkeys, display, menu bar appearance, menu bar layout, and profile panes each map to their own model layer. ProfileManager and related models support applying different layouts/configurations, while SettingsResetter, import/export helpers, and migration utilities show that settings are treated as durable app data with compatibility concerns.

9. Automation, hooks, and behavior policy

Beyond manual toggles, the app supports behavior rules such as re-hide strategies, app conflict detection, focus filtering, and hook scripts. HookRunner and automation settings suggest user-defined actions or scripts that run in response to menu bar state changes. This creates a policy layer above the raw layout engine.

10. UI structure and navigation

The app uses SwiftUI-style window and pane structure for onboarding, permissions, settings, and specialized editors/search panels. AppState and AppNavigationState coordinate what the user sees, while custom UI components under Thaw/UI provide consistent macOS-style controls, tooltips, recorders, and list/panel primitives. The app is not just a single window; it is a set of coordinated windows and sheets.

11. Lower-level platform support

VirtualDisplay and the Objective-C/bridging files indicate platform-specific support code for display-related behavior that macOS APIs alone do not fully provide. Shared utility code includes accessibility helpers, screen capture, mouse helpers, swizzling, localization, and window/space metadata extraction. These modules are the glue between macOS internals and the higher-level menu bar logic.

12. Data persistence and shared domain types

Shared models and utilities define the common language of the app: windows, sections, modifiers, keys, commands, profiles, settings, and diagnostic logging. These types are used across the UI, layout engine, hotkey system, and helper service, which keeps the architecture cohesive even though the app is split across multiple targets.

13. Notifications, onboarding, and updates

User-facing lifecycle concerns are handled separately from the menu bar engine. Onboarding introduces the app, permissions screens explain required access, notifications communicate important state, and an updates module manages version-related behavior. This keeps setup and maintenance flows distinct from the steady-state menu bar management path.

14. Build, packaging, and automation boundary

The repo includes GitHub Actions for build, DMG creation, signing, notarization, release, translation checks, and CI. ThawCtl is a separate SwiftPM-based companion utility likely used for control/packaging workflows. Tests are extensive and cover layout planning, profiles, menu bar shapes, settings, gates, and replay fixtures, which suggests the architecture is heavily algorithmic and regression-sensitive.

15. Overall request/response flow

In steady state, macOS events and hotkeys drive the main app; the app queries or receives menu bar item data from the helper service; layout/reconciliation computes the target arrangement; the UI presents bars, overlays, and settings; and persistent settings/profiles determine how the system behaves across launches. The cleanest diagram would show the helper/service, the event/input layer, the layout engine, the UI/appearance layer, and the persistence/settings layer as separate but connected subsystems.