Settings & Onboarding
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
The Settings and Onboarding systems in MacParakeet provide the foundational user experience for configuring local-first voice capture and speech-to-text (STT) services. The onboarding flow is designed as a linear sequence of steps to guide new users through essential permissions, hotkey configuration, and speech model downloads. The Settings interface facilitates ongoing management of capture modes (Dictation, Transcription, and Meeting Recording), engine selection, AI provider integration, and system-level diagnostics.
These systems emphasize a "local-first" posture, ensuring that audio and transcripts remain on-device while providing explicit surfaces for cloud LLM providers and telemetry. The architecture has evolved from a monolithic card-stack into a tabbed, searchable interface designed to minimize friction and maximize findability for advanced daily workflows.
Sources: AGENTS.md, plans/active/2026-04-settings-ia-overhaul.md:25-50, spec/adr/005-onboarding-first-run.md
Onboarding Architecture
Onboarding is managed by the OnboardingViewModel, which defines a series of discrete steps. The flow prioritizes dictation-first activation by reducing steps that are not strictly necessary for the core product experience.
Onboarding Steps and Logic
The onboarding process follows a specific sequence intended to ensure the app has the necessary rights to function:
- Welcome: Introduction to the app.
- Microphone: Requesting audio input permissions.
- Accessibility: Required for system-wide dictation and hotkey events.
- Hotkey: Configuring the trigger for dictation.
- Speech Model: The engine warm-up and model download phase (~465 MB for Parakeet).
- Ready: Final confirmation and transition to the main application.
Sources: plans/active/2026-05-dictation-first-onboarding.md:43-52, spec/adr/005-onboarding-first-run.md
Flow Diagram: Onboarding Sequence
The following diagram illustrates the linear transition between onboarding steps and the idempotent model warm-up trigger.
Settings Information Architecture
The Settings interface is organized into four primary tabs: Modes, Engine, AI, and System. This structure is designed to separate daily operational configuration from infrastructure and diagnostic tools.
Tabbed Structure
| Tab | Focus Area | Key Components |
|---|---|---|
| Modes | Daily capture operations | Audio Input (Mic), Dictation, Transcription, Meeting Recording |
| Engine | Speech recognition stack | Engine Selector (Parakeet/Whisper), Language settings, Model management |
| AI | LLM provider config | Provider selection (Claude, OpenAI, Local Apps), Advanced API settings |
| System | App infrastructure | Startup (Launch at login), Permissions dashboard, Storage, Updates, Privacy |
Sources: plans/active/2026-04-settings-ia-overhaul.md:65-115
Data Flow and View Models
The Settings architecture utilizes a composition of focused View Models managed by a SettingsRootViewModel. This prevents the creation of a "god object" and allows for independent testing of sub-sections.
AI Configuration and Setup
MacParakeet supports various AI providers for transcript summaries, chat, and meeting insights. The system is designed to favor local AI apps (LM Studio, Ollama) but maintains compatibility with cloud-based API services.
AI Readiness States
Feature surfaces (like Transcript Chat) monitor the AIReadinessState to determine how to present the interface to the user:
- Set Up Needed: No configuration exists. A setup prompt is shown.
- Ready: Configuration is valid and a recent attempt succeeded. The feature is fully functional.
- Can't Connect: A saved configuration failed its last actual attempt. An error state with retry options is shown.
Sources: plans/active/2026-05-ai-setup-ux.md:135-148
LLM Settings Draft Refactor
To prevent async race conditions during connection tests, the LLMSettingsViewModel utilizes a LLMSettingsDraft model. This separates editable fields from side effects.
public struct LLMSettingsDraft: Equatable, Sendable {
var providerID: LLMProviderID
var apiKeyInput: String
var selectedSuggestedModel: String
var usesCustomModel: Bool
var customModelName: String
var baseURLOverride: String
}
Sources: plans/completed/2026-02-llm-settings-state-refactor.md:40-50
Search and Navigation
The settings interface includes a "flat-when-searching" architecture. When the search field is non-empty, the tabbed layout collapses into a unified results list grouped by tab name.
- Search Index: Built from a hierarchy of
SettingsSearchEntryobjects, mapping keywords to specific tab/card/row locations. - Deep Linking: Clicking a search result triggers navigation to the specific
SettingsTab, scrolls the card into view, and provides a visual accent flash on the target row. - Shortcuts: Tab navigation is supported via
⌘1–⌘4keyboard shortcuts.
Sources: plans/active/2026-04-settings-ia-overhaul.md:175-200, plans/active/2026-04-settings-ia-overhaul.md:218-220
Conclusion
The Settings and Onboarding modules form a cohesive configuration layer that balances immediate usability for dictation with deep extensibility for power users and AI integrations. By utilizing a modular ViewModel architecture and a centralized state machine for onboarding, MacParakeet ensures that infrastructure setup remains reliable and non-intrusive to the core voice capture experience.