Skip to content
Back to search

voxclaw

MarketplaceWorks with Claude CodeGitHub

Give OpenClaw a voice — Let your agent speak from any Mac on your network

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/malpern--voxclaw/badge.svg)](/listings/malpern--voxclaw)

HTML

<a href="/listings/malpern--voxclaw"><img src="/api/listings/malpern--voxclaw/badge.svg" alt="findsafeskills safety rating" /></a>

Install

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Prerequisites

- macOS 26+ - OpenAI API key (optional) - ElevenLabs API key (optional)

The onboarding wizard walks you through setup on first launch. To store an API key manually:

security add-generic-password -a "openai" -s "openai-voice-api-key" -w "sk-..."

Or set the environment variable:

export OPENAI_API_KEY="sk-..."

Build & Install

swift build -c release
./Scripts/package_app.sh
./Scripts/install-cli.sh

iPhone App (iOS)

The repo includes an iPhone app target with a widget extension. Open `VoxClawIOS/VoxClawIOS.xcodeproj` in Xcode (26+) and run the `VoxClawIOS` scheme on iOS 26+. The app ships to internal testers via TestFlight (see `.github/workflows/ios-release.yml`, triggered by `ios-v*` tags).

It adds, on top of the shared listener + teleprompter:

- **Control Center control** + **home-screen widget** — "Read Clipboard" with one tap - **Siri / Spotlight / Shortcuts** — "Read Text Aloud" - **Live Activity** — a "Now reading" card on the lock screen / Dynamic Island - **iCloud relay receiver** — enable "Remote Relay" in iOS Settings (and "Relay to my devices over iCloud" on the Mac) so your Mac's agent speech plays here even when the app is closed or the phone is locked. Both devices must be signed into the same iCloud account with the toggle on.

The relay uses the user's **private** CloudKit database (`iCloud.com.malpern.voxclaw`); speech text never leaves your iCloud account.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 18 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. {
  2. "$schema": "https://raw.githubusercontent.com/anthropics/claude-code/refs/heads/main/marketplace/marketplace.schema.json",
  3. "name": "voxclaw",
  4. "version": "1.0.0",
  5. "owner": {
  6. "name": "Micah Alpern",
  7. "email": "malpern@gmail.com"
  8. },
  9. "plugins": [
  10. {
  11. "name": "voxclaw",
  12. "description": "Give your coding agent a voice. Speaks responses aloud through the VoxClaw macOS/iOS app with per-project voices, speech queue, and polite multi-device sync.",
  13. "source": "./plugins/voxclaw",
  14. "category": "development",
  15. "keywords": ["tts", "speech", "voice", "text-to-speech", "accessibility", "audio"]
  16. }
  17. ]
  18. }
