Zsh Autosuggestions

https://github.com/zsh-users/zsh-autosuggestions
Admin
Zsh Autosuggestions provides fast and unobtrusive autosuggestions for the Zsh shell, similar to Fish...
Tokens:27,772
Snippets:204
Trust Score:7.3
License:MIT
Update:1 week ago
Show doc for...
Tokens:
Raw
### Install with Oh My Zsh

Source: https://github.com/zsh-users/zsh-autosuggestions/blob/master/INSTALL.md

Clone the repository into the Oh My Zsh custom plugins directory, then add the plugin to the plugins list in .zshrc. Start a new terminal session after.

```sh
git clone https://github.com/zsh-users/zsh-autosuggestions ${ZSH_CUSTOM:-~/.oh-my-zsh/custom}/plugins/zsh-autosuggestions
```

```sh
plugins=( 
    # other plugins...
    zsh-autosuggestions
)
```

--------------------------------

### Install with Homebrew

Source: https://github.com/zsh-users/zsh-autosuggestions/blob/master/INSTALL.md

Install zsh-autosuggestions via Homebrew, then source the autosuggestions script in your .zshrc. Start a new terminal session after.

```sh
brew install zsh-autosuggestions
```

```sh
source $(brew --prefix)/share/zsh-autosuggestions/zsh-autosuggestions.zsh
```

--------------------------------

### Manual installation via Git Clone

Source: https://github.com/zsh-users/zsh-autosuggestions/blob/master/INSTALL.md

Clone the repository to ~/.zsh/zsh-autosuggestions and source the autosuggestions script in your .zshrc. Start a new terminal session after.

```sh
git clone https://github.com/zsh-users/zsh-autosuggestions ~/.zsh/zsh-autosuggestions
```

```sh
source ~/.zsh/zsh-autosuggestions/zsh-autosuggestions.zsh
```

--------------------------------

### Standard load in ~/.zshrc

Source: https://github.com/zsh-users/zsh-autosuggestions/blob/master/_autodocs/api-reference/plugin-entry-point.md

Standard manual install: source the built bundle from ~/.zshrc.

```zsh
# ~/.zshrc
source ~/.zsh/zsh-autosuggestions/zsh-autosuggestions.zsh
```

--------------------------------

### Install with Antigen

Source: https://github.com/zsh-users/zsh-autosuggestions/blob/master/INSTALL.md

Add this line to your .zshrc to install zsh-autosuggestions via Antigen. Then start a new terminal session.

```sh
antigen bundle zsh-users/zsh-autosuggestions
```

--------------------------------

### Startup setup from src/start.zsh

Source: https://github.com/zsh-users/zsh-autosuggestions/blob/master/_autodocs/api-reference/plugin-entry-point.md

Top-level code from src/start.zsh that sets up the plugin. It autoloads hook helpers, sets ZSH_AUTOSUGGEST_USE_ASYNC (empty) when zsh >= 5.0.8 to enable async fetching, and registers _zsh_autosuggest_start as a precmd hook.

```zsh
autoload -Uz add-zsh-hook is-at-least

if is-at-least 5.0.8; then
	typeset -g ZSH_AUTOSUGGEST_USE_ASYNC=
fi

add-zsh-hook precmd _zsh_autosuggest_start
```

--------------------------------

### Configure ZSH_AUTOSUGGEST_HIGHLIGHT_STYLE

Source: https://github.com/zsh-users/zsh-autosuggestions/blob/master/_autodocs/api-reference/highlighting.md

Example of setting the highlight style in .zshrc before or after sourcing the plugin.

```sh
# ~/.zshrc
source ~/.zsh/zsh-autosuggestions/zsh-autosuggestions.zsh

# bold, underlined, pink-on-cyan suggestion
ZSH_AUTOSUGGEST_HIGHLIGHT_STYLE="fg=#ff00ff,bg=cyan,bold,underline"
```

--------------------------------

### Sync completion capture: _zsh_autosuggest_capture_completion_sync

Source: https://github.com/zsh-users/zsh-autosuggestions/blob/master/_autodocs/api-reference/completion-capture.md

Runs setup and invokes autosuggest-capture-completion directly. Used when the strategy is called while zle is active (sync mode).

```zsh
_zsh_autosuggest_capture_completion_sync() {
	_zsh_autosuggest_capture_setup

	zle autosuggest-capture-completion
}

```

