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
- Open a new tab. Terminals that were open before Termhint set up zsh need a new tab.
- Is the shell integration on? Settings → Terminal → Apps: the status card has Turn On.
termhint installadds it from a terminal. Autocomplete is zsh only: bash gets prompt themes and colors, no popup. - Accessibility. Editor terminals (VS Code and its forks, Hyper, Tabby, Wave), JetBrains IDEs, Kaku, cmux, Tern and split panes in Terminal, iTerm2 and Ghostty need it to find the cursor. Allow Termhint in System Settings → Privacy & Security → Accessibility (permissions). If it shows as on and the panel still asks for it, remove Termhint from that list with − and allow it again.
- It was closed on purpose. Esc hides the popup until the line changes. After a word is accepted, the popup stays closed until the line changes.
- The command is on the off list.
termhint settings get popup.off-forlists the commands the popup never opens for;termhint settings reset popup.off-forclears it. - Termhint is locked (see below): no popup until a license is active.
- Test the popup alone. Demo mode shows the real popup in a window of its own, without Accessibility, the shell or a terminal:
open -n /Applications/Termhint.app --args --demo.
A step-by-step guide per terminal: terminal autocomplete not working on Mac.
Autocomplete in your terminal: what to check
| Terminal | How the cursor is found | Notes |
|---|---|---|
| Terminal, iTerm2 | Accessibility, else zsh asks the terminal for the cursor | Split panes need Accessibility. |
| VS Code, VSCodium, Cursor, Windsurf, Kiro, Trae, Positron, Hyper, Tabby, Wave | Accessibility | Set "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, Rio | zsh asks the terminal for the cursor cell; no Accessibility | Ghostty 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, Tern | Accessibility | Split panes work in Kaku, cmux and Tern. |
| Zed | A hidden input method | Off by default: turn on Settings → Terminal → Apps → Autocomplete in Zed. |
| tmux | zsh asks the terminal; tmux says where the pane is | Works in split panes too. tmux must be on the shell's PATH (command -v tmux). Not inside GNU screen. |
| Warp | Not supported | Its own command editor bypasses zsh's line editor. |
| Others | Tried 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
termhint icons on <terminal>turns them on in one terminal;termhint icons off <terminal>puts its setting back.- Settings → Terminal → Apps has an Icons switch per terminal. Off means standard symbols there.
- A theme set with
--glyphs auto(the default) uses icons only where they show.termhint theme set <name> --glyphs unicodeorasciinever uses Nerd Font icons. - Tab titles are drawn with the system font. It finds Nerd Font icons from U+F0000 up in an installed Nerd Font, but not the older ones below it.
- Warp is not supported.
Prompt theme didn't change
- A tab opened before this version of Termhint needs to be reopened once. After that,
termhint theme setchanges open tabs at once. - Themes need the shell integration (above). In bash, run
termhint install bashfirst; a change shows at the next prompt. - Git status and a language's version appear a moment after the prompt. Git status needs Termhint running.
- While Termhint is locked, the prompt gives way to the shell's own. Your choice is kept and comes back with a license.
termhint theme offputs back the prompt you had before (Starship, oh-my-zsh and so on).- Colors and the tab title do not work inside tmux or screen.
More about themes: prompt themes.
Termhint is locked: license and trial messages
termhint license and Settings → License show why.
| Message | Fix |
|---|---|
| "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 Mac | It 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
- Termhint checks for updates once a day; the switch is in Settings → App.
- To check now, click the version in the menu-bar panel's header, or Check for Updates… in the app menu. When a daily check finds a version, the version becomes an "Update · X.Y.Z" button and the menu-bar icon gets a dot.
- An update installs only if it carries Termhint's signature and is signed by the same developer as the installed app. If one is refused, download Termhint again from termhint.com.
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).
- Settings → Runtimes shows what failed, with Try Again; Details, Copy Details and Report… give the reason.
- Listings that go through GitHub's API are limited to 60 requests an hour without a token. A
GITHUB_TOKENin your environment raises the limit; it is sent only toapi.github.com. - Elixir needs Erlang first:
termhint runtime install erlang. Ruby is precompiled for Apple silicon only. - Xcode: sign in once in Settings → Runtimes → Xcode. A
.xipmust pass Apple's signature check (pkgutil --check-signature), and the Xcode in it must passcodesign(Apple's team) and Gatekeeper; anything else is refused.
Remove Termhint completely
- Settings → License → Deactivate This Mac, so the key can go on another Mac (or remove the Mac later in Polar's customer portal).
- If you use them, turn off the administrator helper (Settings → Runtimes → Xcode) and open at login (Settings → App).
- 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. - 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. - Remove Termhint from System Settings → Privacy & Security → Accessibility.
What stays, for you to delete if you want:
~/.config/termhint(your themes, color schemes, tab title, runtime defaults)~/.local/share/termhint/runtimes(installed runtimes) and~/.cache/termhint~/Library/Application Support/Termhint(popup icons you imported)- Nerd Fonts installed by
termhint icons, in~/Library/Fonts - The keychain items: the license record ("Termhint license"; kept so a reinstall does not restart the trial) and the Apple developer session (remove it first with Settings → Runtimes → Xcode → Sign Out…)
- Xcodes in
/Applicationsinstalled through Termhint
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:
- Open on GitHub: the bug report form of toni1703/termhint-issues opens in your browser with Termhint's version, your macOS version and the error filled in (your home folder as
~). Issues there are public: check the text and leave out keys, tokens, email addresses and anything private before you submit. Needs a GitHub account. - Email Instead: a mail to hello@termhint.com with the same details, read only by Termhint's developer.
Security problems go privately to Report a vulnerability or to hello@termhint.com, never as an issue.