Typing repetitive messages, switching between languages, or formatting code blocks by hand wastes developer time. Voice input promises speed, but generic dictation tools fail at technical vocabulary, mixed-language conversations, and context-specific formatting. hehehai/voxt addresses this with a macOS-native approach: hold a key to speak, release to paste, with AI transcription that adapts rules based on which app or website you're using.
What is hehehai/voxt?
hehehai/voxt is an open-source macOS menu bar application for voice input and translation, maintained by hehehai and distributed under the Apache 2.0 license. Built primarily in Swift and requiring macOS 15.0+, it occupies a specific niche: developer-focused voice tooling that goes beyond basic dictation to include real-time transcription enhancement, translation, and prompt-driven text rewriting.
The project has accumulated 688 GitHub stars and 51 forks as of its last commit on July 16, 2026. Its architecture separates Automatic Speech Recognition (ASR) from Large Language Model (LLM) processing, allowing independent provider selection for transcription versus enhancement, translation, and rewrite operations. This modular design matters for developers who may prefer local models for privacy-sensitive work or remote APIs for speed.
Voxt's distinguishing feature is App Branch (currently in beta): context-aware rule switching that detects the foreground application or browser URL and applies different prompts and enhancement rules automatically. For developers who work across IDEs, documentation, chat applications, and email, this eliminates manual prompt switching.
Key Features
Three-Mode Shortcut System. Voxt operates through modifier-key combinations with two trigger styles: tap-to-toggle or hold-to-record. The default fn combo provides: fn for standard transcription, fn+shift for transcribe-then-translate, and fn+control for voice-driven prompts or rewriting selected text. Each mode can be remapped or switched to a command combo preset.
Dual ASR Engine Support. For speech-to-text, Voxt supports both local and remote providers. Local options include MLX Audio (with models like Qwen3-ASR, Voxtral Realtime Mini, and Cohere Transcribe) and Whisper via WhisperKit (tiny through large-v3). Remote ASR providers include OpenAI Transcribe, Doubao ASR, GLM ASR, and Aliyun Bailian ASR—with WebSocket realtime support where implemented.
Independent LLM Selection. Enhancement, translation, and rewrite flows use separately configurable LLM providers: Anthropic Claude, Google Gemini, OpenAI GPT, DeepSeek, Ollama, oMLX, and ten others. This separation lets you optimize for latency (fast transcription) versus quality (careful rewriting) without compromise.
App Branch Context Switching. When enabled, Voxt detects the active application or browser URL and applies group-specific prompts. Coding in Xcode? Bias toward technical terminology. Writing in Gmail? Apply formal tone rules. The system supports Safari, Chrome, Edge, Brave, Arc, and custom browsers through automation permissions.
Personal Dictionary with Auto-Correction. Users can define terminology that gets injected into prompts and optionally auto-correct high-confidence near-matches before output. A one-click ingest feature scans recent history to propose candidate terms.
Local-First Privacy Option. With macOS 15.0+, all transcription and enhancement can run on-device through MLX Audio, WhisperKit, or local LLM servers via Ollama/oMLX—no audio leaves the machine.
Use Cases
Multilingual Development Documentation. Developers working with Chinese-English mixed environments can use fn+shift for immediate translation after transcription. Doubao ASR and Qwen3-ASR models specifically target mixed Chinese/English usage, while separate translation model selection lets you route through high-quality providers for final output.
IDE Voice Coding Assistance. With App Branch configured for Xcode or Cursor, spoken instructions like "extract this into a helper function" become structured code through the fn+control prompt mode. The app-specific prompt biases technical vocabulary and formatting conventions automatically.
Cross-Platform Communication. Teams using WeChat, Slack, or email across languages can set default translation targets per shortcut. Selected-text translation bypasses the microphone entirely—highlight foreign text, hit fn+shift, and receive translated replacement.
Accessibility and Repetitive Strain Relief. For developers with typing limitations or those recovering from injury, Voxt's hold-to-speak interaction reduces physical keyboard load while maintaining code-quality output through enhancement pipelines.
Offline Field Work. With local MLX Audio and Whisper models downloaded, transcription functions without network connectivity—relevant for security-conscious environments or travel without reliable internet.
Installation & Setup
Voxt distributes through GitHub Releases and Homebrew. The Homebrew method:
# Add the custom tap
brew tap hehehai/tap
# Install the application
brew install --cask voxt
For manual installation, download the latest release from https://github.com/hehehai/voxt/releases/latest.
Required Permissions:
| Permission | Requirement | Purpose |
|---|---|---|
| Microphone | Required | All recording and transcription flows |
| Accessibility | Strongly recommended | Global hotkeys and auto-paste into other apps |
| Input Monitoring | Strongly recommended | Reliable fn-based modifier shortcuts |
| Speech Recognition | Optional | Only for Apple Direct Dictation fallback |
| Automation | Optional | Browser URL reading for App Branch matching |
Post-Installation Configuration:
- Launch Voxt from Applications or menu bar
- Open the main window via tray menu → Dashboard
- Navigate to Model page to configure ASR and LLM providers
- For local models: select storage path, download preferred ASR and LLM models
- For remote providers: enter API keys in respective provider sections
- Enable App Enhancement (Beta) in General → Output if using App Branch
- Test shortcuts and verify permissions in the Permissions tab
Developer Build Notes:
Shared signing configuration lives in Config/Signing.shared.xcconfig. For local development:
# Copy the example local config
cp Config/Signing.local.xcconfig.example Config/Signing.local.xcconfig
# Edit to set your development team if needed
# VoxtTests reads from the same config; CI runs with CODE_SIGNING_ALLOWED=NO
Real Code Examples
The README provides configuration guidance rather than extensive code samples. Below are documented patterns reproduced directly from the source material.
Remote Provider Setup Prompt Pattern:
The project suggests using AI assistants to navigate configuration by providing specific documentation URLs:
https://raw.githubusercontent.com/hehehai/voxt/refs/heads/main/README.md
https://raw.githubusercontent.com/hehehai/voxt/refs/heads/main/docs/RemoteModel.md
How do I get started configuring remote ASR and LLM? I want to use Doubao ASR and Alibaba Cloud Bailian LLM. Please give me the full application and configuration workflow.
1. For every step that requires visiting a website, include the exact URL.
2. Point out the important notes and required configuration items.
3. Make the key steps more detailed.
This pattern demonstrates Voxt's documentation-first approach: rather than maintaining per-provider tutorials, the project structures reference docs for AI-assisted configuration.
Base64 Provisioning Profile Encoding (Release Builds):
# Encode Developer ID provisioning profile for GitHub Actions secret
base64 -i Voxt_Developer_ID.provisionprofile | tr -d '\n'
# Paste output into DEVELOPER_ID_PROVISIONING_PROFILE secret
The release workflow verifies App ID (com.voxt.Voxt), Keychain access group, expiration, and final signed entitlements before packaging—stability requirements for Data Protection Keychain credential persistence across updates.
Custom OpenAI-Compatible Endpoint Configuration:
# MOSI Studio example
Endpoint: https://studio.mosi.cn/api/v1/audio/transcriptions
Model: moss-transcribe or moss-transcribe-diarize
# Groq example
Endpoint: https://api.groq.com/openai/v1/audio/transcriptions
Model: whisper-large-v3-turbo or whisper-large-v3
Note that Voxt sends file uploads and reads transcript text from responses; structured metadata like diarization segments is not yet surfaced in the UI.
The README does not contain additional code examples beyond configuration patterns and command-line utilities. This reflects the project's current documentation scope rather than a limitation in functionality.
Advanced Usage & Best Practices
Model Storage Migration. When changing the local model storage path, previously downloaded models are not migrated automatically. Move files manually or re-download. Legacy installs using the old default cache location receive automatic migration during upgrade.
Shortcut Conflict Resolution. The fn key serves as universal stop in tap mode across all three shortcut types. Voxt ignores rapid repeated taps immediately after recording starts to prevent accidental cancellation. If fn conflicts with system functions, switch to the command Combo preset or fully custom bindings.
Proxy Configuration for Corporate Networks. Voxt supports HTTP, HTTPS, and SOCKS5 proxies with host, port, username, and password fields. Note: username/password are stored but not yet automatically injected into all request paths—a current limitation for complex authenticated proxy setups.
Voice End Command for Hands-Free Operation. Enable spoken stop commands ("over", "end", "完毕", "好了", or custom) to end recording without keyboard interaction. Voxt detects the command in transcript tail and auto-terminates after approximately one second of following silence.
Logging for Debugging. Hotkey debug logs and LLM debug logs are available in General → Logging. Enable temporarily to diagnose shortcut misfires or unexpected model outputs. Default state should remain off for performance.
Comparison with Alternatives
| Feature | hehehai/voxt | Apple Dictation | Whisper Desktop Apps |
|---|---|---|---|
| Context-aware prompts (App Branch) | ✅ Yes | ❌ No | ❌ No |
| Local + remote ASR flexibility | ✅ Both | ❌ Local only | ⚠️ Varies |
| Independent translation LLM | ✅ Yes | ❌ No | ❌ No |
| Open-source / self-hostable | ✅ Yes | ❌ No | ⚠️ Varies |
| macOS menu bar native | ✅ Yes | ✅ Yes | ⚠️ Varies |
| Realtime transcription preview | ✅ Yes | ✅ Yes | ⚠️ Varies |
Apple Dictation requires zero setup but offers no customization, limited multilingual support, and no translation pipeline. Standalone Whisper applications provide local transcription but typically lack the integrated enhancement/translation/rewrite flow and context switching that Voxt implements. Voxt's trade-off is configuration complexity: meaningful use requires provider setup, permission grants, and potentially model downloads versus Dictation's instant availability.
FAQ
What macOS version is required? macOS 15.0 or later. Local MLX Audio models specifically require this version.
Is Voxt free? Yes, Apache 2.0 licensed. Remote provider usage incurs their respective API costs.
Can I use Voxt without internet? Yes, with local MLX Audio or WhisperKit ASR and local LLM models downloaded.
Why doesn't auto-paste work? Grant Accessibility permission. Without it, results stay in clipboard for manual paste.
What's the difference between MLX Audio and Whisper? Separate engines with separate model catalogs. Whisper is not a sub-mode of MLX Audio.
How do I migrate settings to another Mac? Export General, Model, Dictionary, and other settings to JSON in the Configuration section, then import on the new machine. Sensitive fields export as placeholders.
Does Voxt support Apple Silicon? Yes. Local model performance benefits significantly from Apple Silicon Macs, especially for larger Whisper and LLM models.
Conclusion
hehehai/voxt targets developers and technical users who need more than basic dictation: context-aware transcription that adapts to your current application, configurable local or remote AI pipelines, and voice-driven text transformation. The 688-star project shows active maintenance with recent commits and a thoughtful architecture separating ASR from LLM concerns.
It's best suited for: multilingual developers, those seeking privacy-preserving local options, and users frustrated with one-size-fits-all dictation that garbles technical terminology. The configuration overhead is real—expect to spend time on permissions, model selection, and provider setup—but the payoff is precise, automated voice workflow integration.
Ready to try it? Download the latest release or install via Homebrew at https://github.com/hehehai/voxt.