--------------------------------

### Bind key to accept suggestion

Source: https://github.com/zsh-users/zsh-autosuggestions/blob/master/README.md

Example of binding the Ctrl + Space key combination to the autosuggest-accept widget.

```sh
bindkey '^ ' autosuggest-accept
```

--------------------------------

### zsh: _zsh_autosuggest_capture_setup function

Source: https://github.com/zsh-users/zsh-autosuggestions/blob/master/_autodocs/api-reference/completion-capture.md

Configures the zpty environment for capturing completions. On zsh < 5.4, installs a zshexit hook that SIGKILLs the current process and sleeps briefly to guard against an old zpty bug. Hardens completion matching with zstyle settings and binds TAB to autosuggest-capture-completion.

```zsh
_zsh_autosuggest_capture_setup() {
	# There is a bug in zpty module in older zsh versions by which a
	# zpty that exits will kill all zpty processes that were forked
	# before it. Here we set up a zsh exit hook to SIGKILL the zpty
	# process immediately, before it has a chance to kill any other
	# zpty processes.
	if ! is-at-least 5.4; then
		zshexit() {
			# The zsh builtin `kill` fails sometimes in older versions
			# https://unix.stackexchange.com/a/477647/156673
			kill -KILL $$ 2>&- || command kill -KILL $$

			# Block for long enough for the signal to come through
			sleep 1
		}
	fi

	# Try to avoid any suggestions that wouldn't match the prefix
	zstyle ':completion:*' matcher-list ''
	zstyle ':completion:*' path-completion false
	zstyle ':completion:*' max-errors 0 not-numeric

	bindkey '^I' autosuggest-capture-completion
}
```

--------------------------------

### Define _zsh_autosuggest_async_request to fork suggestion fetching

Source: https://github.com/zsh-users/zsh-autosuggestions/blob/master/_autodocs/api-reference/async.md

Public function that starts an asynchronous suggestion request. It loads zsh/system for `$sysparams`, declares the FD and child PID globals, and cancels any pending request by closing the file descriptor and removing its handler before forking the child process.

```zsh
_zsh_autosuggest_async_request() {
	zmodload zsh/system 2>/dev/null # For `$sysparams`

	typeset -g _ZSH_AUTOSUGGEST_ASYNC_FD _ZSH_AUTOSUGGEST_CHILD_PID

	# If we've got a pending request, cancel it
	if [[ -n "$_ZSH_AUTOSUGGEST_ASYNC_FD" ]] && { true <&$_ZSH_AUTOSUGGEST_ASYNC_FD } 2>/dev/null; then
		# Close the file descriptor and remove the handler
		builtin exec {_ZSH_AUTOSUGGEST_ASYNC_FD}>&-
		zle -F $_ZSH_AUTOSUGGEST_ASYNC_FD

		unset _ZSH_AUTOSUGGEST_ASYNC_FD
	fi

	# Fork the process in the background
	_zsh_autosuggest_strategy_$ZSH_AUTOSUGGEST_STRATEGY &!

	# Get the PID for the child process we just forked
	_ZSH_AUTOSUGGEST_CHILD_PID=$!

	# Create a new file descriptor pointing to a pipe and register a zle handler for it
	builtin exec {_ZSH_AUTOSUGGEST_ASYNC_FD} < <(cat <&$ZSH_AUTOSUGGEST_ASYNC_FD 2>/dev/null) 2>/dev/null

	# Set the type of the fd to be a file descriptor for zle -F to work properly
	zle -F $_ZSH_AUTOSUGGEST_ASYNC_FD _zsh_autosuggest_async_response
}

```

--------------------------------

### Configure Suggestion Highlight Style

Source: https://github.com/zsh-users/zsh-autosuggestions/blob/master/README.md

Set the ZSH_AUTOSUGGEST_HIGHLIGHT_STYLE variable to customize the appearance of suggestions. This example applies bold, underlined, pink text on a cyan background.

```sh
ZSH_AUTOSUGGEST_HIGHLIGHT_STYLE="fg=#ff00ff,bg=cyan,bold,underline"
```

--------------------------------

### Fetch suggestion function _zsh_autosuggest_fetch_suggestion

Source: https://github.com/zsh-users/zsh-autosuggestions/blob/master/_autodocs/api-reference/strategies.md

