Local Device Bridge

Local Device Bridge is a local-network companion app pair for Android and macOS. It connects one Android phone to one Mac for encrypted file transfer, automatic text clipboard synchronization, and Android notification mirroring. There is no cloud service, account system, analytics SDK, or internet relay.

Features

• Bonjour/NSD discovery on the same Wi-Fi or LAN
• Eight-digit, time-limited pairing with secure trust storage
• Encrypted sessions using P-256 ECDH, HKDF-SHA256, and AES-256-GCM
• Android-to-Mac and Mac-to-Android file transfer
• 64 KiB streaming chunks, SHA-256 verification, and duplicate-safe names
• Automatic text clipboard sync with independent controls on both devices
• Android notification mirroring with global and per-app controls
• Android Share Sheet target named Send to Mac
• macOS Share Extension named Android Phone
• Foreground Android connection service, heartbeat, and automatic reconnect

Repository Structure

.
├── android-app/   # Kotlin and Jetpack Compose Android app
├── macos-app/     # SwiftUI menu bar app and Share Extension
├── docs/          # Protocol, testing, release, and limitations documentation
├── script/        # Build, install, launch, and verification scripts
├── README.md
└── .gitignore

The macOS Xcode project is generated from macos-app/project.yml with XcodeGen. A generated shared project and scheme are also included for convenience.

Requirements

Android

• Android 12 or newer (API 31+)
• Android SDK 36
• JDK 21
• Android Studio or the included Gradle wrapper
• A physical Android device is recommended for discovery and integration tests

macOS

• macOS 15 or newer
• Xcode with the macOS 15+ SDK
• XcodeGen
• A locally signed build for runtime testing

Both devices must be on the same Wi-Fi or LAN. Routers with client/AP isolation enabled may prevent discovery and connection.

Quick Start

1. Clone

git clone https://github.com/gour6380/macdroid-link
cd macdroid-link

2. Verify Both Projects

./script/verify_all.sh

The verification script runs Android clean, unit test, lint, debug assembly, and instrumentation-APK compilation. Connected Android tests run when an authorized device is attached. It then regenerates and tests the macOS app and Share Extension.

3. Build Android

cd android-app
./gradlew assembleDebug

The debug APK is written to:

android-app/app/build/outputs/apk/debug/app-debug.apk

4. Build macOS

cd macos-app
xcodegen generate
xcodebuild \
  -project LocalDeviceBridge.xcodeproj \
  -scheme LocalDeviceBridge \
  -configuration Debug \
  -derivedDataPath DerivedData \
  CODE_SIGNING_ALLOWED=NO \
  build

For a local ad-hoc signed build and launch:

./script/build_and_run.sh

Pairing

1. Put the Android phone and Mac on the same Wi-Fi or LAN.
2. Launch Local Device Bridge on the Mac and enable Connection.
3. Launch the Android app and open Pairing.
4. Choose the discovered Mac.
5. In the Mac menu, choose Pair New Device to display a pairing code.
6. Enter the code on Android before it expires.
7. Confirm both apps report Connected.

After a trusted pair has connected once, the apps automatically reconnect when both devices and apps return to the same network with connection enabled.

Using The Bridge

Files

• Android to Mac: use Files in the Android app or choose Send to Mac from an Android Share Sheet.
• Mac to Android: choose Send File to Android from the menu bar app or Share > Android Phone in Finder.
• Mac receives files in ~/Downloads/LocalDeviceBridge.
• Android receives files in Downloads/LocalDeviceBridge.

Clipboard

Enable clipboard sync on both devices. Text copied on either device is forwarded automatically while connected. Android-to-Mac clipboard observation works only while the Android app is in the foreground because of Android clipboard privacy restrictions.

Notifications

Grant notification-listener access on Android, notification permission on macOS, and enable notification mirroring on both devices. Android Settings in the app provides immediate per-app filtering. Disabling notifications does not disable files or clipboard sync.

Permissions

Android uses network, Wi-Fi multicast, notification, foreground connected device, boot-completed, notification-listener, and user-selected content access. Files are selected through Android system pickers or share intents.

macOS uses local-network discovery, client/server networking, notification permission, Downloads access, and user-selected file access. The sandboxed Share Extension has read-only access to the selected file.

Security And Privacy

• Pairing uses an eight-digit code valid for two minutes.
• Pairing performs P-256 ECDH and authenticates the transcript with HMAC.
• Session frames use AES-256-GCM with sequence-based replay protection.
• Framing and file sizes are bounded.
• Received files remain temporary until their SHA-256 digest is verified.
• Android trust material is protected by Android Keystore.
• macOS trust material is stored in Keychain.
• Clipboard and notification payload contents are not intentionally logged.

The protocol is documented in docs/protocol.md.

Known Limitations

• Version 1 pairs exactly one Android phone with one Mac.
• The bridge works only on the same local network.
• Android background clipboard reads are unsupported.
• The locally signed Mac build is not notarized for distribution.
• The Share Extension requires the menu app to be running and asks for host confirmation before forwarding.
• Notification actions and replies are not mirrored.

See docs/known-limitations.md for the maintained list.

Verification Status

Runtime testing on June 10, 2026 verified:

• Automatic discovery, secure connection, disconnect, and reconnect
• Bidirectional file transfer with matching SHA-256 values
• Duplicate-safe file naming
• Clipboard sync in both directions and independent toggles
• Notification mirroring, global toggles, and per-app filtering
• Android Share Sheet transfer to macOS
• macOS Share Extension confirmation and transfer to Android
• Foreground service and connection stability
• Absence of synthetic clipboard and notification contents in app logs

Automated and physical-device test expectations are tracked in docs/testing.md.

Development Documentation

• Android app
• macOS app

License

License not selected yet.