superwhisper

name	superwhisper
description	Create, configure, and manage custom commands and modes for the superwhisper AI dictation app on macOS. Use when the user wants to create custom superwhisper modes, configure dictation workflows, set up URL schemes, write AppleScript/shell automations, manage voice and language models, configure context awareness, set up auto-activation rules, or customize any aspect of superwhisper.

Superwhisper Custom Command & Mode Builder

This skill helps you create custom commands, modes, and automations for superwhisper, the AI-powered dictation app for macOS.

Quick Start

To create a new custom mode for superwhisper:

1. Create a JSON mode file in ~/Documents/superwhisper/modes/
2. Configure the mode with AI instructions, context settings, and voice model
3. Optionally set up deep links and automations to trigger the mode

Overview of Superwhisper

Superwhisper is an AI-powered dictation tool that converts speech into polished written content. It offers:

• Multiple built-in modes: Voice, Message, Email, Note, Super, Meeting, and Custom
• Context awareness: Application context, selected text, and clipboard content
• Deep link URL schemes: superwhisper:// protocol for automation
• Local and cloud models: Voice models (transcription) and language models (AI processing)
• File transcription: Process audio/video files (MP3, MP4, WAV)
• Speaker separation: Multi-speaker identification in meetings
• Custom vocabulary and replacements: Improve recognition accuracy

Instructions

Step 1: Understand the User's Goal

Ask the user what they want to accomplish:

• New custom mode: A mode with specific AI instructions (e.g., "translate my speech to Spanish", "format as markdown", "summarize what I said")
• Automation workflow: Trigger superwhisper actions from scripts or Apple Shortcuts
• Mode configuration: Adjust voice models, language models, context settings, or auto-activation rules
• Vocabulary setup: Add custom words or text replacements
• File transcription workflow: Set up batch processing or specific transcription pipelines

Step 2: Create Custom Modes

Custom modes are the primary way to extend superwhisper. Each mode is a JSON file stored in ~/Documents/superwhisper/modes/.

CRITICAL: After creating the mode JSON file, you MUST add its key to the modeKeys array in ~/Documents/superwhisper/settings/settings.json.

CRITICAL: Mode files MUST use Apple-style JSON formatting (JSONSerialization style) with spaces before colons. Standard Python json.dump format will silently fail to load. Use re.sub(r'": ', '" : ', raw) after json.dumps(indent=2) and replace empty arrays [] with multi-line format:

import json, re, uuid

def to_apple_json(data):
    raw = json.dumps(data, indent=2, ensure_ascii=False)
    raw = re.sub(r'": ', '" : ', raw)
    def replace_empty_array(m):
        return f'{m.group(1)}"{m.group(2)}" : [\n\n{m.group(1)}]'
    raw = re.sub(r'^(\s*)"([^"]+)" : \[\]', replace_empty_array, raw, flags=re.MULTILINE)
    return raw

CRITICAL: All promptExamples IDs must be UUID format (e.g., str(uuid.uuid4()).upper() → "0B3329A1-09B2-4E31-BA43-3BB6FBA3DAB8").

Mode Configuration Fields

When creating a custom mode, configure these key aspects:

AI Instructions (the core of the custom mode):

• Write clear, specific instructions for how the AI should process the transcribed text
• Use XML tags for better structure with advanced AI models: <role>, <instructions>, <requirements>, <context>, <style>, <output-format>
• Add 2-3 input/output examples to significantly improve AI understanding
• Keep instructions focused on ONE specific task

Context Awareness Toggles:

• Application Context: Reads active window data, app name, input field text. Also includes system date/time, user name, computer name
• Selected Text: Captures highlighted text when recording starts (requires focus on source app)
• Clipboard Context: Captures text copied within 3 seconds before or during dictation

Voice Model Selection (for transcription):

• S1-Voice (Cloud): Multi-language, translation, speed 10, accuracy 9 (Pro)
• Ultra (Cloud): Multi-language, translation, speed 9, accuracy 9 (Pro)
• Parakeet (Local): English only, lightning-fast for short dictations
• Ultra Turbo v3 (Local): Balanced speed/quality, privacy-preserving
• Nova (Cloud): Best for longer recordings and speaker separation

Language Model Selection (for AI processing):

