Support · KeyVi

Look for a quick answer below. If that does not help, report a bug as described at the end of the page.

FAQ

Why is there no "type tone marks anywhere in the word" option?

Because it is always on and not a setting. You can type the tone key after the final consonant (vietj, tieengs), in the middle of the word, or the second d at the end (dangd) and the result is correct.

An English word still gets marks, or a Vietnamese word stays unchanged. What now?

Open Settings, Typing. Under English restore there are two lists: "keep as typed" and "keep as Vietnamese". Add the word to the matching list and you are done. You can also report the word so it can be considered for the bundled data.

Why are there no quick consonant shortcuts (cc to ch, kk to kh)?

Because they break ordinary words (cc becomes ch, kkk becomes khk). KeyVi leaves them out on purpose, even as an option.

Is the tone placed as hòa or hoà?

The default is the traditional style (hòa, thủy, khỏe). The modern style (hoà, thuỷ, khoẻ) is one toggle away in Settings, Typing.

Are TCVN3, VNI-Windows or CP1258 supported?

No. KeyVi outputs precomposed Unicode (NFC) only, which every current app reads.

What is the Vietnamese/English toggle key, and can I change it?

By default you tap and release Control + Shift. Change it in Settings, General. If you pick a combination macOS already uses (for example Command+Space), the app accepts it but warns you which macOS feature owns it. See how to turn off that macOS shortcut.

Why does KeyVi pause when I pick a Japanese, Chinese or Korean keyboard?

When you select an input source that does not use Latin letters (Japanese, Chinese, Korean and similar), KeyVi pauses on its own and dims its menu bar icon, so your keys go straight to that input method: typing kore in a Japanese input method does not turn into kỏe. Select the ABC or U.S. keyboard again and KeyVi types Vietnamese again. This is deliberate and not a setting.

Does KeyVi work in password fields?

Password fields are always skipped and keys go straight to the app. This is deliberate and not a setting.

What about QWERTZ, AZERTY, Dvorak or Colemak keyboards?

They work. KeyVi follows the keyboard layout macOS is using, with nothing to configure.

Does the app send what I type anywhere?

No. See the Privacy page for exactly what the app stores and sends.

My Mac runs macOS 11 or older.

KeyVi requires macOS 12 Monterey or later, on Apple silicon or Intel. See the Download page for the current figure.

How do I uninstall?

Quit KeyVi and drag the app to the Trash. To remove the data as well, see the last section of the Privacy page.

Troubleshooting by symptom

Permission is on but I still cannot type

KeyVi needs permission to receive your keystrokes. The pane name depends on your macOS version:

macOS 12: System Preferences > Security & Privacy > Privacy > Accessibility (click the lock to make changes).
macOS 13 to 26: System Settings > Privacy & Security > Accessibility.
macOS 27: System Settings > Privacy & Security > Device Control and Data Access (previously Accessibility). VERIFY

Make sure KeyVi is in /Applications (or ~/Applications), not running from the DMG.
Turn on the switch for KeyVi in that pane. The app notices within a few seconds.
If the switch is already on but nothing works (common after a macOS update): select KeyVi in the list, press the minus (-) button to remove it, then add it again. Or use the Reset permission button in the app, which resets only KeyVi's own entry.
To do it yourself in Terminal: tccutil reset Accessibility vn.kal.keyvi. Always include the bundle identifier. Never run sudo tccutil reset Accessibility without one, because that clears every app's permission. VERIFY The service name may differ on macOS 27.

While permission is missing your keyboard keeps typing normally; KeyVi just pauses and never blocks keys.

Typing is paused and the menu mentions secure input

When an app turns on macOS Secure Event Input, the system stops delivering keystrokes to every background input tool, not only KeyVi. It is usually caused by a password field that is still open. KeyVi pauses only when macOS reports this mode or when the focused field really is a password field. It does not guess, and it resumes on the very first key after the mode ends.

The KeyVi menu names the app that is likely holding it (a best guess that is sometimes wrong):