This function iterates through the configured strategies to find a valid suggestion for the current buffer. It validates that the suggestion starts with the provided prefix and stops at the first successful match.

```zsh
_zsh_autosuggest_fetch_suggestion() {
	typeset -g suggestion
	local -a strategies
	local strategy

	# Ensure we are working with an array
	strategies=(${=ZSH_AUTOSUGGEST_STRATEGY})

	for strategy in $strategies; do
		# Try to get a suggestion from this strategy
		_zsh_autosuggest_strategy_$strategy "$1"

		# Ensure the suggestion matches the prefix
		[[ "$suggestion" != "$1"* ]] && unset suggestion

		# Break once we've found a valid suggestion
		[[ -n "$suggestion" ]] && break
	done
}
```

--------------------------------

### _zsh_autosuggest_capture_completion_widget - capture completion buffer

Source: https://github.com/zsh-users/zsh-autosuggestions/blob/master/_autodocs/api-reference/completion-capture.md

Runs the real completion widget inside the pty, moves the cursor to the end of the buffer, disables CR/LF transformations on zsh >= 5.0.3, and prints the resulting buffer delimited by NUL bytes. Installs a postcompletion hook to modify compstate after completions are gathered.

```zsh
_zsh_autosuggest_capture_completion_widget() {
	# Add a post-completion hook to be called after all completions have been
	# gathered. The hook can modify compstate to affect what is done with the
	# gathered completions.
	local -a +h comppostfuncs
	comppostfuncs=(_zsh_autosuggest_capture_postcompletion)

	# Only capture completions at the end of the buffer
	CURSOR=$#BUFFER

	# Run the original widget wrapping `.complete-word` so we don't
	# recursively try to fetch suggestions, since our pty is forked
	# after autosuggestions is initialized.
	zle -- ${(k)widgets[(r)completion:.complete-word:_main_complete]}

	if is-at-least 5.0.3; then
		# Don't do any cr/lf transformations. We need to do this immediately before
		# output because if we do it in setup, onlcr will be re-enabled when we enter
		# vared in the async code path. There is a bug in zpty module in older versions
		# where the tty is not properly attached to the pty slave, resulting in stty
		# getting stopped with a SIGTTOU. See zsh-workers thread 31660 and upstream
		# commit f75904a38
		stty -onlcr -ocrnl -F /dev/tty
	fi

	# The completion has been added, print the buffer as the suggestion
	echo -nE - $'\0'$BUFFER$'\0'
}
```

--------------------------------

### Async completion capture: _zsh_autosuggest_capture_completion_async

Source: https://github.com/zsh-users/zsh-autosuggestions/blob/master/_autodocs/api-reference/completion-capture.md

Sets up the environment, loads zsh/parameter, wraps _complete to handle vared completion, and opens zle with vared 1 to capture completions. Returns early if zsh/parameter is unavailable.

```zsh
_zsh_autosuggest_capture_completion_async() {
	_zsh_autosuggest_capture_setup

	zmodload zsh/parameter 2>/dev/null || return # For `$functions`

	# Make vared completion work as if for a normal command line
	# https://stackoverflow.com/a/7057118/154703
	autoload +X _complete
	functions[_original_complete]=$functions[_complete]
	function _complete() {
		unset 'compstate[vared]'
		_original_complete "$@"
	}

	# Open zle with buffer set so we can capture completions for it
	vared 1
}

```

--------------------------------

### Wrapper entry point: zsh-autosuggestions.plugin.zsh

Source: https://github.com/zsh-users/zsh-autosuggestions/blob/master/_autodocs/api-reference/plugin-entry-point.md

One-line wrapper that sources the built bundle. The ${0:A:h} expansion resolves the wrapper's directory (following symlinks) so plugin managers can load the plugin without symlink support.

```zsh
source ${0:A:h}/zsh-autosuggestions.zsh
```

--------------------------------

### Increment bind count for a widget

Source: https://github.com/zsh-users/zsh-autosuggestions/blob/master/_autodocs/api-reference/widget-binding.md

Increments the bind count for a widget in the global associative array _ZSH_AUTOSUGGEST_BIND_COUNTS. Each wrap gets a fresh, monotonically increasing count so nested wraps do not collide.

```zsh
_zsh_autosuggest_incr_bind_count() {
	typeset -gi bind_count=$((_ZSH_AUTOSUGGEST_BIND_COUNTS[$1]+1))
	_ZSH_AUTOSUGGEST_BIND_COUNTS[$1]=$bind_count
}
```

