Skip to content
Fish-like autosuggestions for zsh
Shell Ruby Other
Branch: master
Clone or download
Type Name Latest commit message Commit time
Failed to load latest commit information.
.circleci Fix circle ci build issues Sep 30, 2019
.github/ISSUE_TEMPLATE Add issue templates Jul 3, 2019
spec Allow skipping completion suggestions when buffer matches a pattern Dec 15, 2019
src Merge pull request #487 from zsh-users/features/completion-ignore Jan 4, 2020
.editorconfig Set up circle ci Feb 26, 2017
.rspec Lots of async changes Feb 17, 2017
.rubocop.yml replace tabs in Rubocop config with spaces Aug 20, 2017
.ruby-version Build docker image for running tests Nov 19, 2018 Update changelog for v0.6.4 release Jan 7, 2020
DESCRIPTION Use `add-zsh-hook` to remove need to call `autosuggest_start`. Feb 7, 2016
Dockerfile Build docker image for running tests Nov 19, 2018
Gemfile Use pry-byebug instead of pry for more functionality Mar 3, 2017
Gemfile.lock Use pry-byebug instead of pry for more functionality Mar 3, 2017 Add package links to install docs (#222) Jul 3, 2019
LICENSE Update license copyright year Jun 16, 2019
Makefile Implement completion suggestion strategy (#111) Apr 11, 2019 Merge pull request #494 from zsh-users/develop Jan 7, 2020
URL Update URL references after repo move to zsh-users Feb 25, 2016
VERSION v0.6.4 Jan 7, 2020
ZSH_VERSIONS Support new zsh version Apr 9, 2019 Enable tcsetpgrp to support job control Apr 9, 2019
zsh-autosuggestions.plugin.zsh Adjust plugin.zsh file to run on zsh 5.1 in mSYS2. May 11, 2016
zsh-autosuggestions.zsh v0.6.4 Jan 7, 2020


Fish-like fast/unobtrusive autosuggestions for zsh.

It suggests commands as you type based on history and completions.

Requirements: Zsh v4.3.11 or later

CircleCI Chat on Gitter




As you type commands, you will see a completion offered after the cursor in a muted gray color. This color can be changed by setting the ZSH_AUTOSUGGEST_HIGHLIGHT_STYLE variable. See configuration.

If you press the key (forward-char widget) or End (end-of-line widget) with the cursor at the end of the buffer, it will accept the suggestion, replacing the contents of the command line buffer with the suggestion.

If you invoke the forward-word widget, it will partially accept the suggestion up to the point that the cursor moves to.


You may want to override the default global config variables. Default values of these variables can be found here.

Note: If you are using Oh My Zsh, you can put this configuration in a file in the $ZSH_CUSTOM directory. See their comments on overriding internals.

Suggestion Highlight Style

Set ZSH_AUTOSUGGEST_HIGHLIGHT_STYLE to configure the style that the suggestion is shown with. The default is fg=8, which will set the foreground color to color 8 from the 256-color palette. If your terminal only supports 8 colors, you will need to use a number between 0 and 7.

Background color can also be set, and the suggestion can be styled bold, underlined, or standout. For example, this would show suggestions with bold, underlined, pink text on a cyan background:


For more info, read the Character Highlighting section of the zsh manual: man zshzle or online.

Note: Some iTerm2 users have reported not being able to see the suggestions. If this affects you, the problem is likely caused by incorrect color settings. In order to correct this, go into iTerm2's setting, navigate to profile > colors and make sure that the colors for Basic Colors > Background and ANSI Colors > Bright Black are different.

Suggestion Strategy

ZSH_AUTOSUGGEST_STRATEGY is an array that specifies how suggestions should be generated. The strategies in the array are tried successively until a suggestion is found. There are currently three built-in strategies to choose from:

  • history: Chooses the most recent match from history.
  • completion: Chooses a suggestion based on what tab-completion would suggest. (requires zpty module)
  • match_prev_cmd: Like history, but chooses the most recent match whose preceding history item matches the most recently executed command (more info). Note that this strategy won't work as expected with ZSH options that don't preserve the history order such as HIST_IGNORE_ALL_DUPS or HIST_EXPIRE_DUPS_FIRST.

For example, setting ZSH_AUTOSUGGEST_STRATEGY=(history completion) will first try to find a suggestion from your history, but, if it can't find a match, will find a suggestion from the completion engine.

Widget Mapping

This plugin works by triggering custom behavior when certain zle widgets are invoked. You can add and remove widgets from these arrays to change the behavior of this plugin:

  • ZSH_AUTOSUGGEST_CLEAR_WIDGETS: Widgets in this array will clear the suggestion when invoked.
  • ZSH_AUTOSUGGEST_ACCEPT_WIDGETS: Widgets in this array will accept the suggestion when invoked.
  • ZSH_AUTOSUGGEST_EXECUTE_WIDGETS: Widgets in this array will execute the suggestion when invoked.
  • ZSH_AUTOSUGGEST_PARTIAL_ACCEPT_WIDGETS: Widgets in this array will partially accept the suggestion when invoked.
  • ZSH_AUTOSUGGEST_IGNORE_WIDGETS: Widgets in this array will not trigger any custom behavior.

Widgets that modify the buffer and are not found in any of these arrays will fetch a new suggestion after they are invoked.

Note: A widget shouldn't belong to more than one of the above arrays.

Disabling suggestion for large buffers

Set ZSH_AUTOSUGGEST_BUFFER_MAX_SIZE to an integer value to disable autosuggestion for large buffers. The default is unset, which means that autosuggestion will be tried for any buffer size. Recommended value is 20. This can be useful when pasting large amount of text in the terminal, to avoid triggering autosuggestion for strings that are too long.

Enable Asynchronous Mode

As of v0.4.0, suggestions can be fetched asynchronously. To enable this behavior, set the ZSH_AUTOSUGGEST_USE_ASYNC variable (it can be set to anything).

Disabling automatic widget re-binding

Set ZSH_AUTOSUGGEST_MANUAL_REBIND (it can be set to anything) to disable automatic widget re-binding on each precmd. This can be a big boost to performance, but you'll need to handle re-binding yourself if any of the widget lists change or if you or another plugin wrap any of the autosuggest widgets. To re-bind widgets, run _zsh_autosuggest_bind_widgets.

Ignoring history suggestions that match a pattern

Set ZSH_AUTOSUGGEST_HISTORY_IGNORE to a glob pattern to prevent offering suggestions for history entries that match the pattern. For example, set it to "cd *" to never suggest any cd commands from history. Or set to "?(#c50,)" to never suggest anything 50 characters or longer.

Note: This only affects the history and match_prev_cmd suggestion strategies.

Skipping completion suggestions for certain cases

Set ZSH_AUTOSUGGEST_COMPLETION_IGNORE to a glob pattern to prevent offering completion suggestions when the buffer matches that pattern. For example, set it to "git *" to disable completion suggestions for git subcommands.

Note: This only affects the completion suggestion strategy.

Key Bindings

This plugin provides a few widgets that you can use with bindkey:

  1. autosuggest-accept: Accepts the current suggestion.
  2. autosuggest-execute: Accepts and executes the current suggestion.
  3. autosuggest-clear: Clears the current suggestion.
  4. autosuggest-fetch: Fetches a suggestion (works even when suggestions are disabled).
  5. autosuggest-disable: Disables suggestions.
  6. autosuggest-enable: Re-enables suggestions.
  7. autosuggest-toggle: Toggles between enabled/disabled suggestions.

For example, this would bind ctrl + space to accept the current suggestion.

bindkey '^ ' autosuggest-accept


If you have a problem, please search through the list of issues on GitHub to see if someone else has already reported it.

Reporting an Issue

Before reporting an issue, please try temporarily disabling sections of your configuration and other plugins that may be conflicting with this plugin to isolate the problem.

When reporting an issue, please include:

  • The smallest, simplest .zshrc configuration that will reproduce the problem. See this comment for a good example of what this means.
  • The version of zsh you're using (zsh --version)
  • Which operating system you're running


  1. Remove the code referencing this plugin from ~/.zshrc.

  2. Remove the git repository from your hard drive

    rm -rf ~/.zsh/zsh-autosuggestions # Or wherever you installed


Build Process

Edit the source files in src/. Run make to build zsh-autosuggestions.zsh from those source files.

Pull Requests

Pull requests are welcome! If you send a pull request, please:

  • Request to merge into the develop branch (NOT master)
  • Match the existing coding conventions.
  • Include helpful comments to keep the barrier-to-entry low for people new to the project.
  • Write tests that cover your code as much as possible.


Tests are written in ruby using the rspec framework. They use tmux to drive a pseudoterminal, sending simulated keystrokes and making assertions on the terminal content.

Test files live in spec/. To run the tests, run make test. To run a specific test, run TESTS=spec/some_spec.rb make test. You can also specify a zsh binary to use by setting the TEST_ZSH_BIN environment variable (ex: TEST_ZSH_BIN=/bin/zsh make test).

A docker image for testing is available on docker hub. It comes with ruby, the bundler dependencies, and all supported versions of zsh installed.

Pull the docker image with:

docker pull ericfreese/zsh-autosuggestions-test

To run the tests for a specific version of zsh (where <version> below is substituted with the contents of a line from the ZSH_VERSIONS file):

docker run -it -e TEST_ZSH_BIN=zsh-<version> -v $PWD:/zsh-autosuggestions zsh-autosuggestions-test make test


This project is licensed under MIT license. For the full text of the license, see the LICENSE file.

You can’t perform that action at this time.