No description
  • TypeScript 47.6%
  • Swift 42.1%
  • JavaScript 7.3%
  • Shell 3%
Find a file
hicham 44b6f7dbfe
All checks were successful
mac / build (push) Successful in 24s
release / release (push) Successful in 3m56s
Fix the launch crash on macOS 13
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.
2026-11-14 12:54:28 +01:00
.forgejo/workflows Name release runs after their tag 2026-11-07 14:24:36 +01:00
assets Use the app icon in the menu bar 2026-11-07 13:49:17 +01:00
docs Rewrite the README and move the protocol to docs/ 2026-11-07 14:07:13 +01:00
mac Fix the launch crash on macOS 13 2026-11-14 12:54:28 +01:00
mobile Build the Android app in CI and attach a signed APK to releases 2026-11-07 14:20:24 +01:00
.gitignore Add KeyBridge: use a phone as a Bluetooth keyboard for the Mac 2026-11-05 11:17:57 +01:00
install.sh Add a one-line Mac install script 2026-11-07 18:13:20 +01:00
LICENSE Add MIT license 2026-11-07 14:08:32 +01:00
README.md Add a one-line Mac install script 2026-11-07 18:13:20 +01:00

KeyBridge icon

KeyBridge

macOS build Android build

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

  1. On the phone, download KeyBridge-<version>-android.apk from the latest release.
  2. 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

  1. Click the KeyBridge icon in the menu bar and open Pair a Phone.
  2. Scan the QR code with the KeyBridge app, or with the phone camera, which opens the app.
  3. 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.