• S1-Language (Cloud): Superwhisper's own model, speed 10, benchmark ~80 (Pro)
• Claude 4.5 Sonnet: Benchmark 89, speed 8 (via Anthropic)
• Claude 3.5 Sonnet: Benchmark 82, speed 9 (via Anthropic)
• GPT-5: Benchmark 91, speed 7 (via OpenAI)
• GPT-4.1: Benchmark 87, speed 8 (via OpenAI)
• Groq Llama 3 8b: Fastest (speed 10), benchmark 67

Example: Custom Mode AI Instructions

Here is a template for writing effective custom mode instructions:

<role>
You are a [specific role description].
</role>

<instructions>
Process the user's dictated text as follows:
1. [First processing step]
2. [Second processing step]
3. [Third processing step]
</instructions>

<requirements>
- [Specific requirement 1]
- [Specific requirement 2]
- [Specific formatting rule]
</requirements>

<context>
Use the following context if available:
- Application Context: {application_context}
- Selected Text: {selected_text}
- Clipboard Context: {clipboard_context}
</context>

<output-format>
[Describe exact output format]
</output-format>

Content Reference Variables in Instructions

Use these names to reference content in your AI instructions:

• User Message: The dictated text input
• Application Context: Active window data (app name, input field text, system info)
• Selected Text: Highlighted content when dictation started
• Clipboard Context: Recently copied text

Step 3: Set Up Deep Links and Automations

Superwhisper supports URL schemes for automation:

Available URL Schemes

URL Scheme	Description
superwhisper://mode?key=YOUR_MODE_KEY	Switch to a specific mode
superwhisper://record	Start recording
superwhisper://settings	Open settings window

Finding a Mode's Key

1. Navigate to ~/Documents/superwhisper/modes/
2. Open/Quick Look the mode's JSON file
3. Find the "key" value in the JSON

Shell Command Examples

# Switch mode and start recording
open "superwhisper://mode?key=YOUR_MODE_KEY"
sleep 0.5
open "superwhisper://record"

# Open settings
open "superwhisper://settings"

# Transcribe a file from command line
open /path/to/audiofile.mp3 -a superwhisper

Apple Shortcuts Integration

Create an Apple Shortcut that:

1. Opens superwhisper://mode?key=YOUR_MODE_KEY to switch modes
2. Waits briefly
3. Opens superwhisper://record to start recording

This combines mode switching and recording in one action.

Step 4: Configure Auto-Activation Rules

Modes can automatically activate based on the currently active application or website:

• Configure auto-activation in each mode's settings
• The mode switches automatically when the specified app/website is in focus
• Once activated, the mode cannot be manually overridden
• The system won't auto-revert to a previous mode when leaving the app

Step 5: Set Up Vocabulary and Replacements

Custom Vocabulary Words (sent with audio to help transcription):

• Add specialized terminology, acronyms, company names, person names
• Use sparingly - too many words can confuse the AI transcription model
• Stored in ~/Documents/superwhisper/settings/

Text Replacements (applied after transcription, no AI involved):

• Case-insensitive matching ("todo", "TODO", "Todo" all match)
• Outputs your specified capitalization
• Multiple input variations can map to one replacement
• Great for correcting recurring transcription errors

Step 6: Configure Audio Settings

Microphone: Select preferred input or use automatic selection Volume: Automatic adjustment recommended for clear recordings Silence Removal: Skips quiet parts, prevents AI hallucinations during silence Sound Effects: Customizable recording start/completion audio cues System Audio Capture: Enable for meetings (records what you hear) Speaker Separation: Enable "Identify Speakers" for multi-speaker transcription (Nova Cloud model recommended)

Step 7: Set Up File Transcription

Superwhisper can transcribe external audio/video files:

Supported formats: MP3, MP4, mono WAV (16 kHz)

Methods:

1. Menu Bar > Transcribe File > Browse for file
2. Finder: Right-click > Open With > Superwhisper
3. Command line: open /path/to/file.mp3 -a superwhisper

The active mode's AI and voice settings are applied to the transcription.

Common Custom Mode Recipes

Translation Mode

<role>You are a professional translator.</role>
<instructions>
Translate the user's dictated text to [TARGET_LANGUAGE].
Preserve the original tone and meaning.
Output only the translated text.
</instructions>

Code Dictation Mode

