Native iOS & Android Apps
Relevant source files
The following files were used as context for generating this wiki page:
The native mobile applications in the Happy project provide a first-class experience for remote control and session sharing with Claude Code and Codex. These apps act as secure, end-to-end encrypted clients that allow users to monitor AI coding agents, approve permissions, and interact with sessions from anywhere.
The iOS and Android clients complement the primary React Native mobile/web app by offering native performance, platform-specific integrations (like Apple Push Notification service and Google Play Billing), and deep OS-level features such as widgets and background services.
Sources: CLAUDE.md, apps/mobile/ios/CLAUDE.md:14-25, apps/mobile/android/CLAUDE.md:8-12
Architectural Pattern: MVVM
Both native platforms follow the Model-View-ViewModel (MVVM) pattern combined with Clean Architecture principles. This ensures a strict separation of concerns between the user interface, business logic, and data synchronization services.
iOS Architecture (Swift & SwiftUI)
The iOS app targets iOS 16.0+ and is built entirely with SwiftUI for the UI layer, utilizing Swift Concurrency (async/await) for asynchronous operations and the Combine framework for reactivity.
The diagram shows the unidirectional data flow from Services to Views via ViewModels in the iOS implementation.
Sources: apps/mobile/ios/CLAUDE.md:73-86, apps/mobile/ios/CLAUDE.md:129-132
Android Architecture (Kotlin & Jetpack Compose)
The Android app utilizes Jetpack Compose for declarative UI, Hilt for Dependency Injection, and Kotlin Coroutines/Flow for reactive data streams. It adheres to Clean Architecture layers (Data, Domain, and UI).
The diagram represents the Clean Architecture layers used in the Android native client.
Sources: apps/mobile/android/CLAUDE.md:14-29, apps/mobile/android/CLAUDE.md:65-98
Core Features and Implementation
Security and Encryption
Both platforms implement identical end-to-end encryption (E2E) to remain compatible with the happy-cli. All session data is encrypted client-side using AES-256-GCM.
- iOS Implementation: Uses
CryptoKitfor AES-256-GCM and X25519 ECDH key derivation. - Android Implementation: Uses the
Google Tinklibrary and Java Cryptography Architecture (JCA). - Secure Storage: iOS utilizes the Security framework (Keychain) via a
KeychainHelper, while Android uses Android Keystore andDataStore.
Sources: apps/mobile/ios/CLAUDE.md:154-173, apps/mobile/android/CLAUDE.md:131-147, apps/mobile/ios/CLAUDE.md:214-218
Synchronization and Networking
The apps maintain a real-time connection to the Happy Server using WebSockets for session updates and REST for administrative actions.
| Component | iOS Implementation | Android Implementation |
|---|---|---|
| HTTP Client | URLSession | Retrofit + OkHttp |
| WebSocket | URLSessionWebSocketTask | OkHttp WebSocket |
| Real-time Flow | Combine Publishers | Kotlin Flow |
| Reconnection | Native retry logic | SyncLifecycleManager |
Sources: apps/mobile/ios/CLAUDE.md:43-51, apps/mobile/android/CLAUDE.md:162-178, apps/mobile/android/CLAUDE.md:195-195
Hardware and Platform Integration
The native apps leverage platform-specific hardware capabilities to facilitate the connection between the mobile device and the CLI.
- QR Code Scanner:
- iOS: Uses
AVFoundationfor high-performance scanning. - Android: Uses
CameraXcombined withML Kit.
- iOS: Uses
- Push Notifications:
- iOS: Integrated with APNs (Apple Push Notification service) with specific categories for
SESSION_UPDATE,MESSAGE, andPAIRING. - Android: Integrated with FCM (Firebase Cloud Messaging) including support for rich notifications and channels.
- iOS: Integrated with APNs (Apple Push Notification service) with specific categories for
- Voice Features: Both platforms support ElevenLabs TTS with system fallbacks (AVFoundation on iOS, System TTS on Android).
Sources: apps/mobile/ios/CLAUDE.md:251-267, apps/mobile/android/CLAUDE.md:183-195, apps/mobile/ios/CLAUDE.md:48-55
Data Synchronization Flow
The following sequence illustrates how a native app (iOS/Android) connects and synchronizes with a terminal session.
Sequence diagram showing the pairing and encrypted synchronization flow.
Sources: apps/mobile/ios/CLAUDE.md:174-174, apps/mobile/android/CLAUDE.md:143-147, CLAUDE.md:329-350
Project Status and Requirements
Development Requirements
| Requirement | iOS (Native) | Android (Native) |
|---|---|---|
| Language | Swift 5.9+ | Kotlin 1.9.22+ |
| Min OS | iOS 16.0 | Android 8.0 (SDK 26) |
| Tooling | Xcode 15.0+ | Android Studio Hedgehog+ |
| UI Framework | SwiftUI | Jetpack Compose |
Sources: apps/mobile/ios/CLAUDE.md:104-109, apps/mobile/android/CLAUDE.md:45-53
Feature Maturity Matrix
| Feature | iOS Status | Android Status |
|---|---|---|
| E2E Encryption | Done | Done |
| QR Authentication | Done | Done |
| WebSocket Sync | Done | Done |
| Push Notifications | Done | Done |
| Voice Features | Done | Done |
| In-App Purchases | RevenueCat | Google Play Billing |
| Artifacts Viewer | Syntax Highlighted | Syntax Highlighted |
| Social/Friends | Done | Done |
Sources: apps/mobile/ios/CLAUDE.md:30-58, apps/mobile/android/CLAUDE.md:180-211
Conclusion
The Native iOS and Android applications provide robust, platform-optimized entry points into the Happy ecosystem. By utilizing native SDKs for critical functions—such as CryptoKit and Tink for security, or AVFoundation and CameraX for hardware access—they deliver a high-performance alternative to the React Native implementation while maintaining total compatibility with the shared encryption protocol.