# macOS push-to-talk

Ask your local AI agent: **“Get Olenji and use my chosen shortcut to write what I say into the focused field. Don’t send it.”**

The agent prepares an installed speech model, configures the shortcut with explicit `--delivery insert` or MCP `output: "insert"`, and checks the returned status. Microphone recording and model setup remain separate from shortcut registration. Use a supported standard CPython installation; no Apple source build is required for portable Faster Whisper dictation.

## Permission and first use

Allow the app or executable **macOS identifies** in System Settings → Privacy & Security:

- **Microphone** for recording.
- **Input Monitoring** for the global shortcut.
- **Accessibility** for insertion into another app.

macOS can attribute a command and its helper to the launching app or terminal. Do not assume the entry is always named Olenji, Python, Codex or Terminal. A failed preflight does not automatically display an approval prompt. After granting access, re-enable the binding and check its actual status. Olenji does not grant permissions itself, reset TCC or require Full Disk Access.

Focus an ordinary editable field and clear any selection. Hold the shortcut, speak and release. The transcript stays in Olenji. Supported-field delivery inserts once and never presses Enter or sends the message.

## Short recovery instructions

- **Secure keyboard entry:** leave the password/secure-input state and enable the binding again. Olenji never disables secure input.
- **Keyboard layout changed:** reconfigure the chosen shortcut. A stale physical key is not reused silently.
- **Unsupported field:** read or copy the saved transcript yourself, or use a supported ordinary field. Chrome/Electron accessibility-tree support depends on that application; OS name alone does not establish it.
- **Interrupted or uncertain delivery:** inspect the field and saved transcript before repeating. Interrupted listener holds skip insertion; a write that may already have happened is never replayed automatically.

## Implementation and evidence

The native helper uses Apple’s public `NSWorkspace.frontmostApplication` to identify the app receiving keyboard events and refreshes the documented cached lifecycle state before rechecking its retained identity. It creates that app’s Accessibility reference directly. It uses Apple’s selected-text accessibility setter only when the actual ordinary field explicitly permits that setter. A reported disabled state is refused. Native text areas such as TextEdit may lack a separate enabled attribute: only the attribute-unsupported result is accepted there, while positive setter writability remains mandatory. This does not treat missing metadata as an enabled-state observation; no-value, malformed, denied and failed responses still stop delivery. It validates typed empty UTF-16 ranges, secure subroles, focused application/element identity and their PIDs, then confirms the newly inserted span and caret. It reads no surrounding draft, uses no clipboard and never replaces the whole field value. Cross-process accessibility has no atomic compare-and-insert transaction, so uncertain results remain explicit.

The shortcut listener is listen-only, filters one chosen chord and sends only action edges to Olenji. It bounds callback buffering and timeout recovery, rejects stale edges, and checks Input Monitoring and global secure-input state. Default output remains a saved transcript; insertion requires the user's explicit request.

[Apple foreground application](https://developer.apple.com/documentation/appkit/nsworkspace/frontmostapplication), [running-application lifetime](https://developer.apple.com/documentation/appkit/nsrunningapplication), [selected-text setter](https://developer.apple.com/documentation/appkit/nsaccessibilityprotocol/setaccessibilityselectedtext(_:)), [attribute writability](https://developer.apple.com/documentation/applicationservices/1459972-axuielementisattributesettable), [UTF-16 range queries](https://developer.apple.com/documentation/applicationservices/kaxstringforrangeparameterizedattribute), [microphone authorization](https://developer.apple.com/documentation/bundleresources/requesting-authorization-for-media-capture-on-macos) and [Input Monitoring](https://support.apple.com/en-ie/guide/mac-help/mchl4cedafb6/mac) are the primary contracts. The [native handoff](/docs/1.3.0/source/#source-122e0644ea856ce65c28) explains the automated owned TextEdit and shortcut-registration checks. Exact execution reports distinguish research, Ubuntu regressions, native Apple framework/field behavior and publication.