# Claude Code Permissions Guide
Configure Claude Code to use VoiceMode without constant permission prompts.
## Quick Setup (30 seconds)
Add this to `~/.claude/settings.json`:
```json
{
"permissions": {
"allow": [
"mcp__voicemode__converse",
"mcp__voicemode__service"
]
}
}
```
That's it! Voice conversations and service management now work without prompts.
## What These Permissions Allow
| Permission | What It Does |
|------------|--------------|
| `mcp__voicemode__converse` | Voice conversations (speak and listen) |
| `mcp__voicemode__service` | Start/stop Whisper and Kokoro services |
## Permission Levels
Choose the level that fits your needs:
### Level 1: Voice Only
Just voice conversations, nothing else:
```json
{
"permissions": {
"allow": [
"mcp__voicemode__converse"
]
}
}
```
### Level 2: Voice + Service (Recommended)
Voice conversations plus service management:
```json
{
"permissions": {
"allow": [
"mcp__voicemode__converse",
"mcp__voicemode__service"
]
}
}
```
### Level 3: All VoiceMode Tools
Everything except installation (for power users):
```json
{
"permissions": {
"allow": [
"mcp__voicemode__*"
],
"deny": [
"mcp__voicemode__whisper_install",
"mcp__voicemode__whisper_uninstall",
"mcp__voicemode__kokoro_install",
"mcp__voicemode__kokoro_uninstall"
]
}
}
```
## How to Apply Permissions
### Option 1: Edit Settings File
1. Open `~/.claude/settings.json` in your editor
2. Add the permissions block
3. Save and restart Claude Code
```bash
# Create or edit the file
nano ~/.claude/settings.json
```
### Option 2: Use Claude Code UI
1. In Claude Code, type `/permissions`
2. Add `mcp__voicemode__converse` to the allow list
3. Add `mcp__voicemode__service` to the allow list
### Option 3: Command Line
```bash
# Create settings file with VoiceMode permissions
mkdir -p ~/.claude
cat > ~/.claude/settings.json << 'EOF'
{
"permissions": {
"allow": [
"mcp__voicemode__converse",
"mcp__voicemode__service"
]
}
}
EOF
```
## Troubleshooting
### Still Getting Permission Prompts?
1. **Check file location**: Settings must be in `~/.claude/settings.json`
2. **Check JSON syntax**: Use a JSON validator if unsure
3. **Restart Claude Code**: Changes require restart to take effect
4. **Check tool names**: Must match exactly (case-sensitive)
### Verify Your Settings
```bash
cat ~/.claude/settings.json
```
Should show your permissions block.
### Common Mistakes
❌ Wrong:
```json
{
"allowedTools": ["mcp__voicemode__converse"]
}
```
✅ Correct:
```json
{
"permissions": {
"allow": ["mcp__voicemode__converse"]
}
}
```
## Removing Permissions
To go back to prompting for everything:
```json
{
"permissions": {
"allow": []
}
}
```
Or delete the permissions block entirely.
## Security Notes
### What VoiceMode Tools Can Do
| Tool | Capabilities |
|------|--------------|
| `converse` | Records audio from microphone, plays audio through speakers |
| `service` | Starts/stops background processes for Whisper and Kokoro |
### What Requires Manual Approval
These tools always prompt (not included in recommendations):
- `whisper_install` / `whisper_uninstall` - Downloads and compiles software
- `kokoro_install` / `kokoro_uninstall` - Downloads and installs Python packages
- `whisper_model_install` - Downloads large model files (100MB-3GB)
### Privacy
- Audio is processed locally by Whisper (speech-to-text)
- No audio is sent to external servers unless you configure OpenAI as a provider
- See [Privacy documentation](../reference/privacy.md) for details
## Project vs Global Settings
| File | Scope | Use Case |
|------|-------|----------|
| `~/.claude/settings.json` | All projects | Personal defaults |
| `.claude/settings.json` | This project | Team settings (commit to git) |
| `.claude/settings.local.json` | This project | Personal overrides (gitignored) |
Settings merge: global → project → local (local wins).
## See Also
- [Getting Started](../tutorials/getting-started.md) - Installation guide
- [Configuration](configuration.md) - VoiceMode settings
- [Troubleshooting](../reference/troubleshooting.md) - Common issues
