freeflow-button

What It Does

A single full-screen button on the iPhone, branded as FreeFlow Button on the home screen. Tap it, and the paired Mac presses Right Option — the FreeFlow push-to-talk key. The phone becomes a silent remote for FreeFlow dictation without having to reach for the keyboard.

When To Use

• When you want to start dictating from across the room without touching the Mac.
• When you want to keep dictation push-to-talk but the Right Option key is awkward to hold during long thinking-out-loud sessions.
• When pairing FreeFlow with a podcasting or recording setup where the Mac is not within arm’s reach.

How It Works

1. iPhone holds a SwiftUI app with one giant button.
2. Mac runs a tiny Python http.server listener on port 8765, managed by a launchd user agent.
3. Tap the button → POST to the listener with a shared secret in the Authorization header.
4. Listener invokes a Swift binary (press-right-option) that uses CGEventPost to fire keycode 61 (Right Option).
5. FreeFlow on the Mac sees the keypress and starts (or stops) dictation.

Transport is mDNS first (james-macbook-pro.local, jamess-mac-studio.local), Tailscale hostnames as fallback for when the laptop is off-network.

Where It Lives

• Repo: ~/apps/freeflow-button/
• iOS source: ios/Sources/
• Mac listener: mac/listener.py, mac/install.sh, plus the Swift helper that fires the keypress
• Shared secret: mac/secret.txt and ios/Sources/Secret.swift — both gitignored, generated once by mac/install.sh.

Install

Mac side (one Mac at a time — typically MBP for daily use, Studio optional):

cd ~/apps/freeflow-button/mac
bash install.sh

That builds the Swift helper, generates the shared secret, registers a launchd user agent, and starts the listener.

iOS side: Open ios/FreeFlowButton.xcodeproj in Xcode after running xcodegen. Sideload to the iPhone with a free Apple ID. Build expires every 7 days; re-sideload from Xcode when it does.

Test the listener with curl before touching iOS:

curl -X POST http://localhost:8765/click -H "Authorization: Bearer $(cat mac/secret.txt)"

Known Gaps / Quirks

• The Right Option keycode (61) is a magic number. If FreeFlow’s hotkey ever changes upstream, update both the Swift helper and the README.
• Free Apple ID sideload means the iOS app expires weekly. Long-term fix would be a paid developer account or TestFlight.
• mDNS hostnames are hardcoded in ios/Sources/Config.swift. If you add a third Mac, edit that file.
• Re-run mac/install.sh on each Mac you want to use as a target so they all share the same secret.