--------------------------------

### Backing implementation of autosuggest-accept widget

Source: https://github.com/zsh-users/zsh-autosuggestions/blob/master/_autodocs/api-reference/widgets.md

The `_zsh_autosuggest_accept` function implements the `autosuggest-accept` widget. It accepts the current suggestion by appending `$POSTDISPLAY` to `$BUFFER` when the cursor is at the end of the buffer (or at `$#BUFFER - 1` in `vicmd` keymap). If the cursor is not in a valid position or there is no suggestion, it invokes the original widget and returns. The function then invokes the original widget before moving the cursor to the end of the buffer, and returns the original widget's exit status.

```zsh
_zsh_autosuggest_accept() {
	local -i retval max_cursor_pos=$#BUFFER

	# When vicmd keymap is active, the cursor can't move all the way
	# to the end of the buffer
	if [[ "$KEYMAP" = "vicmd" ]]; then
		max_cursor_pos=$((max_cursor_pos - 1))
	fi

	# If we're not in a valid state to accept a suggestion, just run the
	# original widget and bail out
	if (( $CURSOR != $max_cursor_pos || !$#POSTDISPLAY )); then
		_zsh_autosuggest_invoke_original_widget $@
		return
	fi

	# Only accept if the cursor is at the end of the buffer
	# Add the suggestion to the buffer
	BUFFER="$BUFFER$POSTDISPLAY"

	# Remove the suggestion
	POSTDISPLAY=

	# Run the original widget before manually moving the cursor so that the
	# cursor movement doesn't make the widget do something unexpected
	_zsh_autosuggest_invoke_original_widget $@
	retval=$?

	# Move the cursor to the end of the buffer
	if [[ "$KEYMAP" = "vicmd" ]]; then
		CURSOR=$(($#BUFFER - 1))
	else
		CURSOR=$#BUFFER
	fi

	return $retval
}
```

--------------------------------

### Add widget and re-bind

Source: https://github.com/zsh-users/zsh-autosuggestions/blob/master/_autodocs/api-reference/widget-binding.md

Shows how to add a widget to the ZSH_AUTOSUGGEST_ACCEPT_WIDGETS list and re-bind so it takes effect immediately.

```sh
ZSH_AUTOSUGGEST_ACCEPT_WIDGETS+=my-custom-accept-widget
_zsh_autosuggest_bind_widgets
```

--------------------------------

### Build Docker image for testing

Source: https://github.com/zsh-users/zsh-autosuggestions/blob/master/README.md

Build a Docker image for a specific version of zsh to run tests in an isolated environment.

```sh
docker build --build-arg TEST_ZSH_VERSION=<version> -t zsh-autosuggestions-test .
```

--------------------------------

### Widget autosuggest-execute implementation

Source: https://github.com/zsh-users/zsh-autosuggestions/blob/master/_autodocs/api-reference/widgets.md

Appends the suggestion to the buffer, clears POSTDISPLAY, and invokes the original accept-line widget to ensure proper syntax highlighting and behavior.

```zsh
_zsh_autosuggest_execute() {
	# Add the suggestion to the buffer
	BUFFER="$BUFFER$POSTDISPLAY"

	# Remove the suggestion
	POSTDISPLAY=

	# Call the original `accept-line` to handle syntax highlighting or
	# other potential custom behavior
	_zsh_autosuggest_invoke_original_widget "accept-line"
}
```

--------------------------------

### Implementation of _zsh_autosuggest_partial_accept

Source: https://github.com/zsh-users/zsh-autosuggestions/blob/master/_autodocs/api-reference/widgets.md

This function temporarily appends the suggestion to the buffer, invokes the original widget to move the cursor, and then re-splits the buffer and POSTDISPLAY based on the new cursor position. It includes normalization for vi-mode cursor positioning.

