radleylewis/zsh: a minimal zsh config with its own plugin manager

What radleylewis/zsh actually installs

This is a zsh configuration, not a shell. It assumes zsh is already on the machine and replaces the contents of your config directory with a set of files: .zshenv, .zshrc, aliases.zsh, bindings.zsh, fzf.zsh, plugins.zsh, prompt.zsh and starship.toml. The README describes it as "Powerful but tastefully minimal zsh configuration", and the file list backs that up. There is no theme system, no plugin registry and no configuration DSL. If you want to change a keybinding, you edit bindings.zsh.

The intended audience is someone who already uses zsh and has opinions about it. The config leans on external tools rather than reimplementing them: eza for directory listings, bat for file viewing, fd for finding files, ripgrep for searching, fzf for fuzzy selection, zoxide for directory jumping and starship for the prompt. On Arch and macOS these come from a single package manager command. On Ubuntu the README splits them: some from apt, zoxide and starship from their own install scripts.

The dependency list is the real scope statement. If you are not already using fzf, fd and starship, this config is asking you to adopt seven tools before it does anything for you.

How the config loads and where plugins come from

The setup uses ZDOTDIR rather than symlinking files into $HOME. The README instructs you to add a block to /etc/zsh/zshenv that exports XDG_CONFIG_HOME to $HOME/.config if it is unset, then exports ZDOTDIR to $XDG_CONFIG_HOME/zsh if that directory exists. Because zshenv runs for every zsh invocation, including non-interactive ones, the check on the directory's existence matters: if the clone is missing, ZDOTDIR stays unset and zsh falls back to its normal behaviour.

The repository is cloned directly to ~/.config/zsh, so the working tree is the config directory. That is why the plugin directory is $ZDOTDIR/plugins/ and why the README tells you to create ~/.local/state/zsh for history and ~/.cache/zsh for the completion cache before starting a shell.

Plugins are handled without a third-party manager. According to the README, plugins are cloned into $ZDOTDIR/plugins/ on first launch by a built-in plugin manager, and the four are fast-syntax-highlighting, zsh-autosuggestions, zsh-history-substring-search and zsh-vi-mode. Updating them is a single command, zplugin-update. That is the whole lifecycle: clone on first launch, update on demand. There is no lockfile, so the README does not document how to pin a plugin to a specific revision, and it does not describe what happens if a clone fails partway through.

Installing radleylewis/zsh and starting a first shell

Install the dependencies for your platform first. On Arch the README gives one command covering all seven tools.

paru -S zsh neovim eza bat fd fzf zoxide starship ripgrep

Ubuntu needs two extra steps because zoxide and starship are not in the apt list, and because Ubuntu renames two of the binaries.

sudo apt install zsh neovim eza bat fd-find fzf ripgrep
curl -sSfL https://raw.githubusercontent.com/ajeetdsouza/zoxide/main/install.sh | sh
curl -sS https://starship.rs/install.sh | sh
ln -s $(which batcat) ~/.local/bin/bat
ln -s $(which fdfind) ~/.local/bin/fd

Those symlinks are not cosmetic. The config calls bat and fd by those names, so without them the relevant bindings and aliases will not resolve. macOS is a single brew install line covering the same set.

Clone the repository into the config directory, then add the ZDOTDIR block to /etc/zsh/zshenv.

git clone https://github.com/radleylewis/zsh ~/.config/zsh
mkdir -p ~/.local/state/zsh
mkdir -p ~/.cache/zsh
chsh -s $(which zsh)

The mkdir commands create the history and completion cache directories the README lists as required. After chsh, open a new terminal. On first launch the plugin manager clones the four plugins; you should see the plugins directory appear under ~/.config/zsh/. If you are on Ubuntu, install a Nerd Font before judging the prompt, since starship.toml is loaded through STARSHIP_CONFIG in .zshenv and the README states a Nerd Font is required.

Keybindings and what fzf is wired to

The bindings table is where the config earns its keep. Ctrl+R is fuzzy history search through fzf. Ctrl+T is fuzzy file search that includes hidden files, using fzf plus fd. Ctrl+F is the same search excluding hidden files. Up and down arrows do prefix-based history search rather than plain history walking, and Ctrl+\ toggles autosuggestions on and off. Ctrl+left and Ctrl+right move by word.

The split between Ctrl+T and Ctrl+F is a deliberate choice worth noting. Most fzf integrations give you one file-search binding and a flag to toggle hidden files. Here the toggle is baked into two separate keys, which is faster to use but means you are committing two bindings to the same job. If you already have muscle memory for one of them, expect to rebind.

