WakeBridge

WakeBridge is a macOS menu-bar host for activating ChatGPT Voice from a local wake phrase. It keeps ChatGPT responsible for GPT-Live and emits the dedicated global Voice shortcut already supported by the desktop app.

The current vertical slice includes:

• a native AppKit menu-bar shell
• local AVAudioEngine microphone capture with no recording
• a replaceable wake-word detector protocol
• a pinned sherpa-onnx English detector for “Hey Codex”
• a polished four-page settings window with live health checks
• a native shortcut recorder that captures the pressed key chord
• a Safe Test Lab that never emits the ChatGPT Voice shortcut
• a custom English phrase designer with exact BPE tokenization
• up to three simultaneously enabled wake phrases
• per-phrase enable, test, and removal controls
• launch-at-login support through macOS Service Management
• microphone engine recovery after audio-route changes and system sleep
• a bounded serial inference queue outside the audio callback
• safe shortcut parsing and persistent local configuration
• CoreGraphics shortcut emission gated by Accessibility permission
• a ChatGPT-running guard before any keyboard event is emitted
• a two-second refractory period that suppresses duplicate activation
• a diagnostic mode that does not capture audio or emit keyboard events

The first detector uses sherpa-onnx 1.13.4 and the official English GigaSpeech 3.3M KWS model. Both runtime and model downloads are checksum pinned.

Requirements

• Apple Silicon Mac
• macOS 14 or newer
• Swift 6.3 toolchain with a matching macOS SDK
• ChatGPT desktop with a dedicated Voice chat hotkey configured

Build

scripts/setup-sherpa.sh
scripts/test.sh
scripts/build-app.sh

The bundle is created at:

.build/WakeBridge.app

Run safe diagnostics:

.build/WakeBridge.app/Contents/MacOS/WakeBridge --diagnose

Verify that the bundled model loads and rejects silence:

.build/WakeBridge.app/Contents/MacOS/WakeBridge --detector-smoke

Verify real microphone callbacks without storing audio or emitting keys:

.build/WakeBridge.app/Contents/MacOS/WakeBridge --capture-smoke

The capture smoke runs for about 1.5 seconds. It prints frame and sample counts, then confirms that audio retention is disabled.

Verify custom phrase tokenization:

.build/WakeBridge.app/Contents/MacOS/WakeBridge \
    --phrase-smoke "Hey Computer"

Verify a combined built-in plus two-custom-phrase detector:

.build/WakeBridge.app/Contents/MacOS/WakeBridge --multi-phrase-smoke

Verify launch-at-login registration and restore the previous state:

cp -R .build/WakeBridge.app /Applications/
/Applications/WakeBridge.app/Contents/MacOS/WakeBridge \
    --launch-at-login-smoke

Run a 30-second spoken detector test without keyboard emission:

.build/WakeBridge.app/Contents/MacOS/WakeBridge --wakeword-smoke

Launch the menu-bar app:

open .build/WakeBridge.app

First Manual Test

1. Configure an uncommon Voice chat hotkey in ChatGPT Settings > Voice.
2. Open WakeBridge Settings > Integration.
3. Click the shortcut field and press the exact same chord.
4. Grant microphone permission. Audio is processed locally and discarded.
5. Grant Accessibility access only when ready to test keyboard emission.
6. Select Test in ChatGPT once and confirm ChatGPT starts one new Voice task.
7. Close the Voice session, then open Test Lab and run five safe trials.
8. Resume listening and say “Hey Codex” once.
9. Optionally enable Launch at Login on the Integration page.

To use another hotword, open Wake Phrases > Design New Phrase. WakeBridge tokenizes the phrase locally, opens Safe Test automatically, and requires at least three detections across five prompted trials before the phrase can be activated. Up to three phrases can be enabled at once. All enabled phrases trigger the same configured ChatGPT Voice shortcut.

The test action can toggle an active Voice task off if used while Voice is already running. Close or stop the existing Voice session before repeating the test.

Ad hoc signatures change when the app is rebuilt. macOS may require WakeBridge to be toggled off and back on in Privacy & Security > Accessibility after each development build.

Persistent Local Permissions

Create a self-signed code-signing identity in the user login Keychain once:

scripts/setup-local-signing.sh

Build, sign, install, verify, and launch WakeBridge with that stable identity:

scripts/install-local.sh

This local identity costs nothing and requires no Xcode installation or Apple Developer Program membership. It is trusted only on the current Mac and is not appropriate for distributing binaries to other users. The local build omits Hardened Runtime because self-signed certificates do not have an Apple Team ID. Developer ID release builds retain Hardened Runtime.

After switching from an ad hoc build, toggle WakeBridge off and back on once in Privacy & Security > Accessibility. Later local builds signed with the same identity keep the same designated requirement.

Distribution

Development builds are ad hoc signed. A public macOS build should use a stable Developer ID identity, Hardened Runtime, notarization, and stapling:

CODESIGN_IDENTITY="Developer ID Application: Your Name (TEAMID)" \
    CONFIGURATION=release scripts/build-app.sh

APPLE_NOTARY_PROFILE="wakebridge-notary" scripts/notarize.sh

See docs/distribution.md for the complete release checklist. The selected GigaSpeech KWS model archive declares Apache License 2.0, and its artifact details and source URL are recorded in THIRD_PARTY_NOTICES.md.

Contributing

Contributions are welcome. Read CONTRIBUTING.md, SECURITY.md, and THIRD_PARTY_NOTICES.md before opening a change.

Safety Properties

• No default shortcut is emitted.
• No shortcut is emitted while ChatGPT is closed.
• At least two modifiers are required.
• Audio is not written to disk or sent over the network.
• Safe smoke modes never emit a keyboard event.
• Phrase candidates remain isolated from Voice activation during Safe Test.
• At least one and at most three wake phrases are enabled.
• Detector work runs outside the real-time audio callback.
• Queued audio is bounded to about 500 ms and discarded after inference.
• Duplicate activation inside two seconds is suppressed.
• WakeBridge does not patch or inject into ChatGPT.

See SPEC.md, tasks/plan.md, and wakeword-plan.html for the design and roadmap.