```zsh
_zsh_autosuggest_partial_accept() {
	local -i retval cursor_loc

	# Save the contents of the buffer so we can restore later if needed
	local original_buffer="$BUFFER"

	# Temporarily accept the suggestion.
	BUFFER="$BUFFER$POSTDISPLAY"

	# Original widget moves the cursor
	_zsh_autosuggest_invoke_original_widget $@
	retval=$?

	# Normalize cursor location across vi/emacs modes
	cursor_loc=$CURSOR
	if [[ "$KEYMAP" = "vicmd" ]]; then
		cursor_loc=$((cursor_loc + 1))
	fi

	# If we've moved past the end of the original buffer
	if (( $cursor_loc > $#original_buffer )); then
		# Set POSTDISPLAY to text right of the cursor
		POSTDISPLAY="${BUFFER[$(($cursor_loc + 1)),$#BUFFER]}"

		# Clip the buffer at the cursor
		BUFFER="${BUFFER[1,$cursor_loc]}"
	else
		# Restore the original buffer
		BUFFER="$original_buffer"
	fi

	return $retval
}
```

--------------------------------

### Run tests in Docker

Source: https://github.com/zsh-users/zsh-autosuggestions/blob/master/README.md

Execute the test suite inside the previously built Docker container.

```sh
docker run -it -v $PWD:/zsh-autosuggestions zsh-autosuggestions-test make test
```

--------------------------------

### Opt in to async on older zsh

Source: https://github.com/zsh-users/zsh-autosuggestions/blob/master/_autodocs/api-reference/async.md

Enables async autosuggestion fetching on zsh < 5.0.8 by setting ZSH_AUTOSUGGEST_USE_ASYNC=1 after sourcing the plugin. Known ^C caveat from issue #364.

```sh
source ~/.zsh/zsh-autosuggestions/zsh-autosuggestions.zsh
ZSH_AUTOSUGGEST_USE_ASYNC=1
```

--------------------------------

### Implementation of _zsh_autosuggest_strategy_match_prev_cmd

Source: https://github.com/zsh-users/zsh-autosuggestions/blob/master/_autodocs/api-reference/strategies.md

This function implements the match_prev_cmd strategy by scanning history for entries that match the current prefix and follow the previously executed command.

```zsh
_zsh_autosuggest_strategy_match_prev_cmd() {
	# Reset options to defaults and enable LOCAL_OPTIONS
	emulate -L zsh

	# Enable globbing flags so that we can use (#m) and (x~y) glob operator
	setopt EXTENDED_GLOB

	# TODO: Use (b) flag when we can drop support for zsh older than v5.0.8
	local prefix="${1//(#m)[\\*?\[\]<>()|^~#]/\\$MATCH}"

	# Get the history items that match the prefix, excluding those that match
	# the ignore pattern
	local pattern="$prefix*"
	if [[ -n $ZSH_AUTOSUGGEST_HISTORY_IGNORE ]]; then
		pattern="($pattern)~($ZSH_AUTOSUGGEST_HISTORY_IGNORE)"
	fi

	# Get all history event numbers that correspond to history
	# entries that match the pattern
	local history_match_keys
	history_match_keys=(${(k)history[(R)$~pattern]})

	# By default we use the first history number (most recent history entry)
	local histkey="${history_match_keys[1]}"

	# Get the previously executed command
	local prev_cmd="$(_zsh_autosuggest_escape_command "${history[$((HISTCMD-1))]}")"

	# Iterate up to the first 200 history event numbers that match $prefix
	for key in "${(@)history_match_keys[1,200]}"; do
		# Stop if we ran out of history
		[[ $key -gt 1 ]] || break

		# See if the history entry preceding the suggestion matches the
		# previous command, and use it if it does
		if [[ "${history[$((key - 1))]}" == "$prev_cmd" ]]; then
			histkey="$key"
			break
		fi
	done

	# Give back the matched history entry
	typeset -g suggestion="$history[$histkey]"
}
```

--------------------------------

### Public function _zsh_autosuggest_start

Source: https://github.com/zsh-users/zsh-autosuggestions/blob/master/_autodocs/api-reference/plugin-entry-point.md

Public function invoked as a precmd hook. It calls _zsh_autosuggest_bind_widgets to (re)bind widgets; if ZSH_AUTOSUGGEST_MANUAL_REBIND is set, it removes itself from the hook so re-binding happens only once at startup.

```zsh
_zsh_autosuggest_start() {
	# By default we re-bind widgets on every precmd to ensure we wrap other
	# wrappers. Specifically, highlighting breaks if our widgets are wrapped by
	# zsh-syntax-highlighting widgets. This also allows modifications to the
	# widget list variables to take effect on the next precmd. However this has
	# a decent performance hit, so users can set ZSH_AUTOSUGGEST_MANUAL_REBIND
	# to disable the automatic re-binding.
	if (( ${+ZSH_AUTOSUGGEST_MANUAL_REBIND} )); then
		add-zsh-hook -d precmd _zsh_autosuggest_start
	fi

	_zsh_autosuggest_bind_widgets
}
```

