Workflows

How Workflows Work#

When you start dictating, TypeWhisper matches the current browser URL first, then the active app, against your enabled workflows. Matching workflows can override language, task, engine, translation mode, prompts, and related behavior automatically. Hotkey workflows can also process the current selection or clipboard directly without recording audio. The active workflow name is shown as a badge in the indicator together with why it matched.

Set up an Email Reply workflow step by step

Quick Start with the Workflow Palette#

The Workflow Palette runs a workflow on text you have selected or copied, without a recording. It lists your workflows with the Manual trigger.

1. Create a workflow with the Manual trigger under Settings > Workflows. For a first test, pick the Custom Workflow template and enter the instruction from the example below.
2. Assign a Palette shortcut under Settings > Hotkeys > Workflow Palette.
3. Select or copy text in any app and press the shortcut.
4. Choose the workflow. TypeWhisper processes the text and inserts the result.

Tomorrow call Anna at 10, send revised pricing, and book a follow-up for Friday.

Turn the text into a short bullet list. Keep only the actionable points.

- Call Anna at 10 tomorrow
- Send revised pricing
- Book a follow-up for Friday

Nothing changes? The FAQ lists what to check.

Trigger Types#

• Website

  Website workflows work across browsers. Use one or more domains; a workflow for github.com also matches subdomains like gist.github.com.

• App

  App workflows activate as soon as one of the selected apps is active. Use one or more apps for tools like Mail, Slack, Terminal, or browsers when a website condition is not needed.

• Hotkey

  Hotkey workflows run when you press their assigned shortcut. They can start dictation or process selected text and do not compete with automatic app or website matching.

• Manual

  Manual workflows are available from the Workflow Palette. They run only when you choose them directly.

• Always fallback

  An Always workflow becomes the global fallback. It only applies when no more specific workflow matches.

Priority#

TypeWhisper resolves automatic workflow matches in this order:

1. Website match
2. App match
3. Always fallback workflow

Manual and hotkey workflows are direct actions. They run from the Workflow Palette or their assigned shortcut instead of being selected by app or URL matching.

Creating a Workflow#

Go to Settings > Workflows and click "New Workflow". Pick a template, choose one trigger type, then configure the fields for that trigger and the behavior you want:

• Apps

  Limit the workflow to one or more selected apps

• Websites

  Match browser tabs by one or more domains or subdomain patterns

• Language

  Keep auto-detect, pin one language, or restrict recognition to likely languages

• Task

  Transcribe or Translate where the selected engine supports it

• Translation mode

  For Translation workflows, choose Apple Translate on-device on macOS 15+ or LLM Prompt mode.

• Engine

  WhisperKit, Parakeet TDT, Apple SpeechAnalyzer (macOS 26+), or any add-on engine

• Prompt

  Workflow-specific LLM prompt instructions for automatic post-processing

• Prompt Provider

  Inherit the ordered global LLM fallback list, or select one provider for a strict single-provider call

• Effort

  Shown next to the provider and model when the provider reports effort levels for that model. Provider Default uses the effort set for the provider

• Hotkey

  Assign one or more shortcuts to run this workflow on demand, either by starting dictation or by processing the current selection/clipboard directly

• Press Enter after inserting

  Choose when TypeWhisper presses Enter after inserting the text: never, always, when you press Enter during dictation, or when the dictation ends with “press enter” or “press return”

• Inline Commands

  For Dictation Only workflows: detects a spoken instruction such as “write this as a friendly email”, removes it from the text, and applies it to the dictation

• Priority

  Break ties between workflows in the same automatic match tier

Before you save, Try It Out runs a sample dictation through the workflow with the current settings. Click "Insert Example" or type your own text, then click "Run Test". Nothing is saved or inserted. The test uses the language model of the workflow, so you can check the result before the workflow runs for real. Try It Out is available from TypeWhisper 1.8.1.

Hotkey Workflows#

You can assign one or more shortcuts to a workflow and choose what those shortcuts do. Start Dictation uses the normal recording path with that workflow's settings. Process Selected Text skips recording, reads the current accessibility selection, falls back to Cmd+C and then the clipboard when needed, and inserts the processed result through the same path as the Workflow Palette.

Translate selected text step by step

Language and engine hotkeys#

Create one Dictation Only workflow for each language and engine combination you want to trigger directly.

1. Add a Dictation Only workflow for English, set Spoken Language to English, choose WhisperKit plus the model you want, and assign a Start Dictation hotkey.
2. Add a second Dictation Only workflow for Norwegian, set Spoken Language to Norwegian, choose the local Whisper engine plus its model, and assign a different Start Dictation hotkey.
3. Leave Transcription Engine on Use Global Engine when the workflow should follow the default engine under Settings > Dictation instead.
4. Use Process Selected Text hotkeys for selection-based cleanup or prompts; they do not record audio and therefore do not need a transcription engine or model.

This keeps the global engine unchanged while each dictation hotkey can still force its own language, engine, and model.

Prompt Instructions#

A prompt is the instruction of a workflow. The workflow sends the transcribed or selected text together with its instruction to the LLM provider and inserts the processed result.

