Termhint Get Termhint

Docs

Termhint troubleshooting: autocomplete popup, icons, prompt and license

Updated 19 November 2026

Start with the panel under Termhint's menu-bar icon. It shows whether autocomplete is on, the one step left if it is not, and the terminal tabs connected. To check the installed app itself (no changes, no network), run this; it prints one line per check and exits with status 0 when all pass:

/Applications/Termhint.app/Contents/MacOS/TermhintApp --selftest

Autocomplete popup doesn't appear

A step-by-step guide per terminal: terminal autocomplete not working on Mac.

Autocomplete in your terminal: what to check

TerminalHow the cursor is foundNotes
Terminal, iTerm2Accessibility, else zsh asks the terminal for the cursorSplit panes need Accessibility.
VS Code, VSCodium, Cursor, Windsurf, Kiro, Trae, Positron, Hyper, Tabby, WaveAccessibilitySet "editor.accessibilitySupport": "off" so the editor does not switch to screen-reader mode. Turn off the editor's own terminal suggestions to avoid two popups.
Ghostty, kitty, WezTerm, Alacritty, Riozsh asks the terminal for the cursor cell; no AccessibilityGhostty split panes need Accessibility; WezTerm's work; kitty and Rio need a pane that fills the window. Custom window padding or tab bar settings can shift the popup a little. Alacritty's layout is untested.
Kaku, JetBrains IDEs, cmux, TernAccessibilitySplit panes work in Kaku, cmux and Tern.
ZedA hidden input methodOff by default: turn on Settings → Terminal → Apps → Autocomplete in Zed.
tmuxzsh asks the terminal; tmux says where the pane isWorks in split panes too. tmux must be on the shell's PATH (command -v tmux). Not inside GNU screen.
WarpNot supportedIts own command editor bypasses zsh's line editor.
OthersTried with Accessibility, then the cursor cell

Icons show as boxes

A terminal draws an icon only with a font that has it. The full per-terminal fix is in terminal icons.

termhint icons            # each terminal: icons or standard symbols, and why
termhint icons setup      # turn icons on in every terminal Termhint can (installs fonts as needed)
termhint icons test       # run inside the terminal in question

Prompt theme didn't change

More about themes: prompt themes.

Termhint is locked: license and trial messages

termhint license and Settings → License show why.

MessageFix
"Termhint's free trial has ended."Buy a license in Settings → License and enter the key there. A key that was refunded or disabled is removed at its next check, which also ends here.
"Termhint couldn't check your license with Polar for 30 days."Connect to the internet, then Settings → License → Check Now.
"Your Termhint license has expired."The key had an end date that has passed. Buy a license in Settings → License.
A key that can't be activated on this MacIt is on all the Macs it allows. Deactivate This Mac on another Mac, or remove one in Manage Macs (Polar's customer portal).

While locked, every Settings page but License is disabled and termhint commands stop, except license, uninstall, runtime exec, colors off / reset / native off, icons off / font off / font none / remove, spec and help. Installed runtimes stay on PATH. Updates work in every license state.

The key is entered only in Settings → License, never on the command line. Find it again with Settings → License → Find My Key in Polar. Prices are on the pricing section.

Updates not showing or refused

A runtime install is refused

Every download is checked against its publisher's checksum and signature or attestation before anything in it runs. A missing or wrong one is a refusal, never a warning, so there is no switch to skip it. Releases without such a proof are not listed at all (runtime manager).

Remove Termhint completely

  1. Settings → License → Deactivate This Mac, so the key can go on another Mac (or remove the Mac later in Polar's customer portal).
  2. If you use them, turn off the administrator helper (Settings → Runtimes → Xcode) and open at login (Settings → App).
  3. In a terminal, run termhint uninstall --all. It undoes every change Termhint made outside its own folders: the zsh and bash blocks, the links on PATH, the colors in terminals' own config files and the icon and font settings it changed. It also turns the app's terminal setup off so a running Termhint does not add the block back, turns Autocomplete in Zed off (removing its input method), deletes what the popup learned, and prints what stays.
  4. Quit Termhint from the menu bar and move Termhint.app to the Trash. If you installed it with Homebrew: brew uninstall --cask toni1703/termhint/termhint.
  5. Remove Termhint from System Settings → Privacy & Security → Accessibility.

What stays, for you to delete if you want:

Logs

Termhint writes no log files and never logs command lines. The app writes a few lines (specs loaded, start-up failures) to macOS's unified log:

log show --predicate 'subsystem == "Termhint"' --last 1h

For a failed runtime action, use Copy Details in Settings → Runtimes.

Reporting a problem

Report… under an error in Settings or in the menu-bar panel's last row, or Report a Problem… in the app menu, asks where the report goes:

Security problems go privately to Report a vulnerability or to hello@termhint.com, never as an issue.

Download for Mac All docs