Docs
Terminal autocomplete not working on Mac: causes and fixes
Last checked 19 November 2026
In short: when Termhint's popup does not show, the cause is almost always one of four: a tab opened before setup, a shell other than zsh, a missing Accessibility permission (editor terminals, JetBrains IDEs, Kaku, cmux, Tern, split panes in Terminal, iTerm2 and Ghostty), or a place the popup cannot follow the cursor (a kitty or Rio split pane, GNU screen, Warp, or Zed before you turn it on). Start with the panel under Termhint's menu-bar icon: it shows whether autocomplete is on and the one step left if it is not.
First checks, in any terminal
- Open a new tab. Tabs that were open before Termhint set up zsh need a new one.
- Is the shell zsh? Autocomplete is zsh only. bash gets prompt themes and colors, no popup; fish is not supported.
echo $0shows the shell. - Is the shell integration on? Settings → Terminal → Apps has Turn On, or run
termhint install. - Is Termhint locked?
termhint licenseshows how the trial or license stands. There is no popup while it is locked. - Was it closed on purpose? Esc hides the popup until the line changes, and after a word is accepted it stays closed until the line changes.
- Is the command on the off list?
termhint settings get popup.off-forlists commands the popup never opens for;termhint settings reset popup.off-forclears it.
Two checks that leave nothing changed:
/Applications/Termhint.app/Contents/MacOS/TermhintApp --selftest # one line per check; exit status 0 when all pass
open -n /Applications/Termhint.app --args --demo # the real popup in its own window, no terminal needed
If demo mode shows the popup, the app works and the problem is the terminal or the shell.
Terminal and iTerm2 autocomplete not working
Terminal.app and iTerm2 work without Accessibility: zsh asks the terminal where the cursor is. Their split panes need it. Allow Termhint in System Settings → Privacy & Security → Accessibility. If it is already on and the panel still asks for it, remove Termhint from the list with − and allow it again. Details in permissions.
VS Code terminal autocomplete not working
VS Code, VS Code Insiders, VSCodium, Cursor, Windsurf, Kiro, Trae, Positron, Hyper, Tabby and Wave need Accessibility: Termhint reads the cursor from Electron's accessibility tree. Two more settings matter:
- Set
"editor.accessibilitySupport": "off"so the editor does not switch to screen-reader mode. - Turn off the editor's own terminal suggestions, or you get two popups.
Ghostty autocomplete not working
Ghostty, kitty, WezTerm, Alacritty and Rio need no Accessibility: zsh asks the terminal where the cursor is. That has limits:
- Split panes: Ghostty's work with Accessibility allowed; WezTerm's work without it. kitty and Rio don't say where a pane is, so there the popup needs a pane that fills the window.
- tmux: the popup works inside tmux, in its split panes too.
tmuxmust be on the shell's PATH (command -v tmux). Not inside GNU screen. - Custom window padding or tab bar settings can shift the popup a little. Alacritty's layout is untested.
Zed autocomplete not working
Autocomplete in Zed is off by default. Turn on Settings → Terminal → Apps → Autocomplete in Zed (or termhint settings set terminals.zed-input on). A hidden input method tells Termhint where Zed's cursor is; it passes every key on and never reads what you type.
Every terminal at a glance
| Terminal | How the cursor is found | What to check |
|---|---|---|
| Terminal, iTerm2 | Accessibility, else zsh asks the terminal for the cursor | Accessibility for split panes |
| VS Code, VSCodium, Cursor, Windsurf, Kiro, Trae, Positron, Hyper, Tabby, Wave | Accessibility (Electron's accessibility tree) | The permission, editor.accessibilitySupport, the editor's own suggestions |
| Ghostty, kitty, WezTerm, Alacritty, Rio | zsh asks the terminal for the cursor cell | Ghostty split panes need Accessibility; kitty and Rio need a pane that fills the window |
| Kaku, JetBrains IDEs, cmux, Tern | Accessibility | The permission |
| Zed | A hidden input method | Settings → Terminal → Apps → Autocomplete in Zed |
| tmux | zsh asks the terminal, tmux tells where the pane sits | Works in split panes; tmux must be on the shell's PATH (command -v tmux); not inside GNU screen |
| Warp | Not supported | Warp's command editor bypasses zsh's line editor |
| Others | Accessibility first, then the cursor cell | The permission |
More on each terminal: terminals.
Is it Termhint or zsh?
Termhint's popup and zsh's own Tab completion are separate. If Tab still completes but the popup never appears, the cause is one of the checks above. If Tab completion itself is broken in a new tab, the cause is in your zsh setup (for example compinit or a plugin in ~/.zshrc), not in Termhint; Termhint only adds one marked block to the end of ~/.zshrc. zsh autocomplete explains how the two fit together.
Still not working
Other problems (icons, prompt, license, updates) are in troubleshooting. Use Report… in Settings or the menu-bar panel, or open an issue.