Install Termhint on a Mac
Updated 19 November 2026All docs
How to install Termhint, what it changes on its first launch, and the few things to allow or turn on afterwards. It takes a minute; the free trial starts at the first launch.
Requirements
- macOS 14 (Sonoma) or later, on a Mac with Apple silicon.
- zsh for autocomplete, which is macOS's default shell. bash gets prompt themes, terminal colors, tab titles and runtime versions, without the autocomplete popup (see bash).
Download the DMG
- Download Termhint.dmg.
- Open it and drag Termhint to Applications.
- Open Termhint from Applications.
Releases are signed, and notarized by Apple. Termhint then updates itself: see Updates.
Install with Homebrew
brew install --cask toni1703/termhint/termhint
The cask comes from the tap toni1703/homebrew-termhint and needs macOS 14 or later. Termhint updates itself, so the cask is marked as auto-updating and brew upgrade leaves it alone. Open Termhint once after the install. To remove it with Homebrew, see Uninstall.
What the first launch does
When Termhint opens:
- A Termhint icon appears in the menu bar. A click on it opens the menu-bar panel.
- If Accessibility is not allowed yet, macOS asks for it (see Accessibility).
- It sets up zsh: it writes
~/.config/termhint/shell/termhint.zshand adds one marked block to the end of~/.zshrcthat loads it in every new zsh. Before it changes~/.zshrc, it saves a copy next to it as~/.zshrc.termhint-backup-<time>. If you setZDOTDIR, it uses the.zshrcthere. - It puts the
termhintcommand on PATH (see The termhint command). - Settings opens, once. The Settings window shows a live preview of the popup.
The ~/.zshrc block
The block is the only change in ~/.zshrc, and it is marked so it can be removed byte for byte. It loads Termhint's script in every new zsh: autocomplete, the prompt theme and colors you pick, tab titles and runtime versions. The script also adds ~/.config/termhint/shell/bin to the end of PATH.
Termhint rewrites the script at every launch, so an updated app updates it. It adds the block again at launch while the terminal setup is on. You can do the same from a terminal:
termhint install
To keep the block out, turn the setup off in Settings → Terminal → Apps (Turn Off), or run termhint settings set terminals.integration off. See Uninstall.
A prompt theme with --instant adds a second marked block at the top of ~/.zshrc, also backed up first. See Prompt themes.
Allow Accessibility
Accessibility lets Termhint find the text cursor in other apps, so the popup opens right under what you type. Whether you need it depends on the terminal:
| Terminal | Accessibility |
|---|---|
| Terminal, iTerm2 | Not needed; needed for split panes |
| Ghostty | Not needed; needed for split panes |
| kitty, WezTerm, Alacritty, Rio | Not needed |
| VS Code, Cursor, Windsurf, VSCodium, Kiro, Trae, Positron, Hyper, Tabby, Wave | Needed |
| JetBrains IDEs, Kaku, cmux, Tern | Needed |
| Zed | Not used: turn on Settings → Terminal → Apps → Autocomplete in Zed |
Warp is not supported. Each supported terminal, with its setup, is on Supported terminals.
To allow it:
- Click Allow… in Settings → Terminal → Apps, or Allow in the menu-bar panel. macOS shows its prompt and opens System Settings.
- In System Settings → Privacy & Security → Accessibility, turn Termhint on.
Termhint notices the change within a few seconds; you do not need to restart it. What Accessibility is used for, and how to revoke it, is on Permissions.
Open a new terminal tab
A shell reads ~/.zshrc only when it starts. Terminal tabs that were open before Termhint set up zsh need a new tab. In a new tab, type git ch: the popup opens at the cursor. ↑ and ↓ select, Tab or Enter inserts, Esc hides it. More on the keys in Autocomplete.
Settings on first launch
Settings opens by itself on the first launch only. Later, open it with:
- Settings… (⌘ ,) in the menu-bar panel, or a section tile there;
- opening Termhint.app again, or a click on its Dock icon;
termhint license open, for Settings → License.
Termhint is in the Dock only while Settings is open. Closing Settings, or Quit on its Dock icon, closes the window and leaves autocomplete running. To quit Termhint itself, use Quit Termhint in the menu-bar panel or the app menu. Every pane is described in The menu bar and Settings.
Open at login
Termhint does not open at login until you turn it on. Without it, autocomplete stops after a restart until you open Termhint again. Turn it on with any of these:
- the Open at login switch in Settings → Terminal → Apps;
- the Open at login switch in the menu-bar panel;
termhint settings set app.open-at-login on.
If macOS asks for approval, the state reads "Needs approval": click Open Login Items in Settings → Terminal → Apps and allow Termhint in System Settings → General → Login Items.
bash
Termhint sets up zsh by itself. For bash, run:
termhint install bash
It writes termhint.bash and sources it from the end of ~/.bashrc and of the login file bash reads: the first that exists of ~/.bash_profile, ~/.bash_login and ~/.profile, else a new ~/.bash_profile. Each file is backed up first. bash gets the same prompt themes, terminal colors, tab titles and runtime versions, without autocomplete. termhint uninstall bash removes it.
The termhint command
In every new zsh tab, the termhint command is on PATH: the script adds ~/.config/termhint/shell/bin, where termhint is a link to the copy inside Termhint.app. Termhint relinks it at every launch while the terminal setup is on.
th is a short name for it: th theme set pure runs termhint theme set pure. To change it, type another name in Settings → Terminal → Apps → Short name and click Apply. Termhint checks the name against a new zsh as you type: a name that a command, alias, function or builtin already has is refused, since that one would run instead. Leave the field empty to keep only termhint. The setting is also terminals.short-name.
Every command is in the CLI reference. termhint help lists them in the terminal.
Demo mode
Demo mode shows the real popup in a window of its own, with a pretend shell line, without Accessibility, the shell setup or a terminal. Nothing you type runs, and it changes nothing by itself. It also runs next to a Termhint that is already open:
open -n /Applications/Termhint.app --args --demo
Use it to try the popup before you allow anything, or to check whether a problem is in the popup or in the terminal.