In zsh, pressing Tab after a command that must query a slow source — a package index or a remote inventory — freezes the prompt for a second or two each time. How would you find out where the time goes, and what does zsh's completion system offer to fix it?

## Split the problem before you fix it "zsh is slow" collapses two very different costs, and the fix for one does nothing for the other. - **Per-shell cost** is paid once at startup, when `compinit` scans `fpath` and rebuilds its dump file. It shows up as a slow *new terminal*, not a slow Tab. - **Per-completion cost** is paid every time you press Tab against a particular command. It shows up as a frozen prompt on that command and nowhere else. The question above is squarely the second. The diagnostic is simple: does the delay follow the *command* or the *shell*? If Tab is instant for `cd` and slow only for the one tool, the completion function for that tool is doing work. ## Confirming where the time goes Completion functions generate candidates by calling something — usually a subprocess. Run that thing by hand and time it: ```bash time mytool list-remote-things >/dev/null ``` If that alone takes a second, the completion cannot be faster than a second, and no amount of zstyle tuning will change it — the fix has to be caching or a cheaper source. You can also see which function is responsible: `echo $_comps[mytool]` names it, and reading its body shows what it shells out to. For per-call timing inside the shell, running the candidate-producing command under `time` is more honest than guessing from feel. ## The completion cache compsys ships a cache for precisely this situation. It is opt-in on both sides: - The **completion function** must be written to use it, calling `_cache_invalid` to ask whether the stored data is stale, `_retrieve_cache` to load it and `_store_cache` to save it. Many shipped completions for package managers and similar slow sources already do. - The **user** must enable it: ```bash zstyle ':completion:*' use-cache on zstyle ':completion:*' cache-path "${XDG_CACHE_HOME:-$HOME/.cache}/zsh/zcompcache" ``` `use-cache` switches the mechanism on; `cache-path` says where the files go, and setting it explicitly keeps a pile of cache files out of your home directory. Once enabled, the first Tab pays the full query cost and writes the result; subsequent completions read the file. ## Controlling staleness A cache that never expires eventually offers candidates that no longer exist, which is worse than being slow. The `cache-policy` style names a function that zsh calls to decide whether to rebuild: ```bash _my_cache_policy() { local -a oldp oldp=( "$1"(Nm+1) ) (( $#oldp )) } zstyle ':completion:*' cache-policy _my_cache_policy ``` The policy function receives the cache file's path as `$1` and returns success when the cache should be regenerated. The glob qualifier `(Nm+1)` matches the file only if it was modified more than one day ago — `N` makes a non-match expand to nothing rather than erroring — so the array is non-empty exactly when the cache is a day old. That is the idiomatic zsh way to write "expire after a day", and the policy is the piece you almost always want to set yourself, because the sensible expiry is a property of your data, not of the completion function. ## When caching is not available If the function does not implement the cache protocol, you have three honest options. Scope the expensive completer away from where you do not need it, using a narrower zstyle context so it never runs for arguments where the candidates do not matter. Replace the function with your own that queries a cheap local source — a file your tooling refreshes on a schedule — instead of the live one. Or accept the cost, and make sure the query itself has a short timeout so a network hiccup does not hang the prompt indefinitely, which is the failure mode people actually complain about. ## The related startup cost While you are there, it is worth knowing the other side: a very large `fpath` makes `compinit` slower on every new shell, because it stats every candidate file. `compinit -C` skips the check for new or changed completion functions and reuses the dump as-is, trading discovery of newly installed completions for startup speed. That is a real trade — after installing anything that ships completions you must remove the dump and re-run `compinit` yourself — but on a machine where new tools appear rarely and terminals are opened constantly, it is the right one.