A lightweight, fast, and reproducible plugin manager for zsh.
Made with 🐭 & 🦀 — no magic, no heavy frameworks.

• 🚀 Simple setup
  • Install with a single curl line
  • Just add one eval line in .zshrc to start using it
• ⚙️ Configurable and reproducible
  • Simple TOML-based configuration
  • Automatic plugin load order control
• 🐙 GitHub integration
  • Fetches plugins from GitHub repositories
  • Supports branches, tags, and commits
  • Handles Git submodules automatically
• ⚡️ Lightweight and fast
  • Parallel plugin sync
  • Built in Rust 🦀
• 🔄 Seamless updates
  • Self-upgrade
  • Plugin sync

curl -fsSL https://raw.githubusercontent.com/gotokazuki/rat-zsh/main/install.zsh | zsh

This installs $(rz home)/bin/rz.
(Default install location is $XDG_CONFIG_HOME/.rz. If not set, it falls back to $HOME/.rz.)

Add the following line to your .zshrc:

eval "$("${XDG_CONFIG_HOME:-$HOME}"/.rz/bin/rz init)"

Write your plugin configuration in $(rz home)/config.toml.
A sample file will be created on the first install.

[[plugins]]
source = "github"
repo = "zsh-users/zsh-autosuggestions"
type = "source"
file = "zsh-autosuggestions.zsh"

[[plugins]]
source = "github"
repo = "zsh-users/zsh-completions"
type = "fpath"
fpath_dirs = ["src"]

[[plugins]]
source = "github"
repo = "zsh-users/zsh-syntax-highlighting"
type = "source"
file = "zsh-syntax-highlighting.zsh"

[[plugins]]
source = "github"
repo = "zsh-users/zsh-history-substring-search"
type = "source"
file = "zsh-history-substring-search.zsh"

[[plugins]]
source = "github"
repo = "olets/zsh-abbr"
type = "source"
file = "zsh-abbr.zsh"

[[plugins]]
source = "github"
repo = "gotokazuki/rat-zsh"
type = "fpath"
fpath_dirs = ["contrib/completions/zsh"]

[[plugins]]
source = "github"
repo = "Aloxaf/fzf-tab"
type = "source"
file = "fzf-tab.plugin.zsh"
requires = ["fzf"]

Some plugins should only load when tools like fzf or peco are available.
You can declare such requirements using the requires field:

[[plugins]]
source = "github"
repo = "Aloxaf/fzf-tab"
type = "source"
file = "fzf-tab.plugin.zsh"
requires = ["fzf"]

Behavior:

• If all commands listed in requires exist in $PATH, Rat Zsh will sync and load the plugin normally.
• If any required command is missing, the plugin will be skipped entirely:
  • It is not cloned or updated
  • No symlink is placed in $(rz home)/plugins/
  • It will not be loaded by rz init

Example skip message:

skip plugin fzf-tab: missing required commands ["fzf"]

This allows conditional, environment-dependent plugin activation without modifying the config file.

Some plugins (like zsh-completions or rat-zsh itself) include completion functions in nested directories.
You can explicitly define which directories should be added to Zsh’s $fpath:

[[plugins]]
source = "github"
repo = "gotokazuki/rat-zsh"
type = "fpath"
fpath_dirs = ["contrib/completions/zsh"]

[[plugins]]
source = "github"
repo = "zsh-users/zsh-completions"
type = "fpath"
fpath_dirs = ["src"]

When you run rz list, these appear like:

fpath
- gotokazuki/rat-zsh (github) [fpath: contrib/completions/zsh] @main (4243bb3)
- zsh-users/zsh-completions (github) [fpath: src] @master (173a14c)

Some repositories provide multiple plugins (e.g. ohmyzsh/ohmyzsh).
In such cases you must specify the file and a unique name so they don’t overwrite each other:

[[plugins]]
source = "github"
repo = "ohmyzsh/ohmyzsh"
type = "source"
file = "lib/clipboard.zsh"
name = "clipboard"