--------------------------------

### Force a fetch with zle autosuggest-fetch

Source: https://github.com/zsh-users/zsh-autosuggestions/blob/master/_autodocs/api-reference/widgets.md

Executes the fetch widget manually. This command remains functional even when suggestions are disabled.

```sh
zle autosuggest-fetch
```

--------------------------------

### Configure ZSH_AUTOSUGGEST_PARTIAL_ACCEPT_WIDGETS

Source: https://github.com/zsh-users/zsh-autosuggestions/blob/master/_autodocs/configuration.md

Defines widgets that accept a partial suggestion.

```zsh
(( ! ${+ZSH_AUTOSUGGEST_PARTIAL_ACCEPT_WIDGETS} )) && {
	typeset -ga ZSH_AUTOSUGGEST_PARTIAL_ACCEPT_WIDGETS
	ZSH_AUTOSUGGEST_PARTIAL_ACCEPT_WIDGETS=(
		forward-word
		emacs-forward-word
		vi-forward-word
		vi-forward-word-end
		vi-forward-blank-word
		vi-forward-blank-word-end
		vi-find-next-char
		vi-find-next-char-skip
	)
}
```

--------------------------------

### Configure ZSH_AUTOSUGGEST_EXECUTE_WIDGETS

Source: https://github.com/zsh-users/zsh-autosuggestions/blob/master/_autodocs/configuration.md

Defines widgets that accept and execute the suggestion in one step.

```zsh
(( ! ${+ZSH_AUTOSUGGEST_EXECUTE_WIDGETS} )) && {
	typeset -ga ZSH_AUTOSUGGEST_EXECUTE_WIDGETS
	ZSH_AUTOSUGGEST_EXECUTE_WIDGETS=(
	)
}
```

--------------------------------

### Configure ZSH_AUTOSUGGEST_COMPLETION_IGNORE

Source: https://github.com/zsh-users/zsh-autosuggestions/blob/master/_autodocs/api-reference/strategies.md

Define patterns to skip for completion suggestions, such as git subcommands.

```sh
ZSH_AUTOSUGGEST_COMPLETION_IGNORE="git *"
```

--------------------------------

### Configure ZSH_AUTOSUGGEST_ACCEPT_WIDGETS

Source: https://github.com/zsh-users/zsh-autosuggestions/blob/master/_autodocs/configuration.md

Defines the list of widgets that accept the current suggestion.

```zsh
(( ! ${+ZSH_AUTOSUGGEST_ACCEPT_WIDGETS} )) && {
	typeset -ga ZSH_AUTOSUGGEST_ACCEPT_WIDGETS
	ZSH_AUTOSUGGEST_ACCEPT_WIDGETS=(
		forward-char
		end-of-line
		vi-forward-char
		vi-end-of-line
		vi-add-eol
	)
}
```

--------------------------------

### Set configuration options before sourcing zsh-autosuggestions

Source: https://github.com/zsh-users/zsh-autosuggestions/blob/master/_autodocs/configuration.md

Set ZSH_AUTOSUGGEST_HIGHLIGHT_STYLE, ZSH_AUTOSUGGEST_STRATEGY, ZSH_AUTOSUGGEST_BUFFER_MAX_SIZE, ZSH_AUTOSUGGEST_HISTORY_IGNORE, and ZSH_AUTOSUGGEST_COMPLETION_IGNORE before sourcing the plugin. Values take effect on the first precmd. Also shows how to disable async on modern zsh by unsetting ZSH_AUTOSUGGEST_USE_ASYNC.

```sh
# ~/.zshrc
ZSH_AUTOSUGGEST_HIGHLIGHT_STYLE="fg=#ff00ff,bg=cyan,bold,underline"
ZSH_AUTOSUGGEST_STRATEGY=(history completion)
ZSH_AUTOSUGGEST_BUFFER_MAX_SIZE=20
ZSH_AUTOSUGGEST_HISTORY_IGNORE="(cd *|?(#c50,))"
ZSH_AUTOSUGGEST_COMPLETION_IGNORE="git *"

source ~/.zsh/zsh-autosuggestions/zsh-autosuggestions.zsh

# disable async on modern zsh
unset ZSH_AUTOSUGGEST_USE_ASYNC
```

