Terminals · iTerm2
iTerm2 autocomplete: zsh suggestions as you type
Last checked 19 November 2026
In short: iTerm2 has a word autocomplete of its own (Cmd-;) that suggests words already shown in the window. It does not know commands, options or arguments. Termhint adds a zsh autocomplete popup to iTerm2 that does: subcommands, options, arguments, git branches and dynamic suggestions such as your npm run scripts. It needs no permission in iTerm2; only split panes need Accessibility.
Set up iTerm2 autocomplete for zsh
- Download Termhint, move it to Applications and open it. On launch it adds one marked block to
~/.zshrc, backed up first. - Termhint shows macOS's Accessibility prompt at first launch. Allow it if you use iTerm2's split panes; for single panes you can decline it. Without it, zsh asks iTerm2 where the cursor is (and its exact cell size) on every edit, and Termhint places the popup in the window (permissions).
- Open a new tab. Tabs that were open before Termhint set up zsh don't have it yet.
- Type
git ch. The popup opens under the cursor; Tab, the arrows, Esc and Enter go to it only while it is open.
iTerm2's own autocomplete
iTerm2's feature page says: "Just type the start of any word that has ever appeared in your window and then Cmd-; will pop open a window with suggestions" (iterm2.com features). It completes words from the screen, on request. Termhint's popup opens as you type and its suggestions come from the command line: Fig's open-source completion specs, zsh's own completion functions and, for commands without either, the options in the command's man page. The two can be used side by side, since iTerm2's opens only on Cmd-;.
If what you want is iTerm2's word completion, you need nothing else. If you want suggestions for git, docker, kubectl or brew subcommands and flags, that is what Termhint adds.
What Termhint adds to iTerm2
- Suggestions for subcommands, options, arguments, files and folders, from bundled specs for 3,272 commands and the zsh completion functions on your Mac, plus the command name itself as you type it (
gioffersgit). No plugin to install in zsh: Termhint adds one block to~/.zshrcand removes it byte for byte ontermhint uninstall. - Live values Termhint reads itself, without running git, ssh or docker: git branches, tags and stashes, ssh hosts, Docker containers and images and Makefile targets.
- Colors. iTerm2 keeps its settings in a preferences database, so Termhint's color schemes reach it through the shell when a tab starts; iTerm2's own profiles are not changed.
- Icons.
termhint icons on iterm2sets a Nerd Font as the default profile's non-ASCII font. It writes iTerm2's preferences while iTerm2 is not running, so quit iTerm2 first; Termhint does not script the app. - Prompt themes and tab titles, drawn by the shell.
Limits in iTerm2
- zsh only. bash gets prompt themes and colors, not the popup.
- Split panes need Accessibility. Without it, a custom margin setting can shift the popup a little.
- Inside tmux it works, tmux's split panes too; not inside GNU screen.
- No completion specs you write yourself.
- Apple silicon and macOS 14 or later.
Not working?
- No popup in an iTerm2 split pane: allow Accessibility in System Settings → Privacy & Security → Accessibility. If Termhint shows as on and the panel still asks for it, remove it with − and allow it again.
- The panel under Termhint's menu-bar icon shows whether autocomplete is on, the one step left if it is not, and the terminal tabs connected.
- Your shell must be zsh. bash gets prompt themes and colors, no popup.
- Esc hides the popup until the line changes.
More fixes: terminal autocomplete not working and troubleshooting.