README.md · README · 285 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # VoxClaw
  2. <p align="center">
  3. <a href="https://voxclaw.com/">
  4. <img src="docs/voxclaw-hero.png" alt="VoxClaw app icon — a crab claw holding a speaker" width="320">
  5. </a>
  6. </p>
  7. <p align="center">
  8. <a href="https://voxclaw.com/">
  9. <img src="https://img.shields.io/badge/Visit-Website-1f6feb?style=for-the-badge&logo=google-chrome&logoColor=white" alt="Visit Website">
  10. </a>
  11. <br/>
  12. <a href="https://github.com/malpern/VoxClaw/releases/latest/download/VoxClaw.zip">
  13. <img src="https://img.shields.io/badge/Download-Mac%20App-238636?style=for-the-badge&logo=apple&logoColor=white" alt="Download Mac App">
  14. </a>
  15. </p>
  16. **Give OpenClaw a voice.**
  17. [OpenClaw](https://github.com/openclaw/openclaw) is the open-source personal AI assistant that runs on your devices — your files, your shell, your messaging apps (WhatsApp, Telegram, Slack, Discord, and more). It lives where you work. **VoxClaw gives it a voice.**
  18. Run VoxClaw on your Mac and hear OpenClaw speak to you. When OpenClaw runs on another computer — a server, a headless box, or a different machine — send text to your Mac over the network and VoxClaw speaks it aloud with high-quality text-to-speech. Apple's built-in voices work out of the box; add your own OpenAI or ElevenLabs API key for neural voices when you want that extra polish. Paste text, pipe from the CLI, or stream from any device on your LAN — and listen.
  19. VoxClaw also includes an iPhone app in this repo (`VoxClawIOS/`) with the same core listener + teleprompter flow for iOS. With **iCloud relay** turned on, your Mac can even speak through your iPhone when it's locked, backgrounded, or on a different network — VoxClaw wakes it with a silent CloudKit push and reads the text aloud, with a "Now reading" Live Activity on the lock screen. The iOS app also adds a Control Center control, a home-screen widget, and a "Read Text Aloud" Siri/Shortcuts action.
  20. For Codex plugin installation and marketplace distribution, use the separate [malpern/codex-marketplace](https://github.com/malpern/codex-marketplace) repository. This repository is the main product repo for the app, website assets, releases, and source code.
  21. ---
  22. A macOS menu bar app + CLI tool that reads text aloud using Apple TTS (default), OpenAI TTS (BYOK), or ElevenLabs TTS (BYOK), with an optional teleprompter-style floating overlay and synchronized word highlighting.
  23. ## Screenshots
  24. ### Overlay panel
  25. ![VoxClaw overlay panel showing live highlighted text](docs/overlay-panel.png)
  26. ### Settings panel
  27. ![VoxClaw settings panel with voice controls and style presets](docs/settings-panel.png)
  28. ## Features
  29. - **Onboarding + Agent Handoff** — First-run setup configures voice, key, network mode, and launch at login, and can copy a `🦞 VoxClaw setup pointer` for your agent
  30. - **Teleprompter Overlay** — Floating overlay with word-by-word highlighting synced to speech; includes presets, deep appearance controls, and audio-only mode
  31. - **Three Voice Engines** — Apple (no setup), OpenAI (BYOK), or ElevenLabs (BYOK), with Apple fallback when cloud auth fails
  32. - **Automatic Updates** — In-app updates via Sparkle (notarized + EdDSA-signed); a "Check for Updates…" menu item too
  33. - **Multiple Input Methods** — Arguments, stdin pipe, file, clipboard, URL scheme, and LAN HTTP
  34. - **Network API for Agents** — `POST /read`, `POST /ack`, `POST /control`, `GET /status`, and `GET /claw`, with request validation and structured status payloads
  35. - **Multi-Agent Aware** — `project_id` + `agent_id` give each concurrent agent its own voice, and scope "stop reading" (`/ack`) so prompting one agent never cuts off another
  36. - **Cross-Device iCloud Relay** — Speak agent output on your iPhone/iPad even when it's locked, backgrounded, or off your LAN, via a silent CloudKit push that wakes the device (opt-in, same iCloud account on both ends)
  37. - **Bonjour Discovery** — Advertises `_voxclaw._tcp` on LAN for peer/device discovery
  38. - **Menu Bar App + CLI** — Lightweight menu bar controls plus full terminal control via `voxclaw`
  39. - **iPhone Companion App** — iOS app (`VoxClawIOS/`) on the shared core engine/settings stack, adding a Control Center control, a home-screen widget, a "Read Text Aloud" Siri/Shortcuts action, a "Now reading" Live Activity, and the iCloud relay receiver
  40. - **macOS Services Integration** — Read selected text from other apps via Services
  41. - **Keyboard Controls While Reading** — Space (pause/resume), Escape (stop), Arrow keys (skip ±3s)
  42. ## Installation
  43. ### Prerequisites
  44. - macOS 26+
  45. - OpenAI API key (optional)
  46. - ElevenLabs API key (optional)
  47. The onboarding wizard walks you through setup on first launch. To store an API key manually:
  48. ```bash
  49. security add-generic-password -a "openai" -s "openai-voice-api-key" -w "sk-..."
  50. ```
  51. Or set the environment variable:
  52. ```bash
  53. export OPENAI_API_KEY="sk-..."
  54. ```
  55. ### Build & Install
  56. ```bash
  57. swift build -c release
  58. ./Scripts/package_app.sh
  59. ./Scripts/install-cli.sh
  60. ```
  61. ### iPhone App (iOS)
  62. The repo includes an iPhone app target with a widget extension. Open
  63. `VoxClawIOS/VoxClawIOS.xcodeproj` in Xcode (26+) and run the `VoxClawIOS` scheme
  64. on iOS 26+. The app ships to internal testers via TestFlight (see
  65. `.github/workflows/ios-release.yml`, triggered by `ios-v*` tags).
  66. It adds, on top of the shared listener + teleprompter:
  67. - **Control Center control** + **home-screen widget** — "Read Clipboard" with one tap
  68. - **Siri / Spotlight / Shortcuts** — "Read Text Aloud"
  69. - **Live Activity** — a "Now reading" card on the lock screen / Dynamic Island
  70. - **iCloud relay receiver** — enable "Remote Relay" in iOS Settings (and "Relay
  71. to my devices over iCloud" on the Mac) so your Mac's agent speech plays here
  72. even when the app is closed or the phone is locked. Both devices must be
  73. signed into the same iCloud account with the toggle on.
  74. The relay uses the user's **private** CloudKit database
  75. (`iCloud.com.malpern.voxclaw`); speech text never leaves your iCloud account.
  76. ## Usage
  77. ### CLI
  78. ```bash
  79. voxclaw "Hello, this is a test." # direct text
  80. echo "Read this aloud" | voxclaw # piped stdin
  81. voxclaw --file ~/speech.txt # from file
  82. voxclaw --clipboard # from clipboard
  83. voxclaw --audio-only "No overlay" # audio only, no panel
  84. voxclaw --voice nova "Hello" # OpenAI voice override
  85. voxclaw --rate 1.5 "Hello" # 1.5x speech speed
  86. voxclaw --output hello.mp3 "Hello" # save audio to file (OpenAI)
  87. voxclaw --listen # network mode: listen for text from LAN
  88. voxclaw --send "Hello from CLI" # send text to a running listener
  89. voxclaw --status # check if listener is running
  90. voxclaw # launch menu bar app (no args)
  91. ```
  92. ### Network Mode
  93. Start VoxClaw in network listener mode on your Mac:
  94. ```bash
  95. voxclaw --listen # listens on port 4140
  96. voxclaw --listen --port 8080 # custom port
  97. ```
  98. Send text from another device on your local network:
  99. ```bash
  100. # JSON body
  101. curl -X POST http://your-mac-ip:4140/read \
  102. -H 'Content-Type: application/json' \
  103. -d '{"text": "Hello from my phone"}'
  104. # With voice and rate overrides
  105. curl -X POST http://your-mac-ip:4140/read \
  106. -H 'Content-Type: application/json' \
  107. -d '{"text": "Hello", "voice": "nova", "rate": 1.3}'
  108. # Force a specific engine for this read (apple | openai | elevenlabs).
  109. # ElevenLabs gives the tightest word-highlight sync.
  110. curl -X POST http://your-mac-ip:4140/read \
  111. -H 'Content-Type: application/json' \
  112. -d '{"text": "Hello", "engine": "elevenlabs"}'
  113. # Multi-agent: pass project_id + agent_id to get a distinct voice per agent
  114. # and so prompting one agent never cuts off another that is still speaking.
  115. curl -X POST http://your-mac-ip:4140/read \
  116. -H 'Content-Type: application/json' \
  117. -d '{"text": "Hello", "project_id": "/path/to/repo", "agent_id": "session-123"}'
  118. # Ack: stop reading just this agent's current response (scoped by project_id +
  119. # agent_id), e.g. when the user sends the agent a new prompt. Other agents keep speaking.
  120. curl -X POST http://your-mac-ip:4140/ack \
  121. -H 'Content-Type: application/json' \
  122. -d '{"project_id": "/path/to/repo", "agent_id": "session-123"}'
  123. # Plain text body
  124. curl -X POST http://your-mac-ip:4140/read -d 'Hello from my phone'
  125. # Health check (returns reading state, session state, word count)
  126. curl http://your-mac-ip:4140/status
  127. # Easter egg / connectivity check
  128. curl http://your-mac-ip:4140/claw
  129. ```
  130. Cross-machine tip: use the Mac's numeric LAN IP only (for example `http://192.168.1.50:4140`) unless a human explicitly tells your agent to use a specific `.local` hostname.
  131. If you want a one-paste handoff for your agent, open VoxClaw Settings and use `Copy Agent Setup` in the Network section. It copies a `🦞` setup pointer with website/docs plus your live local `/read` and `/status` URLs.
  132. Reliable bring-up order:
  133. 1. On the VoxClaw Mac: `curl -sS http://localhost:4140/status`
  134. 2. From the agent host, use numeric IP: `curl -sS http://<lan-ip>:4140/status`
  135. 3. Then send speech: `curl -sS -X POST http://<lan-ip>:4140/read -H 'Content-Type: application/json' -d '{"text":"hello"}'`
  136. 4. Do not auto-switch to `.local` hostnames unless the human explicitly provides one.
  137. ### URL Scheme & Integration
  138. ```bash
  139. # URL scheme — trigger from any app or script
  140. open "voxclaw://read?text=Hello%20world"
  141. # Open settings window
  142. open "voxclaw://settings"
  143. # Services menu — select text in any app, right-click > Services > Read with VoxClaw
  144. # Shortcuts / Siri
  145. shortcuts run "Read with VoxClaw"
  146. ```
  147. ### Menu Bar
  148. When launched without arguments, VoxClaw runs as a menu bar app with:
  149. - **Read Clipboard** (⌘⇧V) — Read text from clipboard
  150. - **Pause/Resume** — When actively reading
  151. - **Stop** — Cancel current reading
  152. - **Settings...** (⌘,) — Configure voice, overlay, controls, and network listener
  153. - **About VoxClaw**
  154. - **Quit** (⌘Q)
  155. ### Keyboard Controls (while reading)
  156. | Key | Action |
  157. |-----|--------|
  158. | Space | Pause / Resume |
  159. | Escape | Stop |
  160. | ← | Skip back 3 seconds |
  161. | → | Skip forward 3 seconds |
  162. ## Development
  163. ### Project Structure
  164. ```
  165. Sources/
  166. VoxClawCore/ Library target (all logic)
  167. VoxClaw/ Thin executable (entry point only)
  168. Tests/
  169. VoxClawCoreTests/ Unit + integration tests
  170. ```
  171. ### Running Tests
  172. ```bash
  173. swift test
  174. ```
  175. ### CI
  176. GitHub Actions runs on every push to `main` and on pull requests. See `.github/workflows/ci.yml`.
  177. ## Architecture
  178. Swift Package Manager with a library target (`VoxClawCore`) and thin executable (`VoxClaw`):
  179. ```
  180. Input (args/stdin/file/clipboard/url/network)
  181. → InputResolver resolves text
  182. → ReadingSession orchestrator
  183. → SpeechEngine (Apple | OpenAI | ElevenLabs, with fallback support)
  184. → AudioPlayer schedules AVAudioEngine buffers
  185. → Timing pipeline (cadence/proportional/aligned) maps playback position → word index
  186. → FloatingPanelView highlights current word (or audio-only mode)
  187. → Session ends / panel collapses
  188. ```
  189. **Tech Stack:**
  190. - Swift 6.4 with strict concurrency
  191. - SwiftUI + NSPanel for floating overlay
  192. - AVAudioEngine for low-latency audio playback
  193. - Apple AVSpeechSynthesizer + OpenAI TTS API (`gpt-4o-mini-tts`) + ElevenLabs TTS API
  194. - Multi-stage word timing (cadence, proportional, and aligned timestamps when available)
  195. - Swift Argument Parser for CLI
  196. - NWListener (Network.framework) for LAN text input
  197. - Bonjour service advertisement (`_voxclaw._tcp`) for discovery
  198. - CloudKit (private database, silent-push `CKDatabaseSubscription`) for the cross-device iCloud relay
  199. - WidgetKit + App Intents + ActivityKit on iOS (Control Center control, widget, Siri/Shortcuts, Live Activity)
  200. - Keychain Services for secure API key storage
  201. - Sparkle for notarized, EdDSA-signed in-app auto-updates
  202. ## For Agents
  203. If you're an AI agent and want to speak text aloud on the user's Mac, read [`SKILL.md`](SKILL.md). It has the full HTTP API, error codes, and examples. Quick version:
  204. ```bash
  205. curl -X POST http://<mac-ip>:4140/read -H 'Content-Type: application/json' \
  206. -d '{"text": "Hello from your agent", "voice": "nova", "rate": 1.0}'
  207. ```
  208. If the human pastes you a `🦞 VoxClaw setup pointer`, trust those URLs for that machine/session.
  209. ## License
  210. MIT

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.