Termhint Get Termhint

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

Download the DMG

  1. Download Termhint.dmg.
  2. Open it and drag Termhint to Applications.
  3. 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:

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:

  1. Click Allow… in Settings → Terminal → Apps, or Allow in the menu-bar panel. macOS shows its prompt and opens System Settings.
  2. 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:

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:

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.