Terminal: turn off Secure Keyboard Entry in the Terminal menu.
iTerm2: iTerm2 has Secure Keyboard Entry turned on. Turn off iTerm2 > Secure Keyboard Entry, or finish or cancel the password prompt it is waiting for.
Browsers: click outside the password field or switch tabs.
Password managers and other apps: close their password entry window.
Unknown app, or the menu points at loginwindow: lock the screen and unlock it (Control + Command + Q), or log out and back in.

Letters are doubled or missing

Two input methods running at once make letters double or disappear. Quit the other one and stop it from starting at login. KeyVi warns you when it detects one, but never quits or changes other apps itself.

Quit the old input method (XKey, OpenKey, EVKey, Gõ Nhanh, PHTV or similar) from its menu bar icon.
System Settings > General > Login Items & Extensions: remove the old input method from the open-at-login list. VERIFY
If the built-in macOS Vietnamese input source is enabled, choose the ABC or U.S. keyboard while you use KeyVi.

App-specific guides are in the moving from another input method section.

It fails in one app only

Look the app up in the compatibility list: it may already have a note or a workaround.
Try typing in KeyVi's practice field (the Test in the practice field button in the report flow) to see whether the problem is specific to that app or happens everywhere.
In the KeyVi menu, the With app name submenu can set Always English or Ignore this app if you need to keep working right now.
Report it with Report a problem with this app...: the report is pre-filled with the app, its version and the active rule.

The toggle key clashes with a macOS shortcut

If you pick a combination macOS already uses, KeyVi still saves your choice and shows a warning that names the macOS feature using it. To keep the combination for KeyVi alone, turn that shortcut off or change it in macOS:

Open System Settings > Keyboard and click Keyboard Shortcuts.... VERIFY The item names on each macOS version.
Choose the group in the left column (see the list below), then untick the shortcut to turn it off, or double-click its key combination to assign another one.

Command + Space: the Spotlight group, Show Spotlight search.
Control + Space and Control + Option + Space: the Input Sources group, select the previous input source and select the next source.
Control + Command + Space: opens the Emoji & Symbols viewer. This shortcut lives in each app's Edit menu, not in the groups above; you can assign another combination to that menu item in the App Shortcuts group. VERIFY The menu item and group names on each macOS version.
Command + Tab (switching apps), Command + Q (quitting apps) and Command + W (closing windows): macOS does not let you turn these off. Choose another combination for KeyVi.

KeyVi does not read the macOS shortcut settings, so the warning in Settings stays after you have turned the shortcut off. You can ignore it then.

How to report a bug

The quickest way is from inside the app: the KeyVi menu > Report a problem....

Pick the app where the problem happened (your last app is preselected).
Pick what happened: missing letters, doubled letters, wrong tone, cannot type Vietnamese, slow or laggy, other.
Type again the example you typed and the result you expected. KeyVi never sends what you typed on its own.
Open Preview what will be sent to see the exact report. Then choose Open GitHub (the report is copied to your clipboard for you to paste), Send by email, or Save file....

You do not need a GitHub account: the email path always works.

KeyVi will never ask you for verbose logs or for what you typed. Only when really needed will a maintainer invite you to record a short typing trace (60 seconds), which you review yourself before sharing.

Support channels

GitHub Issues: bugs and app compatibility.
GitHub Discussions: questions and ideas.
Email [email protected] VERIFY for anyone who does not use GitHub.

Sorry, we do not offer support through private messages on social networks. Using the channels above lets everyone see the answer.

Response targets

These are targets, counted in business days and best effort. This is a one-person personal project.

When Kal is away for more than a week, the website shows a notice with the expected return date.

Moving from another input method

Guides for moving your macro list from the input method you use now. Today KeyVi imports macros from a text file (tab-separated or CSV), from a macOS Text Replacements file and from its own export; it does not read other input methods' export files yet. KeyVi imports only a file you choose yourself, and only after you press import. The app never reads another app's data on its own.

Priority	First response	Resolution target
P0 (lost text, freeze, cannot type)	24 hours	Pull the update or give a workaround within 24 hours of confirmation; fix or rollback release within 72 hours
P1	3 days	Next beta; next stable
P2	7 days	Planned in a milestone, or labelled a known limitation with an explanation
P3 and feature requests	Reviewed monthly	Answered with: accept, decline with a reason, or "later"