A lightweight ZSH framework. Sensible defaults, 356 plugins, fast startup.

Built-in themes match upstream Oh My ZSH (Unicode and Powerline where applicable). Prompt-facing plugins under plugins/ are normalized to plain ASCII by tools/ascii_cleanup.sh so they behave well on minimal terminals.

git clone <this-repo> /tmp/leanzsh
cp /tmp/leanzsh/zshrc ~/.zshrc
cp -r /tmp/leanzsh/zshconfig ~/.zshconfig

~/.zshrc           # Your shell config (edit this)
~/.zshconfig/      # Framework root ($ZSH)
  customzsh.sh     # Core loader
  lib/             # Built-in libraries (git, history, completion, etc.)
  plugins/         # 356 plugins
  themes/          # Prompt themes (robbyrussell, agnoster)

Edit ~/.zshrc:

ZSH_THEME="robbyrussell"   # default, minimal
ZSH_THEME="agnoster"       # Powerline-style segments (needs a patched font)

Edit the plugins array in ~/.zshrc:

plugins=(git docker kubectl fzf)

List available plugins:

ls ~/.zshconfig/plugins/

These go in ~/.zshrc before the source $ZSH/customzsh.sh line:

CASE_SENSITIVE="true"           # Case-sensitive completion
HYPHEN_INSENSITIVE="true"       # _ and - interchangeable in completion
DISABLE_AUTO_TITLE="true"       # Don't auto-set terminal title
ENABLE_CORRECTION="true"        # Command auto-correction
COMPLETION_WAITING_DOTS="true"  # Show dots during completion
HIST_STAMPS="yyyy-mm-dd"        # Timestamp format in history

Place your own plugins or lib overrides under $ZSH/custom/ (or set ZSH_CUSTOM to a different path):

~/.zshconfig/custom/
  plugins/my-plugin/my-plugin.plugin.zsh
  lib/git.zsh           # overrides the built-in lib/git.zsh
  themes/my.zsh-theme   # custom theme

Disable git prompt features on large repos:

cd /path/to/huge-repo
git config leanzsh.hide-status 1   # hide dirty/clean status
git config leanzsh.hide-dirty 1    # skip dirty check only
git config leanzsh.hide-info 1     # hide git info entirely

Upstream agnoster reads oh-my-zsh.hide-status; the copy shipped here uses leanzsh.hide-status so the same commands above apply.

Plugins that accept options use the :leanzsh: zstyle namespace. Add these to ~/.zshrc:

zstyle ':leanzsh:plugins:nvm' lazy yes
zstyle ':leanzsh:plugins:ssh-agent' agent-forwarding yes
zstyle ':leanzsh:plugins:docker' legacy-completion yes

One command does everything -- sync, rebrand, strip emoji, and test:

./tools/update.sh

Options:

./tools/update.sh --dry-run     # preview all changes, modify nothing
./tools/update.sh --skip-sync   # skip upstream sync (no network needed)
./tools/update.sh --skip-test   # skip the test suite at the end

update.sh runs four scripts in order. Here is exactly what each step does and why it is needed.

Keeps the local plugin set in lockstep with ohmyzsh/ohmyzsh.

1. Sparse-clone the upstream repo (plugins directory only, depth 1) into a temporary directory.
2. Compare the upstream and local plugin lists with comm.
3. Add any plugins that exist upstream but not locally (new plugins).
4. Update any existing plugins whose content has changed upstream (detected via diff -r). The local copy is replaced with the upstream version.
5. Remove any plugins that no longer exist upstream (deprecated).
6. Optionally run the rebrand pass (skipped when called from update.sh, which runs rebrand as its own step).

Flags: --dry-run (preview only), --no-rebrand (skip branding pass).

Replaces all Oh My ZSH identifiers with leanzsh equivalents so the codebase is self-consistent. Themes are never modified (they stay byte-identical to upstream).

1. Replace :omz: zstyle namespaces with :leanzsh:.
2. Replace oh-my-zsh.* git config keys with leanzsh.*.
3. Replace internal _omz_ / _OMZ_ function and variable prefixes with _leanzsh_ / _LEANZSH_.
4. Replace [oh-my-zsh] user-facing message prefixes with [leanzsh].
5. Replace public function names (omz_urlencode etc.) with their leanzsh_ equivalents, preserving backward-compat wrappers.
6. Replace branding in comments and documentation text.
7. Run a catch-all pass for any remaining _omz_ and _OMZ_ prefixes, skipping backward-compat wrapper lines.

GitHub URLs (github.com/ohmyzsh/...) are preserved. The script is idempotent -- running it on an already-rebranded codebase produces no changes.

Flags: --dry-run (preview only).

Replaces emoji and Unicode symbols with plain ASCII equivalents in plugins/ only. This ensures prompts render correctly on minimal terminals.

1. Replace git-status glyphs (✚ → +, ● → *, etc.).
2. Replace arrow symbols used for ahead/behind indicators (↑ → ^).
3. Replace special symbols (lightning, gear, flag, star, etc.).
4. Replace Powerline Private Use Area glyphs with pipe/at characters.
5. Replace Kubernetes and other domain-specific Unicode escapes.
6. Replace emoji in user-facing messages (lock, folder, skull, fire).

lib/ and themes/ are not touched. The script is idempotent.

Flags: --dry-run (preview only).

Validates the entire codebase after the above steps. Exits non-zero if any test fails.

1. Core structure — required files (customzsh.sh, all libs, themes) exist.
2. No OMZ references — no :omz:, oh-my-zsh.*, _omz_, _OMZ_, or Oh My Zsh branding in functional code (excluding themes and backward-compat wrappers). Also checks zshrc and plugins/.
3. Correct identifiers — leanzsh config keys, function names, zstyle namespaces, and async handlers are all present.
4. Backward compatibility — omz_urlencode, omz_urldecode, and omz_history aliases still work.
5. Dead code removal — OMZ-only functions (uninstall_oh_my_zsh, upgrade_oh_my_zsh) are gone.
6. Config defaults — ZSH_CUSTOM and ZSH_COMPDUMP have defaults.
7. Cross-reference consistency — functions that are called are actually defined, plugin-specific rebrands are verified.
8. Plugin inventory — count is >= 350, deprecated plugins removed, new plugins present, every plugin dir has an entry-point file.
9. ASCII safety — lib/ is fully ASCII; all plugin .zsh/.sh files are ASCII-clean.
10. README sanity — documents leanzsh namespaces and migration.
11. Rebrand idempotency — re-running rebrand.sh produces no changes.

The default zshrc sets these aliases. Add your own below them:

alias grep='grep --color=auto --exclude-dir={.bzr,CVS,.git,.hg,.svn,.idea,.tox}'

If you previously used Oh My ZSH:

Backward-compat aliases are provided so existing scripts continue to work.