zsh-autocomplete: real-time type-ahead completion for Zsh

What zsh-autocomplete changes about typing on the command line

Stock Zsh completion is on demand. You type a partial command, press Tab, and the completion system answers. zsh-autocomplete inverts that: the README says available completions are listed automatically while you type, with no keyboard shortcut, and that Tab inserts the top completion while the down arrow selects a different one. The plugin also configures Zsh's completion system out of the box, so it is not only a UI layer over an existing setup.

The audience is people who live in an interactive shell and find Tab-then-read slow. It is not a scripting aid. Nothing here changes how non-interactive shells behave, and the README frames the whole feature set around the command line: multi-line history search, completion of recent directories, and a documented keyboard shortcut table. If you mostly run scripts and rarely type commands by hand, the payoff is small.

How the async completion pipeline is wired

The repository layout shows the split: a top-level zsh-autocomplete.plugin.zsh entry point, a Functions/ directory, a Completions/ directory, and a Tests/ directory driven by run-tests.zsh and a clitest submodule. The plugin file is what you source; the functions and completion definitions behind it are loaded from those directories.

The asynchronous part is what the topics list calls non-blocking: completion candidates are gathered without freezing the prompt, which is why results can appear as you type rather than after a keypress. The README does not describe the internal scheduling, so treat the exact mechanism as undocumented. What it does document is the configuration surface, in a separate CONFIGURATION.md, including a section on reassigning keys with bindkey. That file is where behavior changes belong, not in the README.

One consequence of the design is worth stating plainly: because the plugin takes over completion setup, it competes with anything else that also wants to own that ground. The README's own troubleshooting section points at a bug report template rather than at a compatibility matrix, so conflicts surface as symptoms, not as a documented list.

Installing zsh-autocomplete and completing a first command

The README offers two routes. Package managers get you releases: Homebrew, Nix, pacman, Plumage, and Portage (as app-shells/zsh-autocomplete). For the latest commit on main, you use the AUR package zsh-autocomplete-git, a Zsh plugin manager, or a direct clone. The clone command from the README is:

git clone --depth 1 -- https://github.com/marlonrichert/zsh-autocomplete.git

Then edit .zshrc. Two changes matter. Remove any calls to compinit, and add the source line near the top, before any calls to compdef:

source /path/to/zsh-autocomplete/zsh-autocomplete.plugin.zsh

Platform notes from the README: on Ubuntu add skip_global_compinit=1 to .zshenv, and on Nix set programs.zsh.enableCompletion = false; in home.nix. Restart the shell by opening a new tab or replacing the current shell:

exec zsh

After that, start typing a command and a partial argument. Completions should appear without pressing anything. Tab inserts the first one. To update a manual install, the README gives git -C ~autocomplete pull; otherwise use your package or plugin manager.

The compinit removal is the real adoption cost

The instruction to remove compinit is not a suggestion, and it is the step most likely to break an existing setup. Many dotfiles call compinit explicitly, sometimes with flags, and some frameworks do it for you. The README also warns about ordering: the source line goes before any compdef call. If another plugin defines completions early, you are now debugging load order rather than completion behavior.

Keybindings are the second friction point, and the README is direct about it: other plugins or scripts might override the bindings, and the fix is to change the order in which you source plugins or to run bindkey commands in your dotfiles after sourcing. Terminal support is uneven too. The README notes that not all keybindings might work depending on your terminal, that Alt may need to be Escape, Option or Meta, and that keys like PgDn and PgUp may require Shift or another modifier.

Uninstalling is documented as reverting your install actions and restarting the shell. There is no separate rollback command, and the README does not document a way to keep compinit and run this alongside it. If your environment cannot give up compinit, this is the wrong tool.

zsh-autocomplete vs zsh-autosuggestions: different problems

These two get compared constantly, and the comparison only makes sense once you separate the mechanisms. zsh-autocomplete lists candidates drawn from Zsh's completion system: commands, arguments, paths, and history entries through its history menu. zsh-autosuggestions, by contrast, is known for showing a single inline suggestion based on what you have already typed, usually from history. One presents a menu of options; the other proposes one continuation.

That difference decides the use case. If you want to discover what arguments a command accepts without knowing them in advance, the completion menu is the tool. If you want the exact command you ran last week to appear after a few characters, the inline suggestion is the tool. The README documents a history menu with its own keybindings (Ctrl+R to toggle history completion in the emacs keymap, Ctrl+P or Alt+Up to enter the history menu), so history is present here, but it is a menu you open, not an inline ghost text.

The same logic applies to fzf-tab and carapace: both are completion front ends with their own opinions about how candidates are gathered and displayed, and the README does not discuss either. Do not expect a compatibility statement.

Requirements, licence and what maintenance looks like

The README says the plugin is tested to work with Zsh 5.8 and newer, and that it should theoretically work with Zsh 5.5.1. The word theoretically is doing work there. If you are on an older distribution Zsh, upgrade first rather than debugging completion behavior on an untested version.

The licence is MIT, per the repository's LICENSE file. MIT is permissive: you can use, modify and redistribute the code, and the practical implication for a dotfiles repo is that vendoring or forking it is straightforward. That is a summary of the licence identifier, not legal advice; read LICENSE if the distinction matters to you.

On maintenance: the last push to the default branch was on 2026-09-13, and the most recent release is 26.08.04 from 2026-08-04, with 26.08.03 the day before. The repository is not archived. The README also links a sponsorship page, which is worth knowing if you depend on it in a team environment. Upgrade cost depends on how you installed it: a package manager or plugin manager handles it, and a manual clone needs the pull command above. There is no migration guide in the README, so a release that changes completion behavior would be discovered by using it.

Editorial conclusion

Adopt it if you want completions to appear while you type and you are willing to remove compinit from .zshrc and re-source plugins in the right order. Skip it if your setup already depends on compinit placement or you need suggestions from your own typed prefix, which is what zsh-autosuggestions does instead. Before installing, verify your Zsh version (5.8 and newer is what the README says is tested) and read CONFIGURATION.md, because the README does not document rollback beyond reverting your install steps.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. marlonrichert/zsh-autocomplete on GitHub
4. README
5. Releases