mbailey · ai-cora · Dec 28, 2025
diff --git a/docs/guides/claude-code-plugin.md b/docs/guides/claude-code-plugin.md
@@ -0,0 +1,175 @@
+# Claude Code Plugin
+
+VoiceMode provides an official plugin for Claude Code that enables voice conversations directly within the CLI.
+
+## What the Plugin Provides
+
+The VoiceMode plugin includes:
+
+- **MCP Server** - Full voice capabilities via the `voicemode-mcp` server
+- **Slash Commands** - Quick access to common operations
+- **Skill File** - Documentation and usage patterns for Claude
+- **Hooks** - Sound feedback during tool execution
+
+## Installation
+
+### From the Plugin Marketplace
+
+The plugin is published to the Claude Code plugin marketplace:
+
+```bash
+# Add from marketplace
+/plugin marketplace add mbailey/voicemode
+
+# Install the plugin
+/plugin install voicemode
+```
+
+### From Local Development
+
+If you're developing or have VoiceMode cloned locally:
+
+```bash
+# Add plugin from local path
+/plugin marketplace add /path/to/voicemode/plugins/voicemode
+
+# Install the plugin
+/plugin install voicemode
+```
+
+## Prerequisites
+
+The plugin requires VoiceMode services to be installed and running. After installing the plugin, use the install command:
+
+```bash
+/voicemode:install
+```
+
+This runs the VoiceMode installer which sets up:
+
+- **Whisper.cpp** - Local speech-to-text
+- **Kokoro** - Local text-to-speech
+- **FFmpeg** - Audio processing (via Homebrew on macOS)
+
+Alternatively, install services manually:
+
+```bash
+# Run the installer directly
+curl -sL https://voicemode.ai/install.sh | bash
+
+# Or install individual services
+voicemode whisper service install
+voicemode kokoro install
+```
+
+## Slash Commands
+
+| Command | Description |
+|---------|-------------|
+| `/voicemode:install` | Install VoiceMode and dependencies |
+| `/voicemode:converse` | Start a voice conversation |
+| `/voicemode:status` | Check service status |
+| `/voicemode:start` | Start voice services |
+| `/voicemode:stop` | Stop voice services |
+
+### Starting a Conversation
+
+```bash
+# Start with a greeting
+/voicemode:converse Hello, how can I help you today?
+
+# Just start listening
+/voicemode:converse
+```
+
+### Checking Status
+
+```bash
+/voicemode:status
+```
+
+Shows whether Whisper (STT) and Kokoro (TTS) services are running and healthy.
+
+## MCP Tools
+
+Once installed, Claude has access to these MCP tools:
+
+- `mcp__voicemode__converse` - Speak and listen for responses
+- `mcp__voicemode__service` - Manage voice services
+
+### Converse Tool Parameters
+
+| Parameter | Default | Description |
+|-----------|---------|-------------|
+| `message` | (required) | Text for Claude to speak |
+| `wait_for_response` | true | Listen for user response after speaking |
+| `listen_duration_max` | 120 | Maximum recording time (seconds) |
+| `voice` | auto | TTS voice name |
+| `vad_aggressiveness` | 2 | Voice detection strictness (0-3) |
+
+## Hooks and Soundfonts
+
+The plugin includes a hook receiver that plays sounds during tool execution:
+
+- Sounds play when tools start and complete
+- Provides audio feedback during long operations
+- Uses configurable soundfonts
+
+Hooks are automatically configured when the plugin is installed.
+
+## Troubleshooting
+
+### Services Not Starting
+
+Check individual service status:
+
+```bash
+voicemode whisper service status
+voicemode kokoro service status
+```
+
+View logs:
+
+```bash
+voicemode whisper service logs
+voicemode kokoro service logs
+```
+
+### No Audio Output
+
+1. Ensure your system audio is working
+2. Check that Kokoro service is running
+3. Verify FFmpeg is installed: `which ffmpeg`
+
+### Speech Not Recognized
+
+1. Ensure Whisper service is running
+2. Check microphone permissions for Terminal/Claude Code
+3. Try speaking more clearly or adjusting VAD aggressiveness
+
+## Configuration
+
+VoiceMode respects configuration from `~/.voicemode/voicemode.env`:
+
+```bash
+# Default TTS voice
+VOICEMODE_TTS_VOICE=nova
+
+# Whisper model (base, small, medium, large)
+VOICEMODE_WHISPER_MODEL=base
+
+# Override thread count for Whisper
+VOICEMODE_WHISPER_THREADS=4
+```
+
+Edit configuration:
+
+```bash
+voicemode config edit
+```
+
+## Resources
+
+- [VoiceMode Documentation](https://voicemode.ai/docs)
+- [GitHub Repository](https://github.com/mbailey/voicemode)
+- [Plugin Source](https://github.com/mbailey/voicemode/tree/master/plugins/voicemode)
diff --git a/plugins/voicemode/commands/converse.md b/plugins/voicemode/commands/converse.md
@@ -5,19 +5,10 @@ argument-hint: [message]
 
 # /voicemode:converse
 
-Start an ongoing voice conversation with the user using the `mcp__voicemode__converse` tool.
+Start an ongoing voice conversation with the user using the `voicemode:converse` MCP tool.
 
-## Example
+## Implementation
 
-```json
-{
-  "message": "Hello! What would you like to work on?",
-  "wait_for_response": true
-}
-```
+Use the `voicemode:converse` tool with the user's message. All parameters have sensible defaults.
 
-All other parameters have sensible defaults - just set the message.
-
-## Troubleshooting
-
-If voice services aren't working, load the `voicemode` skill for troubleshooting guidance and installation instructions.
+If the tool call fails or you need more information about voice capabilities, load the `voicemode` skill for complete documentation.
diff --git a/plugins/voicemode/commands/install.md b/plugins/voicemode/commands/install.md
@@ -9,54 +9,10 @@ Install VoiceMode and its dependencies.
 
 ## Implementation
 
-### Step 1: Install VoiceMode Package
+Load the VoiceMode skill and follow the installation instructions in the "Install Services if Needed" section.
 
-Run the installer with `--yes` flag (required for non-interactive environments like Claude Code):
-
-```bash
-uvx voice-mode-install --yes
-```
-
-This installs the VoiceMode package and CLI. It does NOT install local speech services.
-
-### Step 2: Install Local Speech Services (Optional)
-
-After the VoiceMode package is installed, optionally install local STT and TTS services.
-
-**IMPORTANT**: These commands do NOT support a `--yes` flag - they are already non-interactive.
-
-Install Whisper for local speech-to-text:
-```bash
-voicemode whisper service install
-```
-
-Install Kokoro for local text-to-speech:
-```bash
-voicemode kokoro install
-```
-
-Both installations can take several minutes as they download models.
-
-### Step 3: Verify Installation
-
-After installation completes:
-
-1. Check service status:
-   ```bash
-   voicemode whisper service status
-   voicemode kokoro service status
-   ```
-
-2. Start services if needed:
-   ```bash
-   voicemode whisper service start
-   voicemode kokoro service start
-   ```
-
-## Notes
-
-- The `voice-mode-install` script requires `--yes` flag in non-interactive mode
-- The `voicemode whisper/kokoro install` commands are already non-interactive
-- Local services require ~2-3GB disk space for models
-- Installation requires network access for downloads
-- Services will be configured to start automatically on login
+The skill contains complete guidance for:
+- Installing the VoiceMode package
+- Detecting Apple Silicon for local service recommendations
+- Installing Whisper (STT) and Kokoro (TTS) with download size estimates
+- Verifying installation and troubleshooting