Bash autocomplete with descriptions, on macOS

Figxit adds an IDE-style suggestion list to bash on macOS. Type docker run -- and the options appear under the cursor, each with a one-line description. It needs bash 5 or later.

Apple Silicon, macOS 13 or later. zsh, bash 5, or fish 4. tmux is optional. No account, no AI chat, no telemetry.

macOS ships bash 3.2

The /bin/bash of macOS is version 3.2. Figxit needs bash 5 or later. Install it with Homebrew and check the version of the shell you are in:

brew install bash
echo $BASH_VERSION

What bash completes by default

bash completes when you press Tab. With the bash-completion package it knows the subcommands and options of many commands. It prints the candidate names with no description, it does not open while you type, and it does not know which subcommand you use most in a project.

What Figxit adds to bash

• A list that opens as you type. No Tab press is needed to see what a command can do.
• Subcommands for 700+ tools. Figxit loads the open source Fig completion specs, for example for git, docker, npm, and kubectl. Each row has a one-line description.
• Options with descriptions. Type a dash to see the options of the command on the line. Options you have already typed are hidden.
• Your own project. make lists the targets of the Makefile in the current folder. npm run , pnpm , yarn , and bun run list the scripts of package.json.
• Ranking from your history. With Atuin installed, a word scores higher when you used it in the same folder, in the same repository, or recently.

The list is a native macOS window. It does not take keyboard focus, and nothing is drawn inside your terminal.

Set up bash

1. Download Figxit.dmg, open it, and drag Figxit to Applications.
2. Open Figxit. The setup window shows the line for your login shell and can add it. To add the bash line yourself, put it in ~/.bashrc, or in ~/.bash_profile if that file does not load ~/.bashrc.
3. Open a new terminal and type a command.

eval "$('/Applications/Figxit.app/Contents/MacOS/figxit-engine' init bash)"

How it works in bash

bash cannot open a unix socket or watch one. Each bash session starts one bridge process, which holds the connection to the Figxit engine. The adapter binds each printable key and each editing key to a macro: the original function, then a hook that writes the line to the bridge through a pipe.

Tab, Enter, Up, and Down first ask if the list is open, and run their original binding if it is not.

Limits in bash

• The list is off in vi mode.
• A key with a character outside ASCII, a paste, and a Tab completion do not update the list until the next key.
• Each key clears and draws the input line again, which is how bash runs a key hook.
• Escape as a prefix for a Meta key works only when the second key follows within 0.5 seconds.

Questions and answers

More about Figxit