- TypeScript 47.6%
- Swift 42.1%
- JavaScript 7.3%
- Shell 3%
The status item was created before NSApplication.shared, so there was no window server connection yet and macOS 13 aborted in CGSConnectionByID. Newer releases connect on demand, which hid it. |
||
|---|---|---|
| .forgejo/workflows | ||
| assets | ||
| docs | ||
| mac | ||
| mobile | ||
| .gitignore | ||
| install.sh | ||
| LICENSE | ||
| README.md | ||
KeyBridge
Type on your Mac from your phone over Bluetooth.
KeyBridge is a menu bar app for the Mac and a keyboard app for Android and iOS. The phone sends what you type over an encrypted Bluetooth LE link. There is no server or account.
- Uses the phone's own keyboard, so autocorrect, swipe typing and paste work
- Modifiers for shortcuts (⌃ ⌥ ⌘ ⇧), arrows, Home, End, Page Up/Down, F1 to F12 and media keys
- Works with any keyboard layout on the Mac
- Pairs by scanning a QR code
macOS doesn't let apps act as a standard Bluetooth keyboard, so the phone talks to the menu bar app instead, which types with system input events. That's why it needs Accessibility access.
Requirements
- A Mac with macOS 12 or later, Apple Silicon or Intel
- An Android phone with Android 7 or later on 64-bit ARM, or an iPhone (the iOS build hasn't been tested on a device yet)
Install
Mac
Run this in Terminal:
curl -fsSL https://git.hicham.party/hicham/keybridge/raw/branch/main/install.sh | sh
It installs the latest release in Applications and opens it. Run it again to update. Allow Bluetooth, then choose Grant Accessibility Access… in the KeyBridge menu and turn KeyBridge on in System Settings › Privacy & Security › Accessibility.
To install by hand, download KeyBridge-<version>-macOS.zip from the latest release, unzip it and move KeyBridge to Applications. The app isn't notarized, so clear the quarantine flag before the first launch:
xattr -dr com.apple.quarantine /Applications/KeyBridge.app
Android
- On the phone, download
KeyBridge-<version>-android.apkfrom the latest release. - Open it and allow your browser or file manager to install apps when asked.
iPhone
There is no App Store release. Build the app from source, see Building.
Usage
- Click the KeyBridge icon in the menu bar and open Pair a Phone.
- Scan the QR code with the KeyBridge app, or with the phone camera, which opens the app.
- Type in the text field at the bottom of the app. Tap a modifier to apply it to the next key, long-press it to lock it.
The menu bar icon is filled while a phone is connected. Reset Pairing creates a new code and disconnects phones that used the old one.
Building
Mac
Needs Xcode with Swift 6.
git clone https://git.hicham.party/hicham/keybridge.git
cd keybridge/mac
./build.sh # universal app in build/KeyBridge.app
swift test
build.sh signs the app ad hoc, or with SIGN_IDENTITY if set. It fails if the binary isn't universal or doesn't target the LSMinimumSystemVersion in Info.plist.
Phone
The app uses react-native-ble-plx, so it needs a development build. Expo Go won't work.
cd mobile
npm install
npx expo run:android --device # or: npx expo run:ios --device
npm run android:release # standalone arm64 build, installed on the connected phone
npm test && npm run typecheck && npx expo lint
Local builds are signed with the debug key and release APKs with the release key, so Android refuses to update one with the other. Uninstall the app first when switching.
For an iPhone, add your Apple ID in Xcode › Settings › Accounts and turn on Developer Mode on the phone. With a free Apple ID the app stops opening after 7 days.
Icons
assets/icons.mjs draws the app, phone and menu bar icons from one source. Run npm run icons in mobile/ to regenerate them.
Releases
mac.yml and android.yml in .forgejo/workflows/ test and build the apps on every push to main. Pushing a version tag publishes a release:
git tag -m "KeyBridge v0.2.0" v0.2.0
git push origin v0.2.0
release.yml builds both apps with that version and attaches KeyBridge-0.2.0-macOS.zip and KeyBridge-0.2.0-android.apk to the release. It runs on a Mac runner and signs the APK with ~/.android/keybridge-release.jks, whose password is in the login keychain under keybridge-android-keystore.
How it works
The Mac app advertises a Bluetooth LE service whose UUID is part of the pairing code. The phone connects, reads a fresh challenge and derives a session key from it and the pairing secret. Every frame is encrypted with ChaCha20-Poly1305 and carries an increasing counter, so the Mac drops forged and replayed frames. Text is typed as Unicode and shortcuts are mapped through the Mac's current keyboard layout.
The full protocol is in docs/protocol.md.
| Directory | Contents |
|---|---|
mac/ |
Menu bar app (Swift, AppKit, CoreBluetooth) |
mobile/ |
Phone app (Expo, React Native) |
assets/ |
Icon sources |
docs/ |
Protocol |
License
MIT, see LICENSE.