Termhint Get Termhint

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

  1. Open a new tab. Tabs that were open before Termhint set up zsh need a new one.
  2. Is the shell zsh? Autocomplete is zsh only. bash gets prompt themes and colors, no popup; fish is not supported. echo $0 shows the shell.
  3. Is the shell integration on? Settings → Terminal → Apps has Turn On, or run termhint install.
  4. Is Termhint locked? termhint license shows how the trial or license stands. There is no popup while it is locked.
  5. 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.
  6. Is the command on the off list? termhint settings get popup.off-for lists commands the popup never opens for; termhint settings reset popup.off-for clears 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:

Ghostty autocomplete not working

Ghostty, kitty, WezTerm, Alacritty and Rio need no Accessibility: zsh asks the terminal where the cursor is. That has limits:

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

TerminalHow the cursor is foundWhat to check
Terminal, iTerm2Accessibility, else zsh asks the terminal for the cursorAccessibility for split panes
VS Code, VSCodium, Cursor, Windsurf, Kiro, Trae, Positron, Hyper, Tabby, WaveAccessibility (Electron's accessibility tree)The permission, editor.accessibilitySupport, the editor's own suggestions
Ghostty, kitty, WezTerm, Alacritty, Riozsh asks the terminal for the cursor cellGhostty split panes need Accessibility; kitty and Rio need a pane that fills the window
Kaku, JetBrains IDEs, cmux, TernAccessibilityThe permission
ZedA hidden input methodSettings → Terminal → Apps → Autocomplete in Zed
tmuxzsh asks the terminal, tmux tells where the pane sitsWorks in split panes; tmux must be on the shell's PATH (command -v tmux); not inside GNU screen
WarpNot supportedWarp's command editor bypasses zsh's line editor
OthersAccessibility first, then the cursor cellThe 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.

Download for Mac Troubleshooting