The Ctrl+\ toggle for autosuggestions is less common than the rest. It lets you silence the inline grey suggestions without editing plugins.zsh and restarting the shell, which is useful when the suggestions are pulling from a history file that has accumulated noise. The README does not say whether the toggle persists across sessions, so treat it as a per-session switch until you check plugins.zsh yourself.

Where this config gets in your way

The /etc/zsh/zshenv step is the sharpest edge. It is a system-wide file, it requires root to edit, and on macOS it does not exist by default, so the README's instruction only maps cleanly onto Linux. Putting a ZDOTDIR export there affects every user on the machine, not just you. A per-user alternative exists in zsh, but this README does not mention it, and the stated path is the one you are told to take.

The plugin manager is the second limitation. It clones from GitHub on first launch, so the first shell after installation needs network access and will be slow. There are no releases in the repository and no lockfile, so plugin versions are whatever the upstream default branch was at clone time. The README documents zplugin-update for pulling new commits but says nothing about rollback, pinning or what happens when a plugin's default branch changes shape. If you need reproducible shell environments across machines, this design works against you.

The dependency surface is the third. Seven external binaries have to be present and named correctly. The Ubuntu symlink workaround is documented, but it is a workaround: batcat and fdfind are the real package contents, and anything that resolves those names directly will behave differently from the aliases this config sets up. None of this is hidden, but it does mean the config is only minimal in the sense that the repository is small. The environment it assumes is not.

How it compares to oh-my-zsh and a plain zshrc

The obvious alternative is oh-my-zsh. The difference is in what each one manages. oh-my-zsh ships a framework: a large catalogue of plugins and themes, a loader that sources them by name, and an update mechanism for the framework itself. radleylewis/zsh ships four plugins, hardcoded by name, cloned by a script in the repository. There is no theme layer at all; the prompt is starship, configured by starship.toml in the same directory, and starship is a separate binary with its own configuration format.

That trade is real in both directions. With oh-my-zsh you get discovery and a large community of plugins, at the cost of a startup path that sources a lot of code you did not ask for. With this config you get a small, readable set of files and a first-launch clone, at the cost of doing your own plugin management the moment you want a fifth plugin. The README does not describe how to add one, so that is a gap you would fill by reading plugins.zsh.

The other alternative is no config at all: a hand-written .zshrc with the same tools sourced manually. That gives you complete control and no clone step. What you lose is the assembled bindings, the fzf integration and the starship wiring, which is exactly the part that takes an afternoon to get right. This repository is a reasonable middle point between a framework and a blank file, provided you accept its dependency list.

Maintenance, licence and upgrade cost

The repository is not archived, and the last push was on 2026-08-15. There are no releases, so there is no version to pin against; the unit of upgrade is the commit on main. Upgrading your copy means pulling the repository, and the README does not document a merge strategy for local edits. If you modify bindings.zsh or aliases.zsh, expect to resolve conflicts on every pull. The plugin side is separate: zplugin-update pulls new commits for the four plugins independently of the config itself.

The licence is MIT. That is permissive: you can copy the files into your own dotfiles repository, modify them and redistribute them, provided the copyright notice and permission notice are kept. The repository contains a LICENSE file at the top level, which is where those terms live. This is a description of the licence text, not legal advice; if you are redistributing the config inside a product or a company-wide dotfiles repo, read the LICENSE file and your own policy.

The practical maintenance cost is the dependency list. Every one of the seven tools moves on its own schedule, and the Ubuntu symlink workaround is the kind of thing that breaks quietly when a package renames a binary. That is the part of this setup most likely to need attention, and it is not something the repository can pin for you.

Editorial conclusion

Adopt radleylewis/zsh if you already live in zsh and want syntax highlighting, autosuggestions, prefix history search and a starship prompt without pulling in oh-my-zsh or a separate plugin manager. Do not adopt it if you want a framework with themes, a large plugin catalogue or per-plugin configuration, or if you cannot install a Nerd Font, because the prompt will render broken glyphs without one. Before you commit, verify two things: that a new interactive shell actually clones the four plugins into $ZDOTDIR/plugins/ on a machine with network access, and that Ctrl+R, Ctrl+T and Ctrl+F behave as the keybinding table describes once fzf and fd are on PATH. The Ubuntu path is the one to check hardest, since bat and fd arrive as batcat and fdfind and the README relies on symlinks in ~/.local/bin to bridge the gap.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. radleylewis/zsh on GitHub
4. README