🗣️ Claude Code Voice


> Make Claude Code speak! ✨ Add personalized voice announcements to your AI coding assistant.

Features

- 🎤 Personalized Messages - Uses your name throughout all voice interactions
- 👋 Session Greetings - Time-based greetings when starting, resuming, or clearing sessions
- 👋 Session Farewells - Friendly goodbye messages when ending sessions
- 🔔 Smart Notifications - Different alerts for permissions, idle, auth, and MCP dialogs
- 📝 Smart Summaries - AI-generated summaries of what was accomplished (optional)
- 📦 Context Alerts - Warnings when context is being compacted
- 🔇 Startup Grace Period - No spurious alerts from internal agents during startup
- 🎛️ Granular Control - Mute/unmute specific hooks as needed
- 🌍 Cross-Platform - Works on macOS, Windows, and Linux
- ⚡ One-Command Setup - Install and configure everything in seconds

Installation

``bash
npx claude-code-voice
`

That's it! The interactive wizard will guide you through setup.

What Gets Installed

The setup wizard will:
1. Ask for your name for personalized messages
2. Let you choose which voice hooks to enable
3. Configure platform-specific voice engines
4. Create the /voice command in Claude Code

$3

By default, these hooks are enabled:
- ✅ SessionStart - Greetings on startup, resume, and clear
- ✅ SessionEnd - Farewell messages when exiting
- ✅ Notification - Smart alerts (permissions, idle, auth, MCP dialogs)
- ✅ Stop - When tasks are completed
- ✅ SubagentStop - When subagents finish (with startup grace period)
- ✅ PreCompact - Context compaction warnings

And these are disabled (to reduce noise):
- ❌ PreToolUse - Before each tool runs
- ❌ PostToolUse - After each tool completes

Usage

$3

Once installed, you can use these commands within Claude Code:

`bash
/voice # Toggle voice on/off
/voice status # Show current settings
/voice help # Show all commands

Smart Summaries (AI-generated task descriptions)

/voice smart on # Enable smart summaries
/voice smart off # Use generic messages (default)

Mute specific hooks

/voice mute session # Mute greetings/farewells
/voice mute notification # Mute permission/idle alerts
/voice mute compact # Mute compaction warnings
/voice mute all # Mute everything

Unmute specific hooks

/voice unmute session # Unmute greetings
/voice unmute all # Unmute everything
`

$3

| Hook | Aliases | Description |
|------|---------|-------------|
| session | greet, greeting | Session greetings & farewells |
| notification | notify | Permission, idle, auth, MCP alerts |
| stop | finish | Task completion messages |
| subagent | agent | Subagent completion alerts |
| compact | memory | Context compaction alerts |
| pre | pretool | Tool start announcements |
| post | posttool | Tool completion alerts |
| all | - | All hooks at once |

New in v2.2

$3

Instead of generic "Task completed!" messages, Claude can now summarize what was actually accomplished:

- Stop hook: "Updated the login form with validation" (max 15 words)
- SubagentStop hook: "Agent found 14 matching files" (max 8 words)

How it works:
1. When a task completes, the transcript is read
2. Claude Haiku generates a concise summary
3. Sound plays followed by the AI-generated message

Trade-offs:
- Adds ~1-2 second delay (AI call happens before sound)
- Uses Haiku API credits

Enable during setup or toggle anytime with /voice smart on|off.

New in v2.0

$3

- SessionStart with matchers:
- startup - Fresh session greeting (time-based: "Good morning!", "Good afternoon!", etc.)
- resume - Welcome back message when resuming
- clear - Fresh start message after /clear

- SessionEnd - Farewell message when exiting (time-based)

$3

Instead of one generic notification, you now get specific alerts for:
- permission_prompt - "May I proceed?"
- idle_prompt - "Still here when you're ready"
- auth_success - "Authentication successful!"
- elicitation_dialog - "I need some details"

$3

- PreCompact - Alerts when context is being compacted (manual or auto)

$3

SubagentStop now includes a 3-second grace period after session start to prevent spurious announcements from internal initialization agents.

Examples

`bash


Setup (or re-run to update/change settings)

npx claude-code-voice

Uninstall

npx claude-code-voice uninstall
`

Platform Support

$3

- Uses say command with Samantha voice
- System sounds from /System/Library/Sounds/

$3

- Uses PowerShell speech synthesis
- Windows system sounds

$3

- Uses espeak or festival for speech
- PulseAudio for sound playback

Customization

The voice system generates personalized messages like:
- "Good morning John! Ready to code?"
- "Welcome back Sarah! Picking up where we left off."
- "Hey Alex, may I proceed?"
- "Goodbye Michael! Have a great day!"

Messages vary randomly to keep interactions fresh and natural. Each message type has 5-10 variations.

Troubleshooting

$3

1. Check if voice is enabled:
`bash
/voice status
`

2. Make sure your system has text-to-speech:
- macOS: Built-in (no setup needed)
- Windows: Built-in (no setup needed)
- Linux: Install espeak or festival

3. Verify hook configuration in ~/.claude/settings.json

$3

Use /voice mute and /voice unmute to customize which events trigger voice feedback.

$3

This is fixed in v2.0 with the startup grace period. If you're upgrading, run npx claude-code-voice to update your scripts.

Changelog

$3


- Added smart summaries feature for Stop/SubagentStop hooks
- AI-generated task completion messages (optional, off by default)
- Added /voice smart on|off` command
- Added CLAUDE_CODE_REMOTE check to all scripts (headless safety)
- Session-specific lock files for multi-session support

$3

- Added SessionStart hook with startup/resume/clear matchers
- Added SessionEnd hook for farewells
- Added PreCompact hook for context compaction alerts
- Added typed Notification hooks (permission, idle, auth, elicitation)
- Added startup grace period to prevent spurious SubagentStop alerts
- Added SESSION and COMPACT mute options
- Increased message variety (5-10 variations per message type)
- Time-based greetings and farewells (morning/afternoon/evening/night)

$3

- Initial release with basic hooks

Author

Created by mrrxwyz

License

MIT License - see LICENSE file for details.