Frequently Asked Questions

• 100% offline - No network requests, no telemetry, no analytics
• No cloud services - Everything runs locally on your Mac
• Open source - You can verify the code yourself

Ba Không (Three No’s) Commitment:

• 🚫 No fees - Free forever, no Pro version
• 🚫 No ads - No popups, no interruptions
• 🚫 No tracking - 100% offline, open source

1. Intercept keyboard events - Capture keystrokes before they reach apps
2. Send replacement text - Replace Latin characters with Vietnamese diacritics
3. Detect focused elements - Identify address bars, search fields, etc. for smart replacement

• Record your keystrokes
• Track which apps you use
• Access clipboard or files
• Connect to the internet

• Processes keystrokes in-memory only - No writing to disk (except user settings)
• No logging by default - Debug mode is manual opt-in and writes to /tmp/
• No cloud sync - Settings stored in macOS Preferences locally
• No third-party SDKs - Pure Rust + Swift, no analytics frameworks

• ~5MB RAM usage
• 64-character circular buffer (cleared on word boundaries)
• Settings stored in ~/Library/Preferences/org.gonhanh.*

• Corporate environments
• Confidential documents
• Password managers (typing passwords)
• Medical/legal software

• Respects macOS Secure Input mode (auto-disables during password entry)
• No network access
• BSD-3-Clause license (permissive for commercial use)

• macOS 13.0 (Ventura) or later
• Apple Silicon (M1/M2/M3/M4) or Intel

• Uses Fcitx5 framework
• See install-linux.md

• Uses SetWindowsHookEx for keyboard hooks
• See install-windows.md

​

Telex (default)

• s/f/r/x/j for tones (sắc/huyền/hỏi/ngã/nặng)
• aa/aw/ee/oo/ow/uw for vowel marks
• dd for đ

​

VNI

• 1/2/3/4/5 for tones
• 6/7/8/9 for vowel marks

1. Type the word (e.g., text)
2. Gõ Nhanh initially shows têt
3. Press Space
4. Engine checks if result is invalid Vietnamese
5. If invalid → auto-restores to original text

• Only triggers on Space
• Can’t detect words that form valid Vietnamese (e.g., mix → mĩ)
• Workaround: Press ESC to restore, or toggle Gõ Nhanh off (Ctrl+Space)

• . (period) + Space
• ! (exclamation) + Space
• ? (question mark) + Space
• Enter key (new line)

Type: "xin chào. bạn khỏe không?"
Result: "Xin chào. Bạn khỏe không?"

• vn → Việt Nam
• tpho → thành phố Hồ Chí Minh
• dc → được

• Code in VS Code with Gõ Nhanh OFF
• Switch to Slack → auto-enables
• Switch back to VS Code → auto-disables

• Chrome address bar → Selection mode (auto-detected)
• JetBrains IDEs → Selection mode (auto-detected)
• Claude Code/Cursor → Manual delay adjustment needed

• Rust engine processing: ~100-200μs
• macOS event handling: ~100-200μs
• FFI overhead: ~50μs
• Total: 300-500μs (well under 1ms)

• Address bars (Chrome, Safari, Arc) - uses selection instead of backspace
• JetBrains autocomplete - detected via bundle ID
• Excel cell editing - optimized replacement

• Password fields (auto-disables via Secure Input)
• Terminal commands (use Ctrl+Space to toggle off)

System Settings → Keyboard → Input Sources:
✅ English (ABC)  
✅ GoNhanh (for Vietnamese)
❌ Vietnamese (Telex/VNI) - remove this

• Japanese (Hiragana/Katakana)
• Chinese (Pinyin/Cangjie)
• Korean (2-Set Korean)
• French, German, Spanish, etc.

1. Backspace (to delete old char)
2. New character (to insert diacritic)

1. Settings → Advanced → Per-app customization
2. Add your IDE
3. Increase Delay slider to “Very High” (purple)

​

vs OpenKey

• Same approach: System-wide keyboard hook
• Gõ Nhanh advantages:
  • Rust core (faster, safer)
  • Auto-restore English words
  • Per-app delay customization
  • Modern SwiftUI interface
  • Active development (2025)

​

vs EVKey

• EVKey is Windows-focused
• Gõ Nhanh is cross-platform (macOS primary, Linux/Windows beta)

​

vs GoTiengViet

• Similar features
• Gõ Nhanh adds:
  • Validation-first engine (7-stage pipeline)
  • Better Chrome/IDE compatibility
  • Lower latency (sub-1ms vs 2-5ms)

• Modern architecture (Rust + Swift)
• Extreme performance focus
• Scientific documentation (linguistics + algorithms)

• First widely-adopted Vietnamese IME (1998-2016)
• Pioneered Telex/VNI input
• Established user expectations

• UniKey not maintained since 2016
• Doesn’t support modern macOS (Sonoma, Sequoia)
• 32-bit only (macOS dropped 32-bit in Catalina)
• No fix for Chrome address bar, Claude Code, etc.

• Bug reports: github.com/khaphanspace/gonhanh.org/issues
• Feature requests: Use “Feature Request” template
• Questions: GitHub Discussions

1. Check existing issues
2. Update to latest version
3. Include:
   • macOS version (sw_vers)
   • GoNhanh version (menu bar → About)
   • Steps to reproduce

1. Code: Rust engine, Swift UI, platform support
2. Testing: Report bugs, test beta features
3. Documentation: Improve guides, translations
4. Financial: GitHub Sponsors

git clone https://github.com/khaphanspace/gonhanh.org
cd gonhanh.org
make setup
make test
make build

• Ask questions
• Share tips
• Help other users

• Unikorn.vn (Vietnamese indie products)
• J2TEAM Launch (Vietnamese dev community)

• ✅ Use commercially
• ✅ Modify the code
• ✅ Distribute (original or modified)
• ✅ Use in proprietary software

• Include copyright notice
• Include license text
• Not use author’s name to promote without permission

• Personal use
• Commercial use
• Government use
• Educational use

• 100% offline (no data leaving network)
• No licensing fees
• Open source (auditable)
• BSD-3-Clause (permissive)

🚫 No fees - Free forever, no Pro version

• Personal time (author Kha Phan)
• GitHub Sponsors (optional donations)
• Community contributions

• Paid Pro version
• Subscription model
• Ads or sponsorships
• Selling user data (we don’t collect any!)