Native macOS App
Relevant source files
The following files were used as context for generating this wiki page:
The Happy macOS application is a native client designed to provide a first-class desktop experience for Claude Code remote control and session sharing. Built using Swift and SwiftUI, it integrates deeply with macOS-specific features such as the menu bar, Touch Bar, and native window management, while maintaining end-to-end encryption for all session data.
The application serves as a native peer to the happy-app (React Native mobile/web) and happy-cli, connecting to the backend via WebSockets for real-time synchronization. It implements a zero-knowledge architecture where the server acts only as an encrypted relay, ensuring that session content remains private to the user's devices.
Sources: apps/macos/README.md:1-12, apps/macos/CLAUDE.md:10-15, CLAUDE.md:16-25
Architecture and Design Patterns
The application is built on the MVVM (Model-View-ViewModel) pattern, prioritizing SwiftUI for the user interface and modern Swift concurrency for asynchronous operations.
MVVM implementation
- Models: Plain Swift structs that conform to
Codable. These are often generated from shared Zod schemas to ensure protocol consistency across the monorepo. - Views: Focused SwiftUI views responsible for rendering. Business logic is strictly kept out of views.
- ViewModels: Classes marked with
@Observable(macOS 14+) orObservableObject(for backward compatibility) that manage view state and interface with services. - Services: Actors or singletons handling networking, synchronization, and cryptography.
Sources: apps/macos/README.md:74-82, apps/macos/CLAUDE.md:17-30
Technical Stack
| Category | Technology |
|---|---|
| UI Framework | SwiftUI (primary), AppKit (fallback) |
| Reactivity | Combine |
| Concurrency | Async/await, Actors |
| Encryption | CryptoKit (AES-256-GCM) |
| Networking | URLSession, WebSockets |
| Storage | Keychain (via Security framework) |
Sources: apps/macos/README.md:84-93, apps/macos/CLAUDE.md:163-166
Core Services and Logic Flow
The app relies on three primary services to facilitate remote control of Claude Code.
APIService and SyncService
The APIService handles standard HTTP communication (fetching sessions, posting configurations), while the SyncService manages a persistent WebSocket connection for real-time updates.
This diagram shows the communication flow between the native UI and the remote Claude CLI via the Happy Server.
Sources: apps/macos/CLAUDE.md:73-89, CLAUDE.md:213-222
EncryptionService
Security is implemented using AES-256-GCM. The application uses a specific bundle format for encrypted data to ensure cross-platform compatibility with the CLI and mobile apps.
Encryption Bundle Format:
[version:1][nonce:12][ciphertext:N][authTag:16]
Key derivation is handled via X25519 ECDH with HKDF.
Sources: apps/macos/CLAUDE.md:91-105, apps/mobile/ios/CLAUDE.md:139-152
Key Features and Modules
Artifacts Browser
A native file browser for viewing files generated during Claude Code sessions. It supports:
- Native file tree navigation using
OutlineGroup. - QuickLook integration for file previews.
- Syntax highlighting for over 8 languages.
- Drag-and-drop support to Finder.
Sources: apps/macos/CLAUDE.md:209-230
Voice Features
Integrated with ElevenLabs Conversational AI, the app allows users to interact with Claude via voice.
This sequence illustrates the real-time audio pipeline for the voice assistant feature.
Sources: apps/macos/CLAUDE.md:168-193
In-App Purchases
Subscription management is handled via the RevenueCat SDK, integrating StoreKit 2 for native purchase sheets and entitlement gating.
Sources: apps/macos/CLAUDE.md:197-207
Development and Configuration
Keyboard Shortcuts and Commands
The app implements extensive keyboard support for power users:
| Shortcut | Action |
|---|---|
⌘R | Refresh Session / Artifacts |
⌘N | Scan New Connection |
⇧⌘A | Show Artifacts Browser |
⇧⌘V | Toggle Voice Assistant |
⇧⌘M | Toggle Microphone Mute |
Space | QuickLook Preview |
Sources: apps/macos/CLAUDE.md:155-159, apps/macos/CLAUDE.md:225-230
Project Structure
apps/macos/
├── Happy/
│ ├── HappyApp.swift # App entry point
│ ├── Models/ # Codable structs
│ ├── Views/ # SwiftUI views
│ ├── ViewModels/ # @Observable logic
│ ├── Services/ # API, Sync, Encryption
│ └── Generated/ # Protocol-shared Swift types
└── HappyTests/ # XCTest suite
Sources: apps/macos/README.md:57-70, packages/schema/protocol/CLAUDE.md:37-40
Protocol Integration
The application uses generated Swift types to maintain compatibility with the shared monorepo protocol. These types are generated from Zod schemas located in packages/schema/protocol/.
Generation Command:
yarn workspace @magic-agent/protocol generate:swift
This process converts Zod schemas into JSON Schemas, which are then transformed into Swift Codable structs using quicktype.
Sources: packages/schema/protocol/CLAUDE.md:28-40, apps/mobile/ios/CLAUDE.md:231-240
Conclusion
The Native macOS App provides a robust, encrypted environment for interacting with Claude Code. By utilizing SwiftUI and modern Swift concurrency, it offers a high-performance experience that remains synchronized with the broader Happy ecosystem through shared protocols and end-to-end encryption standards.
Sources: apps/macos/README.md:5-12, apps/macos/CLAUDE.md:10-15