Termhint Get Termhint

How autocomplete works in Termhint

Updated 19 November 2026All docs

Termhint shows an autocomplete popup at the text cursor while you type a command in zsh. This page covers when it opens, the keys, what it completes, how it ranks suggestions, how to change its look and how to turn it off.

Note: Autocomplete works in zsh only. bash gets prompt themes and terminal colors, no popup. The popup needs the zsh integration (a marked block at the end of ~/.zshrc, see Install) and a new terminal tab after it was added.

When the popup opens

After every edit of the command line, zsh tells Termhint what you typed and where the cursor is. Termhint works out what can come next and shows the popup under the cursor once it has found the cursor on screen. How it finds the cursor depends on the terminal: see Supported terminals.

The popup opens when there is something to suggest:

It does not open:

The popup closes when the line runs, when you press Esc, and when another app comes to the front.

Keys

While the popup is open, zsh sends these keys to Termhint:

Key What it does
↑ ↓ Move the selection. It stops at the first and the last row.
Tab Insert the selected suggestion.
Enter Insert the selected suggestion. When the word already is the selected suggestion, Enter runs the line.
Esc Close the popup until the line changes.

Every other key goes to zsh as usual, and the popup follows the new line.

While the popup is closed, Tab, ↑, ↓, Enter and Esc do what they did before Termhint: zsh's own completion, history, or the widget you had bound to them (for example a history-substring-search plugin). Termhint binds Esc only while the popup is open, so Esc followed by another key works as before. If Termhint quits or stops while the popup is open, the keys go back to zsh.

The key bindings cannot be changed.

After you insert a suggestion

Mouse

What it completes

What Example Where it comes from
The command gi → git The commands on the shell's PATH, its aliases, functions and builtins
Subcommands git ch → checkout, cherry-pick The command's completion spec
Options git push --f → --force-with-lease The spec, zsh's own completion or the man page
Arguments npm run → the scripts in package.json The spec and live values
Files and folders cd → folders, cat → files The folder you typed, else the shell's current folder
Live values git branches, ssh hosts, Makefile targets, Docker containers Read by Termhint from local files and Docker's socket

Completion sources lists every source and the order Termhint uses them in.

The command word

As you type the first word, the popup lists the commands on the shell's PATH, its aliases (with the expansion as the description), its functions and builtins. Helper functions by convention (names starting with _, ., - or +, and TRAP… functions) are left out. The same list is used after commands that run another command, such as sudo. A program you just installed shows once it has run or after rehash, as with Tab.

An alias completes as its expansion: gco completes like git checkout . Termhint's short name (th unless you changed it) completes like termhint. A command installed under a versioned or second name completes as that command: pip3.14 as pip3, yarnpkg as yarn.

To stop suggestions for the command word, turn off Settings → Popup → Command names, or:

termhint settings set popup.command-names off

Files and folders

cd offers folders; other commands offer files and folders as their spec says (tsc lists .ts files first, cat every file). After a / the folder typed so far is listed (src/, ~/, /usr/). Hidden files show once you type a dot. A file name is quoted the way you started the word, and ~ stays as it is.

What it does not complete

How suggestions are matched

A suggestion matches when its name starts with what you typed, then when it starts with it ignoring case, then as an abbreviation whose first letter starts a word: cp finds cherry-pick, rs finds --reset-author. A query with a capital letter is matched case-sensitively. The letters you typed show in bold (popup.bold-matches).

Suggestions a spec marks as dangerous are shown in red. Hidden or deprecated ones show only when you type their full name. The popup lists at most 200 suggestions.

Ranking by use

Commands, subcommands and options you use move up among equal matches. The order is:

  1. A spec's own priority bands: what a spec puts on top stays on top, what it puts at the bottom stays at the bottom.
  2. How well the name matches what you typed.
  3. Within an ordinary priority, how often and how recently you used the name, counted per command and subcommand path (--force-with-lease after git push, not after every command).
  4. The spec's own order.

For the command word: an exact name first, then the best match, then the most used, then aliases, builtins and commands with a description, then shorter names.

Recent use counts more: a use within the last hour counts 4 times, within the day 2 times, within the week half, older a quarter. The counts are aged so they stay under 10,000 uses in total.

What it learns from

Settings → Popup → Learn from, or popup.learn:

Value Learns from
runs (default) Every command line that runs, typed or picked in the popup. A line you cancel with Ctrl-C teaches nothing.
picks Only suggestions you insert from the popup.
off Nothing. What was learned is deleted.

Termhint keeps only names it already knows (commands, and subcommands and options from specs), never arguments such as files, branches or hosts. They are stored in ~/Library/Application Support/Termhint/usage.json, readable by you only.

Reset what it learned

Turning learning off deletes the file. Turn it back on to start again:

termhint settings set popup.learn off
termhint settings set popup.learn runs

termhint uninstall --all deletes it too (see Uninstall).

Settings → Popup (⌘1) shows a live preview. Click a part of the preview to change it:

Below a width of 380 points the rows show names only and the details carry the description.

Every look setting is also a popup.* key: see Settings reference and Menu bar and Settings.

Turn it off

For some commands

Add commands in Settings → Popup → Where the popup stays away, or set the list from a terminal. The popup never opens for them, also after sudo:

termhint settings set popup.off-for ls,cat
termhint settings get popup.off-for
termhint settings reset popup.off-for

In all terminals

Settings → Terminal → Apps → Turn Off, or:

termhint settings set terminals.integration off

This removes Termhint's block from ~/.zshrc and keeps it off, so the prompt theme and terminal colors go too. Tabs that are open keep what they loaded until they close. termhint uninstall removes the block as well, but Termhint.app adds it back at its next launch while terminals.integration is on.

There is no switch for a single terminal app. Autocomplete in Zed is off until you turn it on (see Supported terminals).

Quitting Termhint from the menu bar also stops the popup; zsh keeps every key.

Test completions from a terminal

termhint complete prints what the popup would list for a command line, one line per suggestion: its kind, a tab, its name and its description.

termhint complete "git ch"
termhint complete "git checkout " ""

The first argument is the line up to the cursor, the optional second one the text after it. It uses the same specs and man pages as the popup but cannot ask zsh, so for a command without a spec it shows the man page's options instead of zsh's own completions.

termhint complete "git ch" takes 10 to 20 ms, including starting the process and loading the git spec. In the app, a keystroke reaches Termhint in about 0.1 ms.

To see the real popup without a terminal, open demo mode:

open -n /Applications/Termhint.app --args --demo

If the popup does not show in your terminal, see Autocomplete not working.