Templates such as Cleaned Text, Email Reply, or Checklist bring their instruction with them. With the Custom Workflow template you write the instruction yourself in the Behavior step.

LLM Prompt workflows can attach prompt instructions to a specific context. Leave the provider on the global setting to inherit the ordered LLM fallback list, or select one provider when this workflow must make a strict single-provider call.

Global LLM fallback list#

At the top of Settings > Workflows, add providers with an optional model and drag them into the order TypeWhisper should try. Inherited prompts and LLM workflows move to the next entry when a provider is unavailable, cannot restore, is rate-limited, hits a network or API error, or returns no text.

A workflow with an explicitly selected provider does not use the list. It makes one strict call to that provider. If every inherited fallback fails, TypeWhisper shows a combined error and does not insert replacement text.

This list is separate from the Always workflow trigger: Always chooses which workflow runs when no more specific workflow matches, while the LLM fallback list chooses the provider attempt order inside inherited prompt processing.

When a provider reports effort levels, each fallback entry and each workflow with an explicit provider also show an Effort picker, for example for the Claude plugin and for the Codex, Claude Code, and Antigravity CLI providers. It lists the levels of the selected model. Provider Default uses the effort set on the provider's page and names it, for example Provider Default (Medium).

Multiple Engines#

Dictation Only workflows can override the transcription engine and model used for that hotkey. TypeWhisper can keep multiple engines loaded in memory during a session for instant switching. Set Auto-unload model to Never if you want previously loaded local models restored at launch; any active auto-unload policy keeps startup lazy and reloads the selected/downloaded model on first real use. Configure this in Settings > Advanced.

App-aware Formatting#

App-aware formatting is a lightweight formatting pass, not a semantic or AI-based app detection feature. The global toggle under Settings > Dictation > Output Formatting only enables this pass. You only see a visible effect when the matched workflow also sets an Output Format.

When dictation finishes, TypeWhisper passes the matched workflow's output format into the post-processing pipeline. If app-aware formatting is enabled, that formatting step runs before workflow text processing, snippets, and dictionary corrections.

• None

  Disable additional formatting for this workflow.

• Auto-Detect

  Choose a format from a fixed app bundle ID mapping. Known Markdown apps include Obsidian, Notion, Typora, Bear, and Ulysses. Known HTML apps include Apple Mail and Outlook. Known code apps include Xcode, VS Code, Cursor, Zed, Terminal, and iTerm. Unknown apps fall back to plain text.

• Markdown

  Normalize list-like lines such as - item, * item, or dictated bullet item into Markdown list items.

• HTML

  Wrap paragraphs in <p> tags, convert bullet-like lines into <ul>/<li>, and escape HTML characters.

• Plain Text

  Currently leaves the text unchanged.

• Code

  Currently leaves the text unchanged.

Formatting examples#

Input:
bullet first item
* second item

Output:
- first item
- second item

Input:
hello <team>
- launch

Output:
<p>hello &lt;team&gt;</p>
<ul>
<li>launch</li>
</ul>

Input:
for item in items:
    print(item)

Output:
for item in items:
    print(item)

Input:
bullet first item

Output:
bullet first item

Current limitations#

• Auto-Detect only uses known app bundle IDs.
• Unknown apps fall back to plain text.
• The formatter does not inspect the meaning of the text.
• Code and Plain Text are currently pass-through modes.
• Later prompt or LLM steps can still change the formatted result.

Example Setups#

• Mail

  App: Mail, Language: German, Engine: WhisperKit, Model: Large v3

• github.com

  Website: github.com, Language: English, Prompt: concise technical cleanup

• Translation workflow

  Trigger: Manual or Always, Translation mode: Apple Translate, Target language: English

• Language hotkeys

  Two Dictation Only workflows: English hotkey with WhisperKit, Norwegian hotkey with local Whisper, each with its own language and model

• Global fallback

  No app or website, Language: Auto, Engine: Parakeet TDT v3

FAQ#

• Why does TypeWhisper just type my prompt text?

  Because instructions are configuration, not voice triggers. If you say the instruction out loud, TypeWhisper transcribes exactly what you said. Set the instruction in a workflow, then dictate the content you want transformed. If you want to speak the instruction, turn on Inline Commands in a Dictation Only workflow.

• Why does my workflow seem to do nothing?

  Usually one of three things is missing: the workflow is not enabled, its trigger does not match the current app or website, or neither the inherited global LLM fallback list nor the workflow's explicit provider has a ready provider.

• Do templates and custom workflows work differently?

  No. Both are applied after transcription and before insertion. Templates ship with their purpose built in, while a Custom Workflow depends on the instruction and provider you set.

• When should a workflow run automatically?

  Use an app, website, hotkey, or Always trigger when one context should always get the same processing. That is useful for turning Mail dictation into polished emails or formatting meeting notes in a single tool.

• Can workflows trigger actions or plugins instead of plain text output?

  Yes. A workflow can send its result to an action plugin as its Action Target instead of inserting text. That is how workflows like Linear issue creation or Obsidian note capture are wired up.

• Do I need placeholders in my instruction?

  No. TypeWhisper passes the instruction and the text separately to the LLM provider. In practice, write the transformation you want, such as "Rewrite this as a polite email" or "Turn this into bullet points."