macOS Installation

Complete guide to installing and using Gõ Nhanh on macOS

Gõ Nhanh is a free, fast, and stable Vietnamese input method for macOS. Install and use immediately - no ads, no data collection.

Installation Methods

Homebrew (Recommended)

The easiest way to install Gõ Nhanh is using Homebrew:

brew install --cask gonhanh

After installation, grant accessibility permissions:

System Settings → Privacy & Security → Accessibility → Enable GoNhanh

The app automatically checks for updates every 24 hours. You can also manually update using:

brew upgrade --cask gonhanh

Manual Download

1. Download GoNhanh.dmg

   Download the latest version from GitHub:

   Download GoNhanh.dmg

2. Install the application

   Open the .dmg file and drag GoNhanh into your Applications folder.

3. Remove quarantine attribute

   You must quit the app before running this command.

   Open Terminal and run:

   xattr -cr /Applications/GoNhanh.app
   

   This removes the macOS quarantine attribute that prevents unsigned apps from running.

4. Grant accessibility permissions

   Launch GoNhanh, then go to:

   System Settings → Privacy & Security → Accessibility → Enable GoNhanh

System Requirements

• macOS 13.0 (Ventura) or later
• Apple Silicon or Intel processor

Usage

Keyboard Shortcuts

Shortcut	Function
Ctrl + Space	Toggle Vietnamese input on/off
ESC	Restore English text (e.g., úẻ → user)

Telex Mode (Default)

Telex is the default input method:

Type	Result
as, af, ar, ax, aj	á, à, ả, ã, ạ
aa, aw, ee, oo	â, ă, ê, ô
ow, uw, dd	ơ, ư, đ

Example: Type vieetj namd → việt nam

VNI Mode

Switch to VNI mode via: Menu Bar → Settings → Input Method → VNI

Type	Result
a1, a2, a3, a4, a5	á, à, ả, ã, ạ
a6, a8, o6, e6	â, ă, ô, ê
o7, u7, d9	ơ, ư, đ

Example: Type vie65t nam → việt nam

Key Features

Auto-restore English Words

When typing English words with Telex, Gõ Nhanh automatically restores them when you press Space:

Type	macOS Telex	Gõ Nhanh
text	têt ❌	text ✅
expect	ễpct ❌	expect ✅
perfect	pềct ❌	perfect ✅
with	ưith ❌	with ✅
luxury	lủuy ❌	luxury ✅

Some English words form valid Vietnamese syllables (e.g., mix → mĩ, box → bõ). For these cases, press ESC after typing to restore the original word.

Smart Mode Switching

Gõ Nhanh remembers the on/off state for each application:

• Code in VS Code (off) → Chat in Slack (on) → automatically switches

Auto-capitalization

Automatically capitalizes the first letter after ., !, ?, or Enter:

• Type ok. + Space + b → B (capitalized)

Abbreviations

Create custom abbreviations via Menu Bar → Settings → Abbreviations

Default abbreviations:

• vn → Việt Nam
• ko → không

Advanced Configuration

Per-Application Delay Settings

Experiencing text swallowing when using Claude Code in IDEs (VS Code, Cursor, Windsurf)?

1. Open Settings

   Click the Gõ Nhanh icon in the Menu Bar → Settings → Advanced tab

2. Add your IDE

   Under “Per-Application Settings”, click + and select your IDE

3. Adjust delay

   Drag the Delay slider to the right → “Very High” (purple)

4. Done

   Settings are saved automatically. Different machines and IDEs may require different delay settings.

Exception List

Add applications where you don’t want Vietnamese input:

Menu Bar → Settings → Exceptions → Add application

Launch at Login

System Settings → General → Login Items → Add GoNhanh

Updating

Homebrew

brew upgrade --cask gonhanh

Manual

Menu Bar → Settings → Updates → Download and Install

Or download the latest version from GitHub Releases

Uninstallation

Homebrew

brew uninstall --cask gonhanh

Manual

1. Quit the application

   Click the Menu Bar icon → Quit

2. Delete from Applications

   Remove GoNhanh.app from your Applications folder

3. Remove settings (optional)

   rm -rf ~/.config/gonhanh ~/Library/Preferences/org.gonhanh.*
   

Troubleshooting

App won’t open

Run this command in Terminal:

xattr -cr /Applications/GoNhanh.app

Then try opening the app again.

Can’t type Vietnamese

1. Check Menu Bar icon

   The icon should display “VN” when Vietnamese input is enabled

2. Toggle Vietnamese mode

   Press Ctrl + Space to toggle

3. Verify Accessibility permissions

   System Settings → Privacy & Security → Accessibility → Ensure GoNhanh is enabled

After macOS update

Sometimes macOS updates reset accessibility permissions:

System Settings → Privacy & Security → Accessibility → Toggle GoNhanh off and on again

Text swallowing in IDEs

See Per-Application Delay Settings above.

Supported Applications

Gõ Nhanh works with all macOS applications, including:

• Editors: VS Code, Zed, Cursor, Windsurf, JetBrains IDEs
• Browsers: Chrome, Safari, Firefox, Arc
• Chat: Slack, Discord, Telegram
• Notes: Notion, Obsidian, Apple Notes
• Terminals: Terminal.app, iTerm2, Ghostty
• AI Tools: Claude Code, ChatGPT Desktop

For best performance with Claude Code and similar AI coding assistants, adjust the per-application delay settings.

Privacy & Security

”Three No’s” Commitment

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

Accessibility Permissions

Gõ Nhanh requires Accessibility permissions to:

• Intercept keyboard events
• Transform Vietnamese input in real-time
• All processing happens locally on your device

Gõ Nhanh is open source. You can review the code at github.com/khaphanspace/gonhanh.org