--------------------------------

### Widget: autosuggest-suggest

Source: https://github.com/zsh-users/zsh-autosuggestions/blob/master/_autodocs/api-reference/widgets.md

Offers the suggestion by computing the portion of the suggestion not already present in the buffer. If the suggestion or buffer is empty, POSTDISPLAY is cleared.

```zsh
_zsh_autosuggest_suggest() {
	emulate -L zsh

	local suggestion="$1"

	if [[ -n "$suggestion" ]] && (( $#BUFFER )); then
		POSTDISPLAY="${suggestion#$BUFFER}"
	else
		POSTDISPLAY=
	fi
```

--------------------------------

### Widget: autosuggest-fetch

Source: https://github.com/zsh-users/zsh-autosuggestions/blob/master/_autodocs/api-reference/widgets.md

Fetches a suggestion based on the current zle $BUFFER. If ZSH_AUTOSUGGEST_USE_ASYNC is set, it delegates to an async request; otherwise, it fetches synchronously.

```zsh
_zsh_autosuggest_fetch() {
	if (( ${+ZSH_AUTOSUGGEST_USE_ASYNC} )); then
		_zsh_autosuggest_async_request "$BUFFER"
	else
		local suggestion
		_zsh_autosuggest_fetch_suggestion "$BUFFER"
		_zsh_autosuggest_suggest "$suggestion"
	fi
}
```

--------------------------------

### Set strategy order

Source: https://github.com/zsh-users/zsh-autosuggestions/blob/master/_autodocs/api-reference/strategies.md

Configure the order of strategies to use, such as checking history first and falling back to completions.

```sh
ZSH_AUTOSUGGEST_STRATEGY=(history completion)
```

--------------------------------

### Inspect current suggestion highlight

Source: https://github.com/zsh-users/zsh-autosuggestions/blob/master/_autodocs/api-reference/highlighting.md

Prints the current region_highlight entry applied by the plugin, which is non-empty while a suggestion is visible.

```sh
# print the current suggestion highlight entry (non-empty while a suggestion shows)
print -r -- "$_ZSH_AUTOSUGGEST_LAST_HIGHLIGHT"
```

--------------------------------

### Define and register a custom autosuggestion strategy

Source: https://github.com/zsh-users/zsh-autosuggestions/blob/master/_autodocs/api-reference/strategies.md

Create a function following the _zsh_autosuggest_strategy_<name> naming convention and add it to the ZSH_AUTOSUGGEST_STRATEGY array in your .zshrc file.

```zsh
# ~/.zshrc — after sourcing the plugin
_zsh_autosuggest_strategy_fixed() {
	local prefix="$1"
	# custom rule: always suggest a fixed command that extends the buffer
	typeset -g suggestion="$prefix--flag"
}

ZSH_AUTOSUGGEST_STRATEGY=(history fixed)
```

--------------------------------

### Configure ZSH_AUTOSUGGEST_STRATEGY

Source: https://github.com/zsh-users/zsh-autosuggestions/blob/master/_autodocs/configuration.md

Sets an ordered array of strategy names to be tried until a suggestion is returned.

```zsh
(( ! ${+ZSH_AUTOSUGGEST_STRATEGY} )) && {
	typeset -ga ZSH_AUTOSUGGEST_STRATEGY
	ZSH_AUTOSUGGEST_STRATEGY=(history)
}
```

--------------------------------

### Configure ZSH_AUTOSUGGEST_ORIGINAL_WIDGET_PREFIX

Source: https://github.com/zsh-users/zsh-autosuggestions/blob/master/_autodocs/configuration.md

Defines the prefix used when saving the original implementation of a wrapped widget.

```zsh
(( ! ${+ZSH_AUTOSUGGEST_ORIGINAL_WIDGET_PREFIX} )) &&
typeset -g ZSH_AUTOSUGGEST_ORIGINAL_WIDGET_PREFIX=autosuggest-orig-
```

--------------------------------

### Define and export a custom suggestion strategy

Source: https://github.com/zsh-users/zsh-autosuggestions/wiki/How-to-Add-Custom-Suggestion-Strategy

Defines a custom strategy function that runs an external script to set the suggestion, then exports the strategy list to include both 'history' and 'custom'. The function must set the global variable `suggestion`.

