zsh4humans: a finished Zsh configuration instead of a starter kit

Read the three warnings at the top first

The README does not open with a feature list. It opens with three bold lines: the project has very limited support, no new features are in the works, and most bugs will go unfixed. That framing is unusual and worth taking at face value, because it changes what the project is. zsh4humans is a configuration someone built for themselves, finished and handed over, not a distribution with a roadmap.

That matters for the maintenance question more than any date. The last push on the default branch was 2026-05-01, so the repository is not dormant in the strict sense. But there is no version history to speak of: the platform release list is empty, and the tree holds four files, LICENSE, README.md, changelog.md and tips.md. The substantive configuration is not in those four files either. It arrives through the installer.

The installation command names the branch explicitly.

if command -v curl >/dev/null 2>&1; then
  sh -c "$(curl -fsSL https://raw.githubusercontent.com/romkatv/zsh4humans/v5/install)"
else
  sh -c "$(wget -O- https://raw.githubusercontent.com/romkatv/zsh4humans/v5/install)"
fi

That URL points at a v5 ref, while the repository default branch is master. Both are true at once, and the practical consequence is that the code you run is whatever lives on that ref rather than whatever you see when you browse the repository root. If you want to know what a specific setup contains, read the v5 ref, not master.

What the installer does and what it refuses to need

Run the command in bash, zsh or sh. According to the README the installer backs up your existing Zsh startup files, writes new ones, installs everything the configuration depends on, starts a new shell, and configures that shell as your login shell. It asks for confirmation at every step.

The dependency list is short by design: curl or wget, and nothing else. No git, no zsh itself, no sudo. The README states this twice, in the feature list and again in the installation section, and it is the single most distinguishing constraint in the project. Most dotfile managers require git to clone and a shell that already exists. This one pipes a script from a versioned URL and does the work itself.

That design has a cost that follows directly from it. A curl-to-shell installer has no package integrity story and no visible diff before execution, because the confirmation steps happen inside a script you have not read. The mitigation the project offers is that you can look at the script at that URL before running it, which is a real option precisely because there is a stable ref to read. Read it.

There is also a Docker path, which is the safest way to see the configuration without touching your own startup files at all. Two images are documented, one Alpine and one Ubuntu, and in both cases the container is disposable: the README says you can install extra software, change the filesystem freely, and the image is deleted when you exit Zsh.

The four plugins you actually get

The README credits four upstream projects by link, and it is worth naming them because they are the substance of the configuration.

Syntax highlighting on the command line comes from zsh-syntax-highlighting. Autosuggestions come from zsh-autosuggestions, and the README describes the interaction in detail: any key binding that moves the cursor can accept part of a suggestion, so moving one word right takes that word, and the whole suggestion is accepted with Alt+M or Option+M without moving the cursor.

Command completion has two sources. Most completion functions ship with Zsh itself, and the rest are contributed by zsh-completions. When a completion is ambiguous the config starts fzf automatically, and the README documents Ctrl+Space to select more than one candidate and Ctrl+A to take all of them.

The prompt is Powerlevel10k, driven through a built-in configuration wizard. The features list links the author's own zsh-bench work for the startup speed claim rather than publishing numbers, so treat speed as a design goal of the setup rather than a figure you can check.

What is not there is the point. There is no plugin manager in the list, no theme framework, and no curated library of hundreds of plugins. The related search data for this project returns Zimfw, OMZP and Zinit, which are the plugin managers people compare against this setup, and zsh4humans is deliberately on the other side of that line.

History search and fzf query syntax you will need on day one

History is the part people notice first. Pressing Up or Down fetches commands from history that contain what you have already typed, so typing grep and pressing Up surfaces the last grep you ran. Ctrl+R opens fzf over the whole history. The README points at zsh-bench for the speed claim rather than publishing numbers, so treat that as a design goal rather than a measurement.

Several interface elements run on fzf, and the query syntax is the part that pays off. Tokens are space delimited and each one is a different match type.

^music .mp3$ sbtrkt !fire

In that example, a leading caret is a prefix match, a trailing dollar sign is a suffix match, a leading exclamation mark inverts the match, and anything else is a substring. A single vertical bar is an or operator, so the following matches entries starting with core and ending in any of three extensions.

^core go$ | rb$ | py$

This syntax is fzf own, not something zsh4humans invented, and the README defers to the fzf homepage for the full grammar. Worth knowing before you conclude the tool is awkward: the query language you have to learn belongs to a separate project with its own documentation.

SSH teleportation and shared history across hosts

The features list claims two things about remote hosts that are unusual enough to be the reason some people use this configuration. The complete shell environment can be teleported to the remote host when you connect over ssh, and command history can be shared across different hosts, so history from a session on one machine can be available inside a session on another and on your local machine.

Both claims are stated as features. Neither gets its own section in the README beyond a heading with an asciinema recording embedded underneath it, and the table of contents stops there, which is where the documentation thinness the README warns about becomes concrete. The remote side needs nothing installed: the README repeats that no git, zsh or sudo is required on the remote host, which is the same constraint as the local install and the same unusual selling point.

Read the customization section before you rely on any of this. The README says there is no list of the configuration options the project recognizes and no description of what those options do, and that Zsh for Humans has very little documentation. In practice the options are discovered by reading the generated startup files after installation. For a personal machine that is a reasonable trade. For a machine a team shares, it is not, because there is no place to look up what a given key means.

Where this is the wrong tool

The README names one exclusion directly: this is not a good choice for users who prefer vi bindings in their shell. That is a stated design decision rather than an accident, since the whole configuration is built around accepting suggestions with cursor movement keys, and vi mode users live in a modal world where the same keys mean something else.

The second exclusion is anyone who wants to extend it. There are no new features in the works by the author own statement, so a request for one will not be met. There is no plugin interface either. If your workflow depends on a plugin that is not in the list of four, this configuration has no way to add it short of writing your own Zsh.

The third is teams. Because documentation is thin, configuration options are unlisted, and support is limited, onboarding a colleague means walking them through a system neither of you wrote documentation for. A dotfiles repository you control, with commits you can read and a plugin manager you understand, costs more to set up and gives you a system whose behavior you can look up. For one person on one laptop, zsh4humans is faster to that outcome than writing it yourself, which is the trade the author is offering.

Editorial conclusion

Adopt zsh4humans if you want a working shell this afternoon and do not want to assemble plugins yourself, and accept that every key binding after installation is yours to own. Do not adopt it if you need vi bindings, if you intend to file issues expecting fixes, or if your team needs documented configuration options, because the README states there is no list of them. Before you commit a machine, confirm the version line: the installer fetches from a v5 branch while the default branch is master, so what you get depends on that branch and not on the tree you see on the repository root.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. README
4. romkatv/zsh4humans on GitHub