SuperAPI AI Directory
Partner中文AI newsFavorites
Skillssales-handy

sales-handy

Marketing & growth

View repository

Updated 10-16 05:46

About this skill

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
  1. 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.