sales-skills/sales-handy

Handy Platform Help

Step 1 — Gather context

If references/learnings.md exists, read it first for accumulated platform knowledge.

1. What do you need help with?

   • A) Installing Handy or first-time setup (macOS / Windows / Linux)
   • B) Choosing between Whisper and Parakeet STT models
   • C) Bluetooth headset latency or audio input issues
   • D) Push-to-talk shortcut configuration or conflicts
   • E) Voice Activity Detection (VAD) sensitivity tuning
   • F) Running Handy headless or via CLI flags
   • G) Comparing Handy to other dictation tools
   • H) Crashes or startup issues

2. Which platform are you on?

   • A) macOS (Intel or Apple Silicon)
   • B) Windows (x64)
   • C) Linux (x64)

Skip-ahead rule: if the user's prompt already contains enough context, skip to Step 2.

Step 2 — Route or answer directly

| Problem domain | Route to | |---|---| | Comparing Handy to meeting note-takers | /sales-note-taker {user's question} | | Reviewing a specific call for coaching feedback | /sales-call-review {user's question} | | Building a coaching program | /sales-coaching {user's question} | | General tool integration patterns (Zapier, webhooks, iPaaS) | /sales-integration {user's question} |

When routing, provide the exact command.

Step 3 — Handy platform reference

Read references/platform-guide.md for the full platform reference — STT models, installation, CLI flags, VAD configuration, known issues.

Answer the user's question using only the relevant section. Don't dump the full reference.

Step 4 — Actionable guidance

You no longer need the platform guide — focus on the user's specific situation.

First-time setup priority: Install via brew install --cask handy (macOS), winget install cjpais.Handy (Windows), or download from GitHub releases (Linux) → grant microphone permissions → press global shortcut (default: configurable) → speak → release → text pastes into active app.

Model selection: Parakeet V3 for CPU-only machines (fast, auto language detection). Whisper Turbo for GPU machines (best accuracy/speed balance). Whisper Large for maximum accuracy when speed is not critical.

Bluetooth fix: If using wireless headphones (AirPods, etc.), expect 1-2s delay on first activation. Switch to a wired mic or USB mic for latency-sensitive use.

If you discover a gotcha, workaround, or tip not covered in references/learnings.md, append it there.

Gotchas

Best-effort from research — review these, especially items about platform limitations and OS-specific issues that may be outdated.

• Bluetooth headsets cause 1-2 second transcription delay — the most reported issue. AirPods and other Bluetooth audio devices add latency before recording starts. Use a wired or USB microphone for instant response.
• No custom dictionary support — Whisper has no built-in vocabulary override. Company names, technical jargon, and proper nouns may be mis-transcribed. No workaround exists today (feature request).
• Whisper models crash on certain Windows/Linux configs — GPU-accelerated Whisper fails on some hardware. Fall back to Parakeet V3 (CPU-only) if Whisper crashes.
• Linux support has compositor issues — recording overlay is disabled by default on Linux. Wayland requires wtype or dotool for text pasting.
• No API, no integrations, no CRM — Handy is a local desktop app only. No webhooks, no Zapier, no CRM connectors. CLI flags (--toggle-transcription) are the only external control surface.
• No LLM post-processing — unlike Amical, Handy outputs raw STT text with no grammar correction or context-aware formatting. What Whisper/Parakeet outputs is what you get.

Related skills

• /sales-note-taker — Comparing Handy to meeting note-takers (Fathom, Fireflies, Avoma, Gong, etc.) or wiring transcript APIs into CRM/warehouse
• /sales-amical — Amical: MIT-licensed open-source AI dictation with context-aware LLM formatting (closest competitor)
• /sales-meetily — Meetily: MIT-licensed open-source meeting assistant with Whisper/Parakeet transcription
• /sales-char — Char: GPL-3.0 open-source bot-free AI meeting notepad with plugin SDK
• /sales-call-review — Review a specific call for coaching feedback and scoring
• /sales-coaching — Build coaching programs that consume call data
• /sales-integration — General CRM/tool integration patterns (Zapier, webhooks, iPaaS)
• /sales-do — Not sure which skill to use? The router matches any sales objective to the right skill. Install: npx skills add sales-skills/sales --skill sales-do

Examples

Example 1: Setting up offline dictation on macOS

User says: "I want free voice-to-text on my Mac that works completely offline — no cloud." Skill does:

1. Confirms Handy is free, open-source, and fully local — no internet required
2. Guides through brew install --cask handy and microphone permission grant
3. Recommends Parakeet V3 for CPU-only Macs or Whisper Turbo for Apple Silicon with GPU
4. Tests push-to-talk: press shortcut → speak → release → text pastes into active app
5. Notes there's no LLM formatting — if user wants grammar correction, suggests Amical as alternative Result: Working offline dictation with model recommendation.

Example 2: Bluetooth delay with AirPods

User says: "There's a 1-2 second delay before Handy starts transcribing when I use my AirPods." Skill does:

1. Confirms this is a known Bluetooth latency issue acknowledged by the developer
2. Explains Bluetooth audio switches to SCO codec for microphone input, adding latency
3. Recommends switching to a wired or USB microphone for instant response
4. If wireless is mandatory, suggests starting transcription slightly before speaking Result: Clear explanation and workaround for Bluetooth latency.

Example 3: Comparing Handy to Amical

User says: "Should I use Handy or Amical for daily dictation?" Skill does:

1. Compares: Handy (20k stars, Tauri/Rust, Whisper + Parakeet, cross-platform) vs Amical (1.2k stars, Electron, Whisper only, context-aware formatting)
2. Handy wins on: cross-platform (Linux support), STT engine choice (Parakeet V3 CPU option), larger community, lighter resource usage (Tauri vs Electron)
3. Amical wins on: LLM-powered context-aware formatting (Gmail vs Slack tone), grammar correction, custom vocabulary
4. Recommends Handy if raw speed and cross-platform matter; Amical if intelligent formatting matters Result: Clear decision framework based on priorities.

Troubleshooting

Bluetooth headset delay

Symptom: 1-2 second pause before transcription begins when using wireless headphones. Cause: Bluetooth audio switches to SCO (Synchronous Connection-Oriented) mode for microphone input, which adds latency as the codec negotiation happens. Solution: Use a wired microphone or USB headset. If Bluetooth is required, start the push-to-talk shortcut 1-2 seconds before speaking. The developer has acknowledged this as a known limitation.

Handy crashes on startup

Symptom: App crashes immediately or after selecting a Whisper model, especially on macOS Tahoe betas or certain Windows/Linux GPU configurations. Cause: GPU-accelerated Whisper model initialization fails on unsupported hardware or beta OS versions. Solution: Try Parakeet V3 (CPU-only, no GPU dependency). On macOS, check System Settings → Privacy & Security → "Open Anyway" if the app is blocked. On Windows, ensure WebView2 runtime is installed. Run with --debug flag to capture crash logs for GitHub issues.

Text not pasting into active application (Linux)

Symptom: Transcription completes but text doesn't appear in the target application. Cause: Linux Wayland compositors don't support the same text injection methods as X11. The recording overlay is disabled by default on Linux due to compositor focus issues. Solution: Install wtype (Wayland) or dotool for text pasting support. If using X11, text pasting should work out of the box. Check that Handy has the necessary input permissions.