🗣️ 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

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

Default Configuration

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

Voice Commands in Claude Code

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

/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

Available Hooks

| 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

Smart Summaries

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

Session Lifecycle Hooks

• 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)

Smart Notification Types

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"

Context Management

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

Startup Grace Period

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

Examples

# Setup (or re-run to update/change settings)
npx claude-code-voice

# Uninstall
npx claude-code-voice uninstall

Platform Support

macOS

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

Windows

• Uses PowerShell speech synthesis
• Windows system sounds

Linux

• 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

Voice not working?

1. Check if voice is enabled:

   /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

Too many/few announcements?

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

SubagentStop firing at startup?

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

v2.2.0

• 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

v2.0.0

• 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)

v1.0.6

• Initial release with basic hooks

Author

Created by mrrxwyz

License

MIT License - see LICENSE file for details.