Installing OreoKey

OreoKey runs on macOS 13 (Ventura) or later, on both Apple Silicon and Intel (universal binary).

1. Download and install

1. Download the latest .dmg from the Releases page.
2. Open the DMG and drag OreoKey into your Applications folder.
3. Launch OreoKey from Applications (or Spotlight).

Releases are Developer ID-signed and notarized by Apple, so the app opens normally without Gatekeeper warnings.

2. Grant Accessibility permission (required)

The input method needs Accessibility permission to receive keys system-wide. On first launch, OreoKey shows a step-by-step onboarding:

1. Click the button to open System Settings → Privacy & Security → Accessibility.
2. Turn on the toggle next to OreoKey.
3. Return to the app — OreoKey picks up the permission and starts; the VN/EN badge appears in the menu bar.

If the toggle is on but the app still reports a missing permission: turn it off and on again, or run tccutil reset Accessibility com.oreosolutions.oreokey in Terminal and grant it again.

3. Initial setup

• Typing style: Telex by default. Switch to VNI right in the menu bar (Typing style) or in Settings → General.
• Vietnamese on/off hotkey: ⌃Space (Control+Space) by default. Change it in Settings → General.
• Launch at login: enable in Settings → General → System.

Note: you should disable or remove other Vietnamese input methods (including macOS’s built-in Vietnamese keyboard) so two engines don’t process the same keystrokes. When Vietnamese is on, OreoKey switches the system input source to a Latin (ABC) keyboard automatically.

4. Updates

OreoKey checks for new versions periodically (Sparkle). When an update lands, the Settings sidebar footer shows an orange warning — click it to install. To check manually: open Settings and click the version row at the bottom of the sidebar.

5. Uninstall

1. Quit OreoKey (menu bar → Quit OreoKey).
2. Delete OreoKey.app from Applications.
3. (Optional) Remove the configuration: ~/Library/Application Support/OreoKey/.

Building from source

Requirements: Rust (cargo) and the Xcode Command Line Tools.

git clone https://github.com/OreoSolutions/oreokey.git
cd oreokey
./scripts/build.sh    # → dist/OreoKey.app

Self-builds are ad-hoc signed: after every rebuild the old Accessibility grant stops working (the toggle stays ON but has no effect) — reset with tccutil reset Accessibility com.oreosolutions.oreokey and grant again.

Next: read the full user guide.

OreoKey user guide

The complete guide to every feature. Not installed yet? See Installing OreoKey.

Contents

• Menu bar
• Turning Vietnamese on / off
• Telex and VNI typing styles
• Spell checking
• Typing behaviour options
• Text shortcuts (macros)
• Per-app settings
• Fixing apps with flickering / stuck text
• Updates
• FAQ

Menu bar

The badge icon in the menu bar shows the current state:

• VN (solid) — Vietnamese typing is on.
• EN (thin outline) — off, typing plain English.

Click the icon to open the menu: toggle Vietnamese, pick the Telex/VNI style, open Settings… (⌘,) or quit the app.

Turning Vietnamese on / off

Three ways, all equivalent:

• The hotkey — ⌃Space (Control+Space) by default.
• The Vietnamese item in the menu bar.
• Automatically per app (see Per-app settings).

Change the hotkey in Settings → General; the options are ⌃⇧Space, ⌃Space, ⌘⇧Space, ⌥Z.

When Vietnamese is on, OreoKey switches the system input source to a Latin (ABC) keyboard so it never conflicts with another input method.

Telex and VNI typing styles

Pick one in the menu bar (Typing style) or in Settings → General.

Telex

Examples: vieejt → việt, dduwowngf → đường.

VNI

Examples: vie65t → việt, d9u7o72ng → đường.

Spell checking

Settings → General → Typing behaviour → Spell check — a three-level slider; the higher, the stricter:

Restoring means: type class on Strict and it stays class instead of turning into clạs.

Typing behaviour options

In Settings → General → Typing behaviour:

• Flexible circumflex typing — accepts mark keys placed late: nanag → nâng, viete → viêt.
• Modern mark placement — hoà, thuý instead of hòa, thúy.
• Text shortcuts — enables/disables every macro defined in the Macros tab.
• Profanity masking — sensitive words are replaced with * on commit.

Text shortcuts (macros)

Settings → Macros — a table of abbreviations that expand when you commit a word (type the abbreviation, then space/punctuation):

• Add: fill in Shortcut (e.g. vn) and Replace with (e.g. Việt Nam), press +.
• Delete: select a row, press −.
• A duplicate shortcut overwrites the old one.

Remember to keep the Text shortcuts toggle on in the General tab or macros won’t run.

Per-app settings

Settings → Apps:

• Remember state per app — every app keeps its own VN/EN state; switch between apps and each stays where you left it.
• Disable Vietnamese in these apps — apps that always start in English mode (terminals, IDEs…). The hotkey can still turn Vietnamese back on temporarily.
• Compatibility modes — override how text is injected for apps with display glitches (see the next section).

Both lists have an Add… menu: running apps are listed ready to pick; for apps that aren’t running use “Enter bundle ID…” — find the ID with:

osascript -e 'id of app "App Name"'
# or
mdls -name kMDItemCFBundleIdentifier -raw "/Applications/App Name.app"

Fixing apps with flickering / stuck text

OreoKey corrects text through four layers (Accessibility API → minimal diff → event batching → per-app quirk table), so most apps just work. If one specific app still flickers or sticks characters:

1. Open Settings → Apps → Compatibility modes.
2. Add override… → pick the misbehaving app.
3. Try the modes in order:
   • Fast injection — fits most flickering apps (terminals, Java/Swing apps, Electron).
   • Slow injection — for apps that re-render after every key (Word/Excel/PowerPoint, some online editors).
   • Automatic — the default; switch back here to undo.

Popular terminals (Terminal, iTerm2, kitty, Alacritty, WezTerm, Ghostty, Warp, Hyper, VS Code, JetBrains) ship pre-tuned.

Found a mode that fixes an app we don’t have a profile for? Open an issue with the bundle ID + app name + mode so the next release can ship it as the default for everyone.

Updates

• The app checks for new versions periodically in the background (Sparkle).
• The Settings sidebar footer always shows your current version: a green ✓ Up to date when current, an orange ⚠ warning when an update is available — click that row to check or install.

FAQ

No marks appear, the app doesn’t react? Check the Accessibility permission: System Settings → Privacy & Security → Accessibility → OreoKey must be ON. If it’s ON and still nothing, toggle it off/on, or run tccutil reset Accessibility com.oreosolutions.oreokey and grant it again.

Double letters (e.g. “masster”)? Version 0.5.2 and later ship a ghost-key guard. If it still happens, update to the latest build and file a bug with the app you were using.

English words get mangled while typing (class → clạs)? Raise Spell check to Strict — anything that isn’t a valid Vietnamese syllable is restored automatically.

Want English in Terminal/IDE without pressing the hotkey? Add the app to Settings → Apps → Disable Vietnamese in these apps.

Where is the configuration stored? ~/Library/Application Support/OreoKey/settings.json — delete the folder to reset to defaults.

Report a bug on GitHub ↗