cursor-voice-hooks

Voice announcements for Cursor agent actions. Hear what the AI is doing as it edits files, runs commands, and completes tasks.

Quick Start

bunx cursor-voice-hooks init
export OPENAI_API_KEY=sk-...

That's it. Open Cursor and start coding.

Requirements

• Bun
• OpenAI API key

What You'll Hear

| Event | Announcement | |-------|--------------| | File edit | "Edited config.ts: added validation logic" | | Shell command | "Running npm install" | | MCP tool | "Queried the database for users" | | Agent thought | Brief summary of reasoning | | Task complete | Summary of what the agent did |

Configuration

Edit .cursor/voice-config.json to customize:

{
  "tts_model": "gpt-4o-mini-tts",
  "tts_voice": "alloy",
  "tts_speed": 1.5
}

| Option | Description | |--------|-------------| | tts_model | TTS model (gpt-4o-mini-tts, tts-1, tts-1-hd) | | tts_voice | Voice (alloy, echo, fable, onyx, nova, shimmer) | | tts_speed | Speed multiplier (0.25 - 4.0) | | tldr_model | Model for generating summaries | | stop_hook_summary_enabled | Speak summary when agent finishes |

Cursor agent CLI vs IDE

| Hook | IDE | Agent CLI | |------|-----|-----------| | afterShellExecution | ✓ | ✓ | | beforeShellExecution | ✓ | ✓ (we allow; no handler) | | afterAgentResponse, afterAgentThought, afterFileEdit, afterMCPExecution, stop | ✓ | ✗ |

The Cursor agent CLI (e.g. cursor-agent, or the env this agent runs in) only fires beforeShellExecution and afterShellExecution. The IDE fires all hooks.

We await and process the queue for afterShellExecution so that when the CLI runs a command, you hear "Running X" immediately. Other after-hooks use fire-and-forget; only the stop hook speaks the final summary in the IDE.

Audit

Verify hooks work (simulates Cursor stdin → stdout, no TTS required):

bun run audit

Runs each hook type with sample JSON and checks exit code 0 + valid JSON output.

Troubleshooting

No audio? Check OPENAI_API_KEY is set and .cursor/errors.log for details.

License

MIT