[[plugins]]
source = "github"
repo = "ohmyzsh/ohmyzsh"
type = "source"
file = "plugins/copypath/copypath.plugin.zsh"
name = "copypath"

In this example:

• file selects the plugin file inside the repository.
• name defines how it will appear in $(rz home)/plugins/ and in the log messages.

You can use rev to pin a plugin to a specific version (tag or branch).
This ensures reproducible environments and avoids unexpected updates.

# Pin to a tag
[[plugins]]
source = "github"
repo = "zsh-users/zsh-autosuggestions"
rev = "v0.7.0"
type = "source"
file = "zsh-autosuggestions.zsh"

# Pin to a branch
[[plugins]]
source = "github"
repo = "zsh-users/zsh-completions"
rev = "develop"
type = "fpath"
fpath_dirs = ["src"]

• If rev is not specified, the plugin is synced to the default branch (usually main or master).
• When rev is specified, Rat Zsh checks out that branch or tag after cloning or fetching.
• Tags are checked out in a detached state.
• Branches are checked out in an attached state and will track updates.

By default, Rat Zsh loads plugins in the following order:

This order is enforced automatically — you don’t need to configure it manually.

To see the actual order on your system:

rz list

Example output:

Source order
- olets/zsh-abbr (github) [source] @main (13b34cd)
- zsh-users/zsh-history-substring-search (github) [source] @master (87ce96b)
- zsh-users/zsh-autosuggestions (github) [source] @master (85919cd)
- zsh-users/zsh-syntax-highlighting (github) [source] @master (5eb677b)

fpath
- gotokazuki/rat-zsh (github) [fpath: contrib/completions/zsh] @main (4243bb3)
- zsh-users/zsh-completions (github) [fpath: src] @master (173a14c)

rz init     # Print initialization code for .zshrc
rz config   # Open the configuration file
rz sync     # Clone/update plugins defined in config.toml
rz upgrade  # Update rat-zsh itself to the latest release
rz list     # Show plugins in the effective load order with source/type metadata
rz home     # Show the rz home directory

You can open the configuration file using the rz config command.
It respects the EDITOR environment variable (defaults to vim if unset).

# Open with code, nano, etc.
EDITOR=code rz config

You can check whether attached plugins have upstream updates by using the --check-update (-u) option with rz list.

rz list -u

When this option is specified, Rat Zsh will access Git repositories and display additional status indicators at the end of each plugin entry.

• These symbols are shown only for plugins attached to a branch.
• Plugins pinned to a specific commit or tag do not track upstream changes. In such cases, only * (dirty working tree) may be shown.
• Symbols are displayed in color when output is connected to a TTY.

Source order
- Aloxaf/fzf-tab (github) [source] @master (fac1451) ↓3/↑
- zsh-users/zsh-autosuggestions (github) [source] @master (85919cd) ↓/↑2 *
- zsh-users/zsh-syntax-highlighting (github) [source] @master (5eb677b) ↓/↑

fpath
- gotokazuki/rat-zsh (github) [fpath: contrib/completions/zsh] @main (29e2a7b) ↓/↑ *

Update Rat Zsh itself:

rz upgrade

Update plugins:

rz sync

rm -rf "$(rz home)"

Then remove the line eval "$("${XDG_CONFIG_HOME:-$HOME}/.rz/bin/rz" init)" from .zshrc.

By default, zsh-autosuggestions rebinds zle widgets before every prompt,
which may slow down input responsiveness in some environments.

Add the following environment variable before rz init in your .zshrc
to disable automatic rebinding and improve performance:

# .zshrc
export ZSH_AUTOSUGGEST_MANUAL_REBIND=1
eval "$("${XDG_CONFIG_HOME:-$HOME}/.rz/bin/rz" init)"

• Effect: Skips redundant processing at every prompt, resulting in a snappier shell.
• Note: If you add plugins or change key bindings later, you may need to run zle autosuggest-start manually.
• Especially effective when zsh-autosuggestions is loaded last (rat-zsh ensures this automatically).

MIT License. See LICENSE for details.