Documentation
Contents
Install
Download the DMG, double-click to mount, drag Vagudukai.app to your Applications folder. Launch from Spotlight or Launchpad. The app is signed and notarized by Apple, so Gatekeeper accepts it without ceremony.
Requirements: macOS 14 or later, Apple Silicon (M1 / M2 / M3 / M4).
First launch & permissions
On the first launch, vagudukAI walks you through three macOS permissions. All three are required for the core dictation flow:
- Microphone — capture your voice while you hold the hotkey.
- Accessibility — paste your transcript into the focused app via a synthetic ⌘V.
- Input Monitoring — detect when you hold the hotkey globally, regardless of which app is focused.
If you skip onboarding or deny a permission, you can re-grant it later from Settings → Permissions.
Pick your dictation hotkey
Open Settings → Shortcuts. The default is Right ⌘. Other choices include the function key, hyper key, or any modifier-only combination that doesn't collide with your existing shortcuts. Hold it for as long as you want to dictate; release to stop.
A small HUD in the lower right corner shows the input level while you talk. If it stays flat, your mic isn't capturing — jump to Troubleshooting.
Local vs cloud transcription
vagudukAI ships with two transcription backends. You can switch between them at any time in Settings → Transcription.
Local (Parakeet)
NVIDIA's Parakeet TDT v3 model, ~600 MB, runs on the Apple Neural Engine. Click Download in the Transcription tab to fetch it once; after that, every transcription happens on your Mac. No network, no API cost, no key. Best for privacy-first workflows.
Cloud (OpenAI / Groq)
Bring your own API key. Audio is sent to OpenAI's whisper-1 or Groq's whisper-large-v3-turbo and transcribed in the cloud. Typically faster than local on the first cold call, and may handle accents or noisy inputs more gracefully.
Setting up your API key (cloud)
Open Settings → Transcription, pick Cloud, then select your provider:
- OpenAI — create a key at platform.openai.com/api-keys. Paste it into the API key field. It auto-saves after 20+ characters.
- Groq — create a key at console.groq.com/keys. Same field, same behaviour.
Keys are stored in your macOS Keychain. They never leave your Mac except as the Authorization header on requests to your chosen provider. We don't see them, log them, or proxy them.
Click Test to send a one-second silent clip and verify the endpoint + key without spending real audio.
Snippets
A snippet maps a spoken trigger phrase to an expansion. Say the trigger, the expansion gets pasted instead. Manage them in Settings → Snippets.
Matching rules:
- Case-insensitive. "my email" matches "My Email", "MY EMAIL", etc.
- Whole-word boundaries. "cat" matches "cat" but not "category".
- Longer triggers win when they overlap. "my work email" claims its span before "my email".
- A trailing period after a trigger at the end of a sentence is eaten so you don't paste "alice@example.com." with a stray dot.
The Import from Contacts button reads your My Card in Contacts.app and pre-fills snippets like "my email", "my phone", "my address".
Secure snippets
Toggle the lock icon on any snippet to mark it secure. The expansion is moved to Keychain. The non-secure field clears. When the trigger is spoken, vagudukAI shows a small confirmation toast with a hint (e.g. "card ending 1234") — press Enter to paste, Escape to skip. The value is never displayed and never logged.
Useful for credit card numbers, building codes, multi-factor backup codes, anything you don't want sitting in plaintext in your settings.
AI cleanup
Optionally route every transcript through an LLM before it pastes. The LLM removes filler words ("um", "you know"), fixes punctuation, and tightens phrasing without changing meaning.
Toggle in Settings → Transcription → AI Cleanup. Uses the same API key as your cloud STT. Models:
- OpenAI:
gpt-4o-mini - Groq:
llama-3.1-8b-instant
Adds 300–800 ms of latency. If the LLM call fails (network blip, API rate limit), the raw transcript pastes instead — you never lose the dictation.
Selection rewrite
When AI Cleanup is on and you have text highlighted anywhere on screen, holding the hotkey switches to rewrite mode. Speak an instruction:
- "make this more formal"
- "translate to Spanish"
- "rewrite this as bullet points"
- "fix the grammar"
vagudukAI grabs the selection (via ⌘C), sends it to the LLM with your instruction, and pastes the result back over the original. Works in any app that supports standard copy / paste.
If you turn AI Cleanup off, the hotkey reverts to literal dictation that replaces the selection.
Vocabulary biasing
Settings → Vocabulary lets you add proper nouns, product names, acronyms, and jargon. These are packed into the prompt hint sent with each cloud transcription so Whisper recognizes them correctly.
Cap is roughly 200 characters total. Local Parakeet doesn't currently expose biasing — this only helps cloud mode.
Transcribe an audio file
Right-click the menu bar icon → File…. Drop in any audio file (WAV, MP3, M4A, etc). vagudukAI runs it through your current backend and shows the result in a window with copy / paste / save buttons. Useful for meeting recordings, voice memos, podcasts.
Troubleshooting
Recording produces empty / silent transcripts
Your default input device may be a Bluetooth mic that's returning zero samples. Open Settings → General → Input device and pick the built-in mic explicitly. AirPods / AirPods Max occasionally fail HFP negotiation silently — the built-in mic is the most reliable fallback.
Permission dialogs don't appear
If you denied a permission once, macOS won't ask again. Open System Settings → Privacy & Security, find the relevant section (Microphone / Accessibility / Input Monitoring), toggle vagudukAI on, then relaunch.
Hotkey doesn't fire
Make sure Input Monitoring is granted. If another app also uses Right Command (e.g. some keyboard remappers), pick a different hotkey in Settings.
The app crashed
Open Settings → About → Generate Diagnostics Report. This creates a folder on your Desktop with system info, the last 24 hours of logs, and any crash reports. Email it to admin@yondertech.net.
Support
Bug reports, feature requests, refunds, or just a hello: admin@yondertech.net.