Claude Code Permissions Guide

Claude Code Permissions Guide

Configure Claude Code to use VoiceMode without constant permission prompts.

Quick Setup (30 seconds)

Add this to ~/.claude/settings.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 Levels

Choose the level that fits your needs:

Level 1: Voice Only

Just voice conversations, nothing else:

{
  "permissions": {
    "allow": [
      "mcp__voicemode__converse"
    ]
  }
}

Level 2: Voice + Service (Recommended)

Voice conversations plus service management:

{
  "permissions": {
    "allow": [
      "mcp__voicemode__converse",
      "mcp__voicemode__service"
    ]
  }
}

Level 3: All VoiceMode Tools

Everything except installation (for power users):

{
  "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

# 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

# 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

cat ~/.claude/settings.json

Should show your permissions block.

Common Mistakes

❌ Wrong:

{
  "allowedTools": ["mcp__voicemode__converse"]
}

✅ Correct:

{
  "permissions": {
    "allow": ["mcp__voicemode__converse"]
  }
}

Removing Permissions

To go back to prompting for everything:

{
  "permissions": {
    "allow": []
  }
}

Or delete the permissions block entirely.

Security Notes

What VoiceMode Tools Can Do

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 for details

Project vs Global Settings

Settings merge: global → project → local (local wins).

See Also

• Getting Started - Installation guide
• Configuration - VoiceMode settings
• Troubleshooting - Common issues