// Give your agent a voice. Send text to a Mac running VoxClaw and hear it spoken aloud with OpenAI neural voices or Apple TTS.
| name | voxclaw |
| description | Give your agent a voice. Send text to a Mac running VoxClaw and hear it spoken aloud with OpenAI neural voices or Apple TTS. |
| homepage | https://github.com/malpern/VoxClaw |
| metadata | {"clawdbot":{"emoji":"🦀","requires":{"bins":["curl"]}}} |
VoxClaw is a macOS app that speaks text aloud. It runs on the user's Mac as a menu bar app and listens for text over HTTP. Send text from any machine on the LAN and VoxClaw reads it using OpenAI neural voices or Apple's built-in TTS.
This is useful when your agent runs on a remote server or headless machine and you want voice output on the user's local Mac.
By default, agents should speak a short final summary after non-trivial work completes. Live progress narration should remain opt-in.
VoxClaw runs an HTTP listener (default port 4140) on the user's Mac. To speak text, POST to the /read endpoint. The user hears the text immediately through their Mac speakers with a teleprompter overlay showing synchronized word highlighting.
If the human shares a 🦞 VoxClaw setup pointer, use it directly. It includes:
https://voxclaw.com/)SKILL.md)Speak URL (/read)Health URL (/status)Agent Notify URL (/agent-notify)Prefer those provided URLs over guessed hostnames when both are available.
Never auto-switch to .local hostnames. Use numeric LAN IP URLs unless a human explicitly provides a .local target.
If health_url, speak_url, or agent_notify_url are present in the pointer, do not ask for LAN IP or run discovery first; call health_url immediately, then use the provided URLs.
Reliable connect order:
curl -sS http://localhost:4140/statuscurl -sS http://<lan-ip>:4140/status<lan-ip>:4140/read<lan-ip>:4140/agent-notifycurl -X POST http://<mac-ip>:4140/read \
-H 'Content-Type: application/json' \
-d '{"text": "Hello from your agent!"}'
Parameters (JSON body):
| Field | Type | Required | Description |
|---|---|---|---|
text | string | yes | The text to speak (max 50,000 characters) |
voice | string | no | OpenAI voice name: alloy, echo, fable, onyx, nova, shimmer |
rate | number | no | Speech rate multiplier (e.g. 1.5 for faster) |
instructions | string | no | Natural language speaking style (e.g. "Read warmly", "Sound excited"). Only works with OpenAI voices. |
Plain text also works:
curl -X POST http://<mac-ip>:4140/read -d 'Hello from your agent!'
Response:
{"status": "reading"}
Use agent notifications for task summaries, failures, and optional live progress updates.
curl -X POST http://<mac-ip>:4140/agent-notify \
-H 'Content-Type: application/json' \
-d '{"kind":"summary","text":"Task complete. I updated the parser and the focused tests passed."}'
Parameters (JSON body):
| Field | Type | Required | Description |
|---|---|---|---|
kind | string | yes | summary, progress, or failure |
text | string | yes | Spoken text |
source | string | no | Agent/source label |
voice | string | no | OpenAI voice override |
rate | number | no | Speech rate multiplier |
instructions | string | no | Natural-language speaking style |
Expected response:
{"status":"reading"}
or
{"status":"suppressed"}
curl http://<mac-ip>:4140/status
Response:
{
"status": "ok",
"service": "VoxClaw",
"reading": true,
"state": "playing",
"word_count": 42,
"website": "https://voxclaw.com/",
"skill_doc": "https://github.com/malpern/VoxClaw/blob/main/SKILL.md",
"discovery": "_voxclaw._tcp",
"speak_url": "http://192.168.1.50:4140/read",
"health_url": "http://192.168.1.50:4140/status",
"agent_notify_url": "http://192.168.1.50:4140/agent-notify",
"agent_speech_mode": "summary",
"agent_speech_verbosity": "brief"
}
States: idle, loading, playing, paused, finished.
agent_speech_mode controls what the app will actually speak:
off: speak nothingsummary: speak final summaries and failureslive: speak summaries, failures, and progress updatesThe user installs VoxClaw on their Mac:
voxclaw --listen)The listener binds to all interfaces on port 4140 by default. The port is configurable in Settings or via --port.
OpenAI API key is optional. Without a key, VoxClaw uses Apple's built-in voices. With a key, it uses OpenAI's neural voices (the user provides their own key during onboarding or in Settings).
VoxClaw advertises itself via Bonjour as _voxclaw._tcp on the local network. Agents can discover it without knowing the IP address.
| Status | Meaning |
|---|---|
| 200 | Text accepted, now reading |
| 200 | Agent notification accepted or suppressed |
| 400 | Missing or empty text, or text too long |
| 404 | Unknown endpoint (use POST /read, POST /agent-notify, or GET /status) |
| 413 | Request body too large (max 1 MB) |
Error responses are JSON: {"error": "description"}.
CORS: The HTTP API allows requests from http://localhost only. For cross-machine access, use curl or any HTTP client directly (CORS only applies to browsers).
Speak a summary after a task completes:
curl -X POST http://192.168.1.50:4140/agent-notify \
-H 'Content-Type: application/json' \
-d '{"kind":"summary","text":"Task complete. I deployed the new version and all tests passed."}'
Use a specific voice at faster speed:
curl -X POST http://192.168.1.50:4140/agent-notify \
-H 'Content-Type: application/json' \
-d '{"kind":"failure","text":"Heads up, the build failed on CI.","voice":"nova","rate":1.3}'
Control speaking style with instructions:
curl -X POST http://192.168.1.50:4140/read \
-H 'Content-Type: application/json' \
-d '{"text": "Welcome back! Your deploy succeeded.", "instructions": "Read warmly and conversationally"}'
Check if VoxClaw is available before sending:
curl -s http://192.168.1.50:4140/status | grep -q '"status":"ok"' && \
curl -X POST http://192.168.1.50:4140/agent-notify \
-H 'Content-Type: application/json' \
-d '{"kind":"summary","text":"Ready to go."}'
Speak a concise summary of failing tests or build errors with VoxClaw.
Give your agent a voice. Send text to a Mac running VoxClaw and hear it spoken aloud with OpenAI neural voices or Apple TTS.