Codex Micro Wispr Bridge

A small native macOS helper that maps the unassigned double-width key on a Codex Micro to Wispr Flow push-to-talk while preserving the Micro's native Codex layer, Agent Keys, status lighting, dial, and other command keys.

Warning

This experimental project uses undocumented Work Louder HID messages and undocumented Wispr Flow deep links. Either vendor may change those interfaces without notice.

This project is not affiliated with or endorsed by OpenAI, Work Louder, or Wispr Flow.

Behavior

• Hold the unassigned microphone-position key to start Wispr Flow.
• Release it to stop dictation and insert the transcription.
• Optionally say press enter to let Wispr submit after pasting.
• Continue using Codex Micro Layer 1 for every other native control.

The helper opens the Codex Micro non-exclusively, filters for the vendor HID event ACT10, and invokes these background URLs:

• wispr-flow://start-hands-free
• wispr-flow://stop-hands-free

The same physical key also emits ACT11; that duplicate event is deliberately ignored.

At startup and before each action, the bridge verifies that macOS has an application registered for wispr-flow:// links. Missing handlers and URL-open failures are reported in the bridge log instead of failing silently.

Requirements

• macOS 13 or later
• Xcode Command Line Tools or Xcode
• Codex Micro connected by USB or Bluetooth
• Wispr Flow installed and configured
• The microphone-position key set to blank/unassigned in Codex Micro settings
• Input Monitoring permission for Codex Micro Wispr Bridge

The initial hardware and app combination was validated on macOS 26.5.2 with Codex Micro firmware release 177 and Wispr Flow 1.6.122.

Install from source

git clone https://github.com/peteallport/CodexMicroWisprBridge.git
cd CodexMicroWisprBridge
./Scripts/install.sh

On first install, macOS opens System Settings → Privacy & Security → Input Monitoring. Enable Codex Micro Wispr Bridge, then restart the agent:

./Scripts/restart.sh

The installation is user-scoped and does not require sudo.

Generated app bundles are placed under the system temporary directory by default so cloud-backed source folders cannot attach metadata that invalidates code signing. Set BRIDGE_BUILD_ROOT to override the build location.

Updating from the initial private build

The current build uses the bundle identifier io.github.peteallport.CodexMicroWisprBridge. The installer removes the old com.peterallport LaunchAgent automatically. Because macOS associates Input Monitoring approval with an application's identity, you may need to enable the bridge again after this one-time migration and then run ./Scripts/restart.sh.

Compatibility

Component	Version	Status
macOS	26.5.2	Physically validated
Codex Micro firmware	Release 177	Physically validated
Wispr Flow	1.6.122	Start and stop behavior physically validated
Wispr Flow	1.6.182	URL-scheme registration validated; full key test pending
macOS	13 or later	Build target; additional reports welcome

See Experimental protocol notes for the observed HID message format, Wispr URLs, compatibility caveats, and safe reporting guidance.

Verify and troubleshoot

./Scripts/status.sh
tail -f "$HOME/Library/Logs/CodexMicroWisprBridge/bridge.log"

A healthy start includes:

Codex Micro to Wispr Flow bridge started.
Codex Micro connected.

If the key stops responding after an app, firmware, or macOS update:

1. Confirm that the app remains enabled under Input Monitoring.
2. Run ./Scripts/restart.sh.
3. Check bridge.log and bridge-error.log.
4. Confirm that Wispr still recognizes both wispr-flow:// URLs.

Uninstall

./Scripts/uninstall.sh

Logs are retained by default. Use ./Scripts/uninstall.sh --purge-logs to remove them too. Remove the app from Input Monitoring manually if desired.

Privacy and security

macOS Input Monitoring is a broad permission. This helper narrows its own behavior to the Codex Micro's USB vendor and product IDs and ignores every HID message except ACT10 press and release. It does not record audio, read transcribed text, inspect the clipboard, inject keystrokes, or communicate over the network. Wispr Flow handles microphone access, transcription, insertion, and the optional spoken press enter command.

License

Codex Micro Wispr Bridge is available under the MIT License. The license covers this repository's original code and documentation; it does not grant rights in vendor software, firmware, product names, or trademarks.