```shell
_zsh_autosuggest_strategy_custom() {
  typeset -g suggestion
  suggestion=`./my-custom-suggestion-script.sh "$1"`
}

export ZSH_AUTOSUGGEST_STRATEGY=(history custom)
```

--------------------------------

### Generated wrapper function template

Source: https://github.com/zsh-users/zsh-autosuggestions/blob/master/_autodocs/api-reference/widgets.md

Shows the exact body of the wrapper function generated for each action. It resets the highlight, runs the action, re-applies the highlight, redraws the line editor, and returns the captured status.

```zsh
_zsh_autosuggest_widget_<action>() {
	local -i retval

	_zsh_autosuggest_highlight_reset

	_zsh_autosuggest_<action> $@
	retval=$?

	_zsh_autosuggest_highlight_apply

	zle -R

	return $retval
}
```

--------------------------------

### Define _zsh_autosuggest_async_response handler

Source: https://github.com/zsh-users/zsh-autosuggestions/blob/master/_autodocs/api-reference/async.md

Called when new data is ready to be read from the pipe. First arg will be fd ready for reading. Second arg will be passed in case of error. Runs with `emulate -L zsh` to localize options. Only consumes the pipe when `$2` is empty or `hup`. It reads everything up to the NUL terminator (`IFS='' read -rd '' -u $1 suggestion`), then invokes `zle autosuggest-suggest -- "$suggestion"` to display the suggestion. Closes the read end of the pipe with `builtin exec {1}<&-`. Always removes the `zle -F` handler and resets `_ZSH_AUTOSUGGEST_ASYNC_FD` to empty, even on error.

```zsh
_zsh_autosuggest_async_response() {
	emulate -L zsh

	local suggestion

	if [[ -z "$2" || "$2" == "hup" ]]; then
		# Read everything from the fd and give it as a suggestion
		IFS='' read -rd '' -u $1 suggestion
		zle autosuggest-suggest -- "$suggestion"

		# Close the fd
		builtin exec {1}<&-
	fi

	# Always remove the handler
	zle -F "$1"
	_ZSH_AUTOSUGGEST_ASYNC_FD=
}
```

--------------------------------

### completion strategy implementation

Source: https://github.com/zsh-users/zsh-autosuggestions/blob/master/_autodocs/api-reference/strategies.md

The core function _zsh_autosuggest_strategy_completion that handles the logic for fetching completions via zpty. It includes early-return checks for the completion system, zpty module availability, and ignore patterns.

```zsh
_zsh_autosuggest_strategy_completion() {
	# Reset options to defaults and enable LOCAL_OPTIONS
	emulate -L zsh

	# Enable extended glob for completion ignore pattern
	setopt EXTENDED_GLOB

	typeset -g suggestion
	local line REPLY

	# Exit if we don't have completions
	whence compdef >/dev/null || return

	# Exit if we don't have zpty
	zmodload zsh/zpty 2>/dev/null || return

	# Exit if our search string matches the ignore pattern
	[[ -n "$ZSH_AUTOSUGGEST_COMPLETION_IGNORE" ]] && [[ "$1" == $~ZSH_AUTOSUGGEST_COMPLETION_IGNORE ]] && return

	# Zle will be inactive if we are in async mode
	if zle; then
		zpty $ZSH_AUTOSUGGEST_COMPLETIONS_PTY_NAME _zsh_autosuggest_capture_completion_sync
	else
		zpty $ZSH_AUTOSUGGEST_COMPLETIONS_PTY_NAME _zsh_autosuggest_capture_completion_async "$1"
		zpty -w $ZSH_AUTOSUGGEST_COMPLETIONS_PTY_NAME $'\t'
	fi

	{
		# The completion result is surrounded by null bytes, so read the
		# content between the first two null bytes.
		zpty -r $ZSH_AUTOSUGGEST_COMPLETIONS_PTY_NAME line '*'$'\0''*'$'\0'

		# Extract the suggestion from between the null bytes.  On older
		# versions of zsh (older than 5.3), we sometimes get extra bytes after
		# the second null byte, so trim those off the end.
		# See http://www.zsh.org/mla/workers/2015/msg03290.html
		suggestion="${${(@0)line}[2]}"
	} always {
		# Destroy the pty
		zpty -d $ZSH_AUTOSUGGEST_COMPLETIONS_PTY_NAME
	}
}
```
Tokens:
Raw