Voice announcements for Cursor agent actions
npm install cursor-voice-hooksVoice announcements for Cursor agent actions. Hear what the AI is doing as it edits files, runs commands, and completes tasks.
``bash`
bunx cursor-voice-hooks init
export OPENAI_API_KEY=sk-...
That's it. Open Cursor and start coding.
- Bun
- OpenAI API key
| 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 |
Edit .cursor/voice-config.json to customize:
`json`
{
"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 |
| 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.
Verify hooks work (simulates Cursor stdin → stdout, no TTS required):
`bash`
bun run audit
Runs each hook type with sample JSON and checks exit code 0 + valid JSON output.
No audio? Check OPENAI_API_KEY is set and .cursor/errors.log` for details.
MIT