<role>You are a code transcription assistant.</role>
<instructions>
Convert the user's spoken description into clean code.
Use the programming language visible in the application context.
Format with proper indentation and syntax.
</instructions>
<requirements>
- Use Application Context to detect the IDE and language
- Output only code, no explanations
- Follow the code style visible in the selected text
</requirements>

Enable: Application Context, Selected Text

Meeting Summary Mode

<role>You are a meeting notes assistant.</role>
<instructions>
Organize the transcribed meeting content into:
1. Key Discussion Points
2. Decisions Made
3. Action Items (with assignees if mentioned)
4. Follow-up Topics
</instructions>

Email Reply Mode

<role>You are an email composition assistant.</role>
<instructions>
Using the selected text (the email being replied to) as context,
compose a professional reply based on the user's dictated response.
Match the formality level of the original email.
Add appropriate greeting and closing.
</instructions>

Enable: Selected Text, Application Context

Markdown Formatter Mode

<role>You are a markdown formatting assistant.</role>
<instructions>
Format the user's dictated text as clean Markdown:
- Use headings for topic changes
- Create bullet lists for enumerated items
- Add code blocks for technical content
- Use bold/italic for emphasis where appropriate
</instructions>

Clipboard Transformer Mode

<role>You are a text transformation assistant.</role>
<instructions>
Apply the user's spoken instruction to the clipboard content.
For example: "make this more formal", "summarize this", "fix the grammar"
The clipboard context contains the text to transform.
The user message contains the instruction.
</instructions>

Enable: Clipboard Context

Built-in Modes Reference

Mode	Purpose	AI Processing	Context Aware
Voice	Speed-optimized transcription	None	No
Message	Polished messages with grammar fixes	Yes	No
Email	Structured email composition	Yes	No
Note	Organized notes with bullet points	Yes	No
Super	Context-aware smart dictation	Yes	Yes (all 3)
Meeting	Meeting summaries with action items	Yes	No
Custom	User-defined workflow	Configurable	Configurable

Keyboard Shortcuts

Action	Description
Toggle Recording	Start/stop recording (supports single modifier keys like Fn, Cmd)
Cancel Recording	Cancel current recording (<30s instant, >30s confirms)
Change Mode	Hold modifier + tap key to cycle through modes
Push-to-Talk	Hold to record, release to stop (can share Toggle shortcut)
Mouse Button	Quick click = toggle, hold = push-to-talk

File Paths Reference

Path	Contents
~/Documents/superwhisper/	Main configuration directory
~/Documents/superwhisper/modes/	Mode JSON files (find mode keys here)
~/Documents/superwhisper/recordings/	Dictation history and audio files
~/Documents/superwhisper/settings/	Vocabulary and text replacements
~/Documents/superwhisper/models/	Custom model configurations

Best Practices

1. One mode, one purpose: Keep custom modes focused on a single task
2. Use XML tags: Structure AI instructions with <role>, <instructions>, <requirements> tags for clarity
3. Add examples: Include 2-3 input/output examples in your AI instructions
4. Be selective with context: Only enable context types you actually need
5. Test incrementally: Start with simple instructions, then refine based on History tab results
6. Use the History tab: Review the "Prompt" section in the right sidebar to see exactly what was sent to the AI
7. Choose appropriate models: Use Claude or GPT models for complex processing; use Groq for speed
8. Backup your modes: The modes directory can be synced across devices with FileSync enabled
9. Avoid blank instructions: Custom modes with empty AI instructions produce unexpected results
10. Use replacements for consistency: Text replacements are deterministic and faster than AI corrections

Troubleshooting

• Mode not appearing in app: Ensure the mode's key is in the modeKeys array of settings.json, the JSON file uses Apple-style formatting ("key" : value with spaces before colons), and promptExamples IDs are UUID format. Quit and relaunch superwhisper after changes.
• Mode not working: Check History tab > Prompt section to see what instructions were sent
• Context not captured: Verify accessibility permissions in System Preferences
• Selected text missing: Ensure focus stays on source app when starting recording
• Clipboard not captured: Copy within 3 seconds before or during dictation
• Slow performance: Try switching to a cloud model, or close resource-heavy apps for local models
• Hallucinations in silence: Enable "Remove Silence" in sound settings
• Deep links not working: Ensure superwhisper is running and mode key is correct