CodeVetter · Repo Unpack evidence
ohmyzsh/ohmyzsh
github.com/ohmyzsh/ohmyzsh ↗ · 1142 files · 4.4 MB
Oh My Zsh is an open source, community-driven framework for managing your zsh configuration.
Overview
Oh My Zsh is a community-driven framework for managing zsh configuration: a user's .zshrc exports ZSH, ZSH_THEME and a plugins array, then sources oh-my-zsh.sh which wires up $fpath, runs compinit, and loads ~22 lib files, ~368 bundled plugins, and ~143 themes. It ships a self-updater that polls the GitHub API and re-pulls the repo via git, an `omz` CLI (lib/cli.zsh) that rewrites .zshrc to manage plugins/themes, and a curl|sh installer (tools/install.sh) that is deployed to install.ohmyz.sh via Vercel. Distinctive traits: everything is pure zsh sourced into the live shell, customization is layered through a $ZSH_CUSTOM shadow directory, and behavior is tunable via zstyle contexts under ':omz:...'.
System map
Oh My Zsh is a sourced shell framework, not a daemon: oh-my-zsh.sh is the single entrypoint sourced from ~/.zshrc and it orchestrates fpath setup, compinit, lib files, plugins, custom overrides, and the theme. Runtime state lives in $ZSH_CACHE_DIR (completion dump, .zsh-update epoch file, probe caches) and $ZSH/log (update.lock). External integrations are git (self-update via pull --rebase), the GitHub REST API (update check, PR label check), curl/wget/fetch, and chsh. CI is GitHub Actions: syntax checking, installer testing, a Vercel deploy of install.sh, vendored-dependency updates, and OpenSSF Scorecard.
- oh-my-zsh.sh is the sole runtime entrypoint, sourced from .zshrc after the user sets ZSH/ZSH_THEME/plugins; it aborts with a process-tree dump if loaded by a non-zsh shell and refuses non-zsh emulation modes.
- Three env vars define the layout: ZSH (repo dir, defaulting to the script's own dir), ZSH_CUSTOM (default $ZSH/custom, a gitignored shadow tree), and ZSH_CACHE_DIR (default $ZSH/cache, falling back to ${XDG_CACHE_HOME:-$HOME/.cache}/oh-my-zsh when unwritable).
- Before compinit, each name in the $plugins array is resolved by is_plugin() to $ZSH_CUSTOM/plugins/<name> or $ZSH/plugins/<name> (a dir containing <name>.plugin.zsh or _<name>) and prepended to $fpath.
- Completion init writes $ZSH_COMPDUMP (default ${ZDOTDIR:-$HOME}/.zcompdump-<SHORT_HOST>-<ZSH_VERSION>), deletes and rebuilds it when embedded '#omz revision'/'#omz fpath' metadata lines go stale, and zrecompile-compiles it under a .lock mkdir.
- _omz_source() implements the override layer: for each lib/plugins path it prefers $ZSH_CUSTOM/<path> over $ZSH/<path>, and honors 'zstyle :omz:lib:<name>|plugins:<name> aliases no' by snapshotting and restoring the alias tables around the source.
- Load order is fixed: all lib/*.zsh files, then each plugin's <name>.plugin.zsh, then every $ZSH_CUSTOM/*.zsh, then the theme resolved from $ZSH_CUSTOM, $ZSH_CUSTOM/themes, or $ZSH/themes.
- lib/cli.zsh defines the `omz` dispatcher: it maps argv[1] to functions named _omz::<command> (changelog, help, plugin, pr, reload, shop, theme, update, version) and registers a `_omz` compdef completer.
- Self-update is split across two files: tools/check_for_upgrade.sh is sourced at every shell start to gate and trigger updates, while tools/upgrade.sh does the actual `git pull --rebase $remote $branch` using per-repo git config keys oh-my-zsh.remote and oh-my-zsh.branch.
- tools/install.sh is a POSIX sh installer meant to be run via curl|sh: it does a manual `git init` + `git fetch --depth=1` into $ZSH, materializes .zshrc from templates/zshrc.zsh-template with a sed-substituted ZSH path, and optionally chsh's the login shell to zsh.
- The installer is deployed to install.ohmyz.sh by the installer.yml workflow: it copies tools/install.sh into .github/workflows/installer/ and runs `vc deploy --prod` against a Vercel project whose vercel.json rewrites '/' to '/install.sh'.
- lib/git.zsh wraps all prompt-time git calls in __git_prompt_git (GIT_OPTIONAL_LOCKS=0) and exposes git_prompt_info/git_prompt_status plus helpers like git_current_branch; lib/async_prompt.zsh provides an experimental fork-pipe-zle async framework that git.zsh registers into via _omz_register_handler.
- The repo vendors 368 plugin directories under plugins/ (each with <name>.plugin.zsh and usually a README.md; some only ship a _<name> completion file) and 143 *.zsh-theme files under themes/.
Feature catalog
User-facing surface = (a) the `omz` CLI with plugin/theme/update/pr/changelog subcommands, (b) a large catalog of plugins and themes enabled via zshrc variables, (c) lib features that reshape the interactive shell (directory stack aliases, history behavior, key bindings, completion tuning, clipboard helpers, terminal title/OSC7 integration, git prompt API), and (d) lifecycle tooling (install, upgrade, changelog, uninstall, diagnostics).
- `omz plugin enable|disable|info|list|load` manage the plugins array: enable/disable rewrite .zshrc with an awk program, back up to .zshrc.bck, syntax-check the result with `zsh -n`, and reload the shell; load sources a plugin for the current session only.
- `omz theme list|set|use` enumerate and switch themes; `set` rewrites the ZSH_THEME= line in .zshrc (or prepends one) with the same backup + `zsh -n` + rollback discipline as the plugin commands.
- `omz update` shells out to `zsh -f $ZSH/tools/upgrade.sh -i -v <mode> -c <days>`, writes LAST_EPOCH into $ZSH_CACHE_DIR/.zsh-update, removes the update lock, and execs a fresh zsh if HEAD changed.
- `omz pr test <N|URL>` fetches a pull request into branch ohmyzsh/pull-N, first querying api.github.com for the 'testers needed' label (node_id MDU6TGFiZWw4NzY1NTkwNA==) and requiring a typed 'yes' if the PR is unlabeled, then rebases onto master and spawns `zsh -l` for testing.
- `omz changelog` delegates to tools/changelog.sh, a Conventional-Commits parser that buckets subjects by type (feat/fix/perf/docs main; refactor/style/other grouped; chore/ci/etc ignored) and renders them per release.
- The git plugin (plugins/git/git.plugin.zsh) ships ~200 aliases plus functions like git_main_branch (probing main/trunk/mainline/default/stable/master then remote HEAD), git_develop_branch, and gbcopy (branch name to clipboard via clipcopy).
- ZSH_THEME='random' is implemented as a real theme file themes/random.zsh-theme: it gathers candidates from ZSH_THEME_RANDOM_CANDIDATES or the theme dirs minus ZSH_THEME_RANDOM_IGNORED, picks one with $RANDOM, sources it, and records it in $RANDOM_THEME.
- lib/directories.zsh enables auto_cd/auto_pushd and defines the `...`=`../..` global aliases, numeric `1..9`=`cd -N` aliases, `d` for the dir stack, and ls listing aliases (l, ll, la, lsa).
- lib/history.zsh replaces `history` with omz_history (supports -c clear with confirmation and HIST_STAMPS-driven date formats), sets HISTFILE=~/.zsh_history, floors HISTSIZE=50000/SAVEHIST=10000, and enables share_history/hist_verify.
- lib/completion.zsh configures the completer: matcher-list driven by CASE_SENSITIVE/HYPHEN_INSENSITIVE, menu select, use-cache into $ZSH_CACHE_DIR, ignored system users, COMPLETION_WAITING_DOTS spinner widget, and bashcompinit for bash completions.
- lib/termsupport.zsh auto-sets terminal/tab titles via title() on precmd/preexec (special-casing `fg` job resolution and sudo/ssh prefixes) and emits OSC 7 file://host/path cwd notifications via omz_termsupport_cwd, skipped under Emacs/SSH.
- lib/clipboard.zsh defines clipcopy/clippaste dispatching across pbcopy, cygwin, wl-copy, xsel, xclip, lemonade, doitclient, win32yank, and tmux depending on platform and WAYLAND_DISPLAY/DISPLAY/TMUX.
Data flow
Configuration flows inward from .zshrc variables (ZSH_THEME, plugins array, zstyle settings, DISABLE_* flags) which oh-my-zsh.sh reads while sourcing; state flows outward into $ZSH_CACHE_DIR (zcompdump, .zsh-update, probe/alias caches) and back into .zshrc itself when `omz` commands mutate it. Prompt rendering is the hot path: git status data moves from porcelain output through regex parsing into ZSH_THEME_* variables, either synchronously or through a forked async pipe read by a zle -F callback.
- Input boundary: .zshrc defines export ZSH, ZSH_THEME, plugins=(...) and optional zstyle ':omz:...' settings, then `source $ZSH/oh-my-zsh.sh` — the template file is generated by the installer via sed replacing the ZSH= line.
- Plugin data flow: $plugins names -> is_plugin() dir resolution -> dir prepended to $fpath -> <name>.plugin.zsh sourced via _omz_source, with $ZSH_CUSTOM/plugins shadowing $ZSH/plugins at both stages.
- Completion pipeline: plugin dirs + $ZSH_CACHE_DIR/completions enter $fpath, compaudit/compinit -i produce $ZSH_COMPDUMP, OMZ metadata comments are appended, and zrecompile emits $ZSH_COMPDUMP.zwc guarded by a mkdir lock.
- Update state lives in $ZSH_CACHE_DIR/.zsh-update (sourced to read LAST_EPOCH, EXIT_STATUS, ERROR) written by update_last_updated_file(); mutual exclusion is a mkdir on $ZSH/log/update.lock cleaned by an EXIT/INT/QUIT trap.
- Update-availability check: reads git config oh-my-zsh.remote/oh-my-zsh.branch, fetches the remote HEAD sha from api.github.com via curl/wget/fetch (2s timeout), then compares with local HEAD via `git merge-base`; non-GitHub remotes are assumed to have updates.
- Git prompt flow: __git_prompt_git runs `git rev-parse --git-dir --abbrev-ref HEAD` and `git status --porcelain -b`; _omz_git_prompt_status_match forces LC_ALL=C for regex parsing (workaround for REG_ILLSEQ on non-UTF-8 bytes); results map through ZSH_THEME_GIT_PROMPT_* variables into the prompt string.
- Async prompt flow: precmd hook _omz_async_request forks each registered handler writing to a pipe fd, stores fd/pid in _OMZ_ASYNC_FDS/_OMZ_ASYNC_PIDS, and zle -F triggers _omz_async_callback which stores output in _OMZ_ASYNC_OUTPUT[handler] and calls `zle .reset-prompt` only if it changed.
- .zshrc mutation flow (plugin enable/disable, theme set): awk program reads ${ZDOTDIR:-$HOME}/.zshrc -> writes .zshrc.new -> copies original to .zshrc.bck -> mv into place -> `zsh -n` syntax check -> on failure mv .zshrc.bck back -> _omz::reload execs a fresh zsh.
- Startup-cost caching: expensive probes are persisted in $ZSH_CACHE_DIR — grep alias flags (grep-alias), macOS scutil LocalHostName (localhostname, keyed by $HOST), and appearance command probes (appearance-probes, an associative array dumped via print -r).
- upgrade.sh normalizes legacy robbyrussell/oh-my-zsh remotes to ohmyzsh/ohmyzsh, stores the chosen remote in `git config oh-my-zsh.remote`, records pre-update HEAD in oh-my-zsh.lastVersion, and temporarily forces rebase.autoStash before restoring it.
- Terminal output boundary: termsupport precmd/preexec hooks emit OSC 0/1/2 title sequences and OSC 7 cwd notifications (percent-encoded via omz_urlencode) only when TERM/TERM_PROGRAM whitelists match and not inside Emacs or SSH.
- Installer data flow: env vars ZSH/ZDOTDIR/REPO/REMOTE/BRANCH/CHSH/RUNZSH/KEEP_ZSHRC drive behavior; git writes repo to $ZSH; existing .zshrc moves to .zshrc.pre-oh-my-zsh (older backups get datestamped); the old shell path is saved to ~/.shell.pre-oh-my-zsh for uninstall.sh to restore.
Behavior traces
Three flows matter most. Startup: .zshrc -> oh-my-zsh.sh guards -> env defaults -> check_for_upgrade -> fpath/compinit -> lib -> plugins -> custom -> theme. Update: startup hook -> epoch/frequency gates -> GitHub API compare -> upgrade.sh git rebase -> epoch write -> optional exec. Config mutation: omz subcommand -> awk rewrite of .zshrc -> zsh -n validation -> rollback or reload. Install is a fourth boundary: curl|sh -> git init/fetch -> .zshrc template -> chsh -> exec zsh.
- Startup sequence in order: ZSH_VERSION guard with omz_ptree diagnostics -> `emulate` mode check -> ZSH/ZSH_CUSTOM/ZSH_CACHE_DIR defaults -> mkdir cache/completions + fpath -> source tools/check_for_upgrade.sh -> plugin dirs into fpath -> SHORT_HOST -> compinit/zcompdump -> _omz_source each lib/*.zsh -> each plugin -> each $ZSH_CUSTOM/*.zsh -> theme -> LS_COLORS zstyle.
- Auto-update trace: check_for_upgrade.sh resolves zstyle ':omz:update' mode (legacy DISABLE_UPDATE_PROMPT/DISABLE_AUTO_UPDATE mapped to auto/disabled) -> bails on disabled/unwritable/non-tty -> sources .zsh-update and returns early inside the frequency window (default 13 days) -> handle_update takes update.lock -> is_update_available -> prompt ('Would you like to update? [Y/n]') or silent modes -> update_ohmyzsh runs upgrade.sh.
- background-alpha update mode registers _omz_bg_update on precmd which forks handle_update and installs _omz_bg_update_status to report EXIT_STATUS/ERROR from .zsh-update on a later prompt.
- upgrade.sh execution order: re-exec under zsh if needed -> cd $ZSH -> parse -v/-i/-c flags -> rewrite legacy robbyrussell remotes -> set core.eol/autocrlf/fsck/rebase.autoStash git config -> checkout update branch -> git pull --rebase (or cooldown path: fetch + find first FETCH_HEAD commit older than cooldown days + merge --ff-only) -> run changelog.sh if interactive -> restore previous HEAD and autoStash.
- Insecure-completion handling: unless ZSH_DISABLE_COMPFIX=true, compfix.zsh is sourced, compinit runs with -i to skip insecure dirs, and handle_completion_insecurities lists `compaudit` output with a chmod g-w,o-w fix hint.
- `omz plugin disable git` trace: omz -> _omz::plugin -> _omz::plugin::disable validates names against $plugins -> builds gsub() awk program -> awk .zshrc > .zshrc.new -> cp .zshrc .zshrc.bck -> mv .zshrc.new .zshrc -> `zsh -n` check -> rollback mv on syntax error -> _omz::reload execs ${ZSH_ARGZERO:-zsh} (with -l for login shells).
- Git prompt render trace (async default on zsh >= 5.0.6): precmd -> _defer_async_git_register checks whether $(git_prompt_info)/$(git_prompt_status) appear in PS1/RPROMPT/etc -> _omz_register_handler -> _omz_async_request forks _omz_git_prompt_info -> _omz_async_callback fills _OMZ_ASYNC_OUTPUT -> zle reset-prompt -> git_prompt_info stub echoes the cached output.
- Install trace: main() detects non-tty stdin -> forces RUNZSH=no CHSH=no OVERWRITE_CONFIRMATION=no -> setup_ohmyzsh (umask g-w,o-w; git init; core.eol=lf, autocrlf=false, zeroPaddedFilemode ignores; fetch --depth=1; checkout $BRANCH) -> setup_zshrc (backup, sed template) -> setup_shell (locate zsh in /etc/shells, save old shell, sudo chsh) -> print_success -> exec zsh -l.
- `omz pr test 123` trace: URL basename normalized -> digit check -> git symbolic-ref saves current branch -> remote list scanned for ohmyzsh/ohmyzsh -> curl api.github.com/repos/ohmyzsh/ohmyzsh/pulls/123 -> 'testers needed' label check (jq or grep on node_id) -> typed 'yes' gate if unlabeled -> git fetch refs/pull/123/head:ohmyzsh/pull-123 -> rebase onto master with commit.gpgsign temporarily disabled -> `zsh -l` test shell -> optional checkout back.
- Uninstall trace: uninstall_oh_my_zsh -> tools/uninstall.sh restores shell from ~/.shell.pre-oh-my-zsh via chsh, confirms, rm -rf ~/.oh-my-zsh, renames ~/.zshrc to .zshrc.omz-uninstalled-<timestamp>, and restores .zshrc.pre-oh-my-zsh.
Testing signals
Testing is thin for a project of this reach. CI (main.yml) does only `zsh -n` syntax checking over the entrypoint, lib files, plugin entrypoints/completions, and themes — no behavioral test runs. Real tests exist but are scattered and not wired into workflows: lib/tests/cli.test.zsh exercises the plugin-disable awk script, and a few plugins (alias-finder, dotenv) ship zunit suites. The installer gets its own matrix test on ubuntu+macos, and all workflows run step-security/harden-runner in audit mode.
- main.yml's only test step is a `zsh -n` syntax sweep over ./oh-my-zsh.sh, lib/*.zsh, plugins/*/*.plugin.zsh, plugins/*/_*, and themes/*.zsh-theme on ubuntu-latest; the job is gated on github.repository == 'ohmyzsh/ohmyzsh'.
- lib/tests/cli.test.zsh duplicates the plugin-disable awk program inline and tests it against oneline/multiline/mixed plugins=(...) formats, asserting both `zsh -n` validity and exact diff output via run_awk_and_test.
- The awk script tested by lib/tests/cli.test.zsh is a copy of the one embedded in _omz::plugin::disable in lib/cli.zsh, so the test validates a clone of the logic rather than the shipped code path. (inferred)
- Plugin-level tests exist in zunit format: plugins/alias-finder/tests/test_run.sh (@setup/@test/@assert blocks) and plugins/dotenv/tests/{basic-parsing,compatibility,security}.zunit.
- Neither the zunit suites nor cli.test.zsh are invoked by any workflow; grep of .github/workflows shows only the syntax-check job and the installer test, so these tests run only when a developer runs them manually. (inferred)
- installer.yml runs `sh ./tools/install.sh` on ubuntu-latest and macos-latest on pushes touching tools/install.sh, then deploys install.sh to Vercel (install.ohmyz.sh) on master via `vc deploy --prod` with VERCEL_* secrets.
- Every workflow pins actions by SHA and prepends step-security/harden-runner with egress-policy: audit; permissions are minimal (contents: read) except dependencies.yml which grants contents: write for pushing update branches.
- scorecard.yml runs OpenSSF Scorecard analysis weekly and on master pushes, uploading results to the code-scanning dashboard (security-events: write).
- dependencies.yml runs updater.py weekly: it reads .github/dependencies.yml entries (upstream repo/branch/pinned version + precopy/postcopy shell), fetches upstream releases, and opens/commits vendored-plugin updates authenticated as the ohmyzsh[bot] GitHub App.
- project.yml uses pull_request_target with an empty default permission set plus a GitHub App token to add new issues/PRs to the ohmyzsh org Project board and set Plugin/Theme fields.
- CONTRIBUTING.md mandates Conventional Commits (type(scope)!: subject) because tools/changelog.sh generates the user-facing changelog from commit subjects — so commit-message discipline is itself part of the test/release pipeline.
- No test covers oh-my-zsh.sh init order, compfix/compinit handling, upgrade.sh, check_for_upgrade.sh, or lib/git.zsh prompt parsing — the riskiest shell logic is verified only by the syntax sweep. (inferred)
Risk map
The dominant risks are supply-chain and self-modification: every user runs curl|sh installer code and an auto-updater that git-pulls new shell code into a live config; `omz` commands rewrite the user's .zshrc with awk; and 368 community plugins execute unchecked code at every shell start. Mitigations exist (compfix permission checks, PR-test label gating, .zshrc backups + syntax validation, hardened CI), but coverage of the critical paths is minimal.
- The documented install path is `sh -c "$(curl -fsSL .../tools/install.sh)"` — remote code executed with user privileges; the script then chsh's the login shell (via sudo when available) and execs zsh.
- install.sh resolves $HOME via `eval echo ~"$USER"` when HOME is unset — an acknowledged CWE-78-adjacent path that is only safe because $USER is first restricted to [alnum, _, ., -].
- Auto-update executes freshly fetched code: upgrade.sh does `git pull --rebase` on master and the new oh-my-zsh.sh/plugins run at next shell start; the 'cooldown' zstyle exists specifically to delay applying new commits as a supply-chain buffer.
- Every plugin file is arbitrary code sourced into every interactive shell; the only vetting is maintainer review, and `omz pr test` explicitly warns unlabeled PRs 'may contain malicious code' before fetching and running them.
- omz plugin/theme commands write directly into ${ZDOTDIR:-$HOME}/.zshrc via awk transformations; mitigations are the .zshrc.bck backup and the post-write `zsh -n` syntax check with automatic rollback, but a semantically-wrong-but-parseable edit would stick.
- compinit -i skips completion dirs that fail compaudit ownership/permission checks; users hitting this get a warning via handle_completion_insecurities — ZSH_DISABLE_COMPFIX=true bypasses the check entirely by switching to compinit -u.
- check_for_upgrade.sh's GitHub API call uses a 2s connect timeout and treats non-GitHub remotes as always-updateable; is_update_available returning 0 on merge-base failure assumes updates exist — fail-open rather than fail-closed.
- uninstall.sh runs `rm -rf ~/.oh-my-zsh` and `chsh` after a single y/N prompt, and install.sh's setup_shell runs `sudo chsh` — destructive/account-level operations driven by tty prompts that are bypassed only in unattended mode.
- update.lock is a stale-able mkdir lock under $ZSH/log: the code deletes locks older than a day, and the EXIT/INT/QUIT trap must return $ret correctly so Ctrl+C actually interrupts — a fragile bit of signal semantics the comments call out.
- Async prompt handler cancellation kills the process group only under MONITOR; without job control it can only TERM the direct child, and the file itself notes forked grandchildren 'may be orphaned and left behind'.
- lib/vcs_info.zsh exists specifically to %-quote hook_com fields before vcs_info hooks run — a workaround for CVE-2021-45444 where crafted branch/repo data could trigger command substitution in prompts on zsh 5.0.3-5.8.
- git.zsh documents real-world fragility: a =~ regex on non-UTF-8 git output aborted with REG_ILLSEQ (fixed via LC_ALL=C scoping), and async prompt is behind ':omz:alpha:lib:git' with 'force'/opt-out because of known issue reports; the CentOS-7 workaround carries a dated TODO.
Extension points
Oh My Zsh is built to be extended without editing upstream files: $ZSH_CUSTOM shadows every lib file, plugin, and theme; new plugins are just directories with a <name>.plugin.zsh or _<name> completion; new themes are *.zsh-theme files; behavior is tuned via zstyle contexts and env-var flags; and the `omz` CLI dispatches to _omz::<cmd> functions. Theme authors integrate through prompt-info functions and ZSH_THEME_* variables.
- $ZSH_CUSTOM is the primary extension root: files in $ZSH_CUSTOM/*.zsh load last (after lib and plugins), and $ZSH_CUSTOM/<path> shadows $ZSH/<path> inside _omz_source, letting users override any lib file or plugin without touching the repo.
- A plugin is any directory under plugins/ or $ZSH_CUSTOM/plugins/ containing <name>.plugin.zsh (sourced at load) or _<name> (a compinit completion); is_plugin() is the registry check and simply enabling the name in plugins=(...) wires it in.
- A theme is a *.zsh-theme file found in $ZSH_CUSTOM/, $ZSH_CUSTOM/themes/, or $ZSH/themes/ (search order); it typically sets PROMPT/RPROMPT and consumes ZSH_THEME_* styling variables plus *_prompt_info functions.
- zstyle contexts form a typed config API: ':omz:update' mode/frequency/cooldown/verbose, ':omz:lib:theme-and-appearance' gnu-ls, ':omz:alpha:lib:git' async-prompt, and ':omz:lib:<n>'/':omz:plugins:<n>' aliases toggles.
- Env-var feature flags read at startup include DISABLE_MAGIC_FUNCTIONS, DISABLE_LS_COLORS, DISABLE_AUTO_TITLE, ENABLE_CORRECTION, CASE_SENSITIVE, HYPHEN_INSENSITIVE, COMPLETION_WAITING_DOTS, DISABLE_UNTRACKED_FILES_DIRTY, HIST_STAMPS, ZSH_DISABLE_COMPFIX — all documented in the zshrc template.
- Theme-facing integration contract: themes call git_prompt_info/git_prompt_status/ruby_prompt_info/nvm_prompt_info etc.; lib/prompt_info_functions.zsh predefines no-op stubs (chruby, rbenv, hg, pyenv, svn, vi_mode, virtualenv, jenv, azure, tf, conda, go) so themes don't error when plugins are absent.
- Prompt-status symbols are themselves a plugin/theme API: ZSH_THEME_GIT_PROMPT_{PREFIX,SUFFIX,DIRTY,CLEAN,UNTRACKED,ADDED,MODIFIED,RENAMED,DELETED,UNMERGED,AHEAD,BEHIND,DIVERGED,STASHED} map parsed statuses to glyphs.
- Async prompt extension: any function can be registered with _omz_register_handler and its output surfaced via $_OMZ_ASYNC_OUTPUT[handler] inside a stub prompt function — documented in the file header as the intended (but unstable) API.
- The `omz` CLI is open for new subcommands: `omz foo` dispatches to _omz::foo if the function exists, and the _omz completer's cmds/subcmds arrays are the registry to extend; plugin/theme/pr use $0::subcommand namespacing.
- Random-theme selection is extensible via ZSH_THEME_RANDOM_CANDIDATES and ZSH_THEME_RANDOM_IGNORED arrays; the themes plugin additionally provides `theme`/`lstheme` for ad-hoc switching.
- Vendored upstream completions are an extension surface managed declaratively: adding an entry to .github/dependencies.yml (repo, branch, version, pre/postcopy hooks) lets the weekly updater pull new upstream completion sources into plugins/.
- add-zsh-hook (precmd/preexec) is the sanctioned way libs hook the prompt lifecycle — termsupport registers omz_termsupport_precmd/preexec/cwd, async_prompt registers _omz_async_request, and git.zsh prepends _defer_async_git_register to precmd_functions.
Contributor handoff
This is a pure-shell repo: no build step, no package manifest, no unit-test harness wired to CI. The safe edit boundary is 'add or modify files, don't reorder init'. Read oh-my-zsh.sh first (it defines load order and the _omz_source override contract), then the specific lib/ or plugins/ file. Validate changes with `zsh -n` on every touched file — that is literally all CI runs. Mind zsh-only syntax (emulate modes, zstyle, zparseopts, associative arrays), POSIX-sh vs zsh script split (install.sh is sh; upgrade.sh/tools are zsh), and that many variables/hooks are user-facing API you cannot rename.
- Read order for any task: oh-my-zsh.sh (init order, _omz_source, compinit handling) -> templates/zshrc.zsh-template (the user-facing config contract) -> the target lib/*.zsh or plugins/<n>/<n>.plugin.zsh -> CONTRIBUTING.md commit conventions.
- Never reorder the load sequence in oh-my-zsh.sh: plugin fpath entries must precede compinit, lib files precede plugins, $ZSH_CUSTOM/*.zsh loads last, and the theme loads after everything so it can use lib-defined functions.
- tools/install.sh is POSIX sh (#!/bin/sh, run via curl|sh) while tools/upgrade.sh, tools/check_for_upgrade.sh, and tools/changelog.sh are zsh scripts — do not use zsh-isms in install.sh or assume sh semantics in the tools.
- The only CI gate is `zsh -n` over oh-my-zsh.sh, lib/*.zsh, plugins/*/*.plugin.zsh, plugins/*/_*, and themes/*.zsh-theme — replicate it locally before submitting; there is no formatter config for shell (only .prettierrc for docs at 110 cols).
- Public API you must not break: plugin/theme/env-var names (ZSH_THEME, plugins, ZSH_CUSTOM, ZSH_CACHE_DIR, DISABLE_*, HIST_STAMPS), zstyle contexts ':omz:...', prompt functions (git_prompt_info, parse_git_dirty, *_prompt_info stubs), and aliases — all are consumed by user dotfiles and external themes/plugins.
- When writing shell that runs at startup, avoid forks and subshells; the codebase caches probes in $ZSH_CACHE_DIR (grep-alias, localhostname, appearance-probes) precisely to avoid per-start process spawns — follow that pattern for new probes.
- Quote % in anything that reaches the prompt: git.zsh escapes % to %% in branch names and upstreams, vcs_info.zsh exists because unquoted hook_com fields enabled command substitution (CVE-2021-45444), and _omz::log sets nopromptsubst for the same reason.
- Use `command`/`builtin` prefixes for external calls in lib code (diagnostics.zsh documents why: users redefine echo/which), and route git prompt calls through __git_prompt_git so GIT_OPTIONAL_LOCKS=0 is set.
- ZDOTDIR is a first-class citizen: all .zshrc-mutating code resolves ${ZDOTDIR:-$HOME}, and the installer picks $ZDOTDIR/ohmyzsh as $ZSH when ZDOTDIR is set and != HOME — replicate this resolution rather than hardcoding ~/.zshrc.
- Trap: editing the plugin-enable/disable awk logic means updating two copies — lib/cli.zsh and the duplicated copy inside lib/tests/cli.test.zsh.
- The devcontainer (.devcontainer/devcontainer.json) symlinks the workspace to ~/.oh-my-zsh and installs templates/minimal.zshrc as ~/.zshrc — the fastest way to smoke-test a change is a new container or `zsh -f` with a minimal zshrc sourcing the repo.
- New aliases face an explicit bar in CONTRIBUTING.md (used by many, common tasks, prefer generic over specific, don't shadow existing commands), and new themes are currently not accepted at all — check these policies before generating either.
Languages
| Language | Files | Share of source |
|---|---|---|
| Shell | 400 | 98% |
| Markdown | 394 | docs/config |
| YAML | 14 | docs/config |
| Python | 8 | 2% |
| JSON | 3 | docs/config |
Start reading here
Probable source entrypoint: lib/ — inferred from the directory tree and manifest, not the upstream docs.
Source roots
lib/ (22 files)
Repository structure
| Top-level path | Files |
|---|---|
plugins/ | 937 |
themes/ | 143 |
lib/ | 22 |
.github/ | 21 |
tools/ | 7 |
templates/ | 2 |
.devcontainer/ | 1 |
Docs found: CONTRIBUTING.mdREADME.md
CI & config entrypoints
README.md— Repository readme.github/workflows/installer.yml— GitHub Actions workflow.github/workflows/dependencies.yml— GitHub Actions workflow.github/workflows/project.yml— GitHub Actions workflow.github/workflows/main.yml— GitHub Actions workflow.github/workflows/scorecard.yml— GitHub Actions workflow
Structural health signals
Average score 7.7/10 across 8 analyzed source files; 1 hotspot surfaced.
.github/workflows/dependencies/updater.py— 621 lines, score 5.9 (Large file, Deep nesting)plugins/emoji/update_emoji.py— 213 lines, score 6.9 (Deep nesting, High churn)plugins/aliases/termcolor.py— 168 lines, score 7.4 (Deep nesting, Moderate churn)
These are deterministic review leads — size, churn, and structural signals — not proof of a bug in this project.
Recent history
86ef6555e0682026-09-22 — feat(hermes): add hermes plugin (#14111)32d7277ac34b2026-09-22 — docs(gh): fix the completion cache path in the README (#14117)e0d3557e14e52026-09-21 — fix(gradle): remove echo when running gradlew (#12893)b6830a53d5752026-09-21 — feat(otp): honour OTP_HOME and XDG_DATA_HOME (#12953)fa82d8a3eb842026-09-22 — fix(frontend-search): use fallback search for dead dartlang docs URL (#14112)