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:
- While you type the command itself: the commands, aliases, functions and builtins that start with what you typed.
- After a command and a space: its subcommands and arguments. Options show when the word is empty or starts with
-. - While you type a word: what matches that word.
It does not open:
- For an empty command line, or while the first word is a path (
./,~/,/usr/) or an assignment (FOO=bar). - When the cursor is inside a word (a character other than a blank follows it).
- After a redirection (
>,<), where a file name goes. - In zsh's vi command mode, in a
selectmenu or invared. - For a command on the off list (
popup.off-for, see Turn it off). - While Termhint is locked (see License).
- After you pressed Esc or accepted a word that ends there, until the line changes.
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
- A word that is complete gets no blank after it, and the popup stays closed. Type a space to see what comes next, or press Enter to run the line.
- A folder (
src/) or an option that takes a value after=(--format=) keeps the popup open with what comes next.
Mouse
- Right-click the popup for a menu: Details of the Selected Item, Key Hints, Descriptions in Rows, Reset Size and Termhint Settings….
- Drag the grip at the bottom right to resize the popup. The width follows the pointer, the height snaps to whole rows, and the size is saved.
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
- Lines from your shell history. Termhint ranks names you use instead (below).
- Values that need a spec's JavaScript or a generator Termhint does not read itself, for example kubectl resources or tmux sessions.
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:
- 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.
- How well the name matches what you typed.
- Within an ordinary priority, how often and how recently you used the name, counted per command and subcommand path (
--force-with-leaseaftergit push, not after every command). - 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).
Popup look
Settings → Popup (⌘1) shows a live preview. Click a part of the preview to change it:
- 12 ready-made themes (System, Rose, Rose Dark, Aurora, Lagoon, Graphite, Nord, Dracula, Catppuccin, Tokyo Night, Solarized Light, GitHub Light). They change colors only.
- Light, dark or as macOS is; a blurred, solid or gradient background, its colors and opacity; corner radius, width and the number of rows.
- The font and size of names, their color and the color of the matched letters.
- Descriptions on or off, in a column or against the right edge.
- An icon for each kind of suggestion (any SF Symbol, an emoji or up to two characters, or your own image), plain or on a colored badge.
- The details of the selected suggestion (below the list, or beside it from a width of 680 points) and the footer with the position and the keys.
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.