# Extension points — ohmyzsh/ohmyzsh

> Canonical page: https://codevetter.com/unpack/ohmyzsh/extension-points

# Extension points — ohmyzsh/ohmyzsh

Scanned commit 86ef6555e068663736a33376e4055aca9c1acc89 (2026-09-22). Generated by codevetter codevetter 1.12.0 on 2026-09-22.

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. — [oh-my-zsh.sh#L206-211](https://github.com/ohmyzsh/ohmyzsh/blob/86ef6555e068663736a33376e4055aca9c1acc89/oh-my-zsh.sh#L206-L211) [oh-my-zsh.sh#L241-245](https://github.com/ohmyzsh/ohmyzsh/blob/86ef6555e068663736a33376e4055aca9c1acc89/oh-my-zsh.sh#L241-L245) [custom/example.zsh](https://github.com/ohmyzsh/ohmyzsh/blob/86ef6555e068663736a33376e4055aca9c1acc89/custom/example.zsh) [README.md#L349-358](https://github.com/ohmyzsh/ohmyzsh/blob/86ef6555e068663736a33376e4055aca9c1acc89/README.md#L349-L358)
- 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. — [oh-my-zsh.sh#L81-98](https://github.com/ohmyzsh/ohmyzsh/blob/86ef6555e068663736a33376e4055aca9c1acc89/oh-my-zsh.sh#L81-L98)
- 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. — [oh-my-zsh.sh#L248-264](https://github.com/ohmyzsh/ohmyzsh/blob/86ef6555e068663736a33376e4055aca9c1acc89/oh-my-zsh.sh#L248-L264) [lib/theme-and-appearance.zsh#L8-13](https://github.com/ohmyzsh/ohmyzsh/blob/86ef6555e068663736a33376e4055aca9c1acc89/lib/theme-and-appearance.zsh#L8-L13)
- 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. — [tools/check_for_upgrade.sh#L14-20](https://github.com/ohmyzsh/ohmyzsh/blob/86ef6555e068663736a33376e4055aca9c1acc89/tools/check_for_upgrade.sh#L14-L20) [lib/theme-and-appearance.zsh#L89-91](https://github.com/ohmyzsh/ohmyzsh/blob/86ef6555e068663736a33376e4055aca9c1acc89/lib/theme-and-appearance.zsh#L89-L91) [lib/git.zsh#L177-214](https://github.com/ohmyzsh/ohmyzsh/blob/86ef6555e068663736a33376e4055aca9c1acc89/lib/git.zsh#L177-L214) [oh-my-zsh.sh#L191-197](https://github.com/ohmyzsh/ohmyzsh/blob/86ef6555e068663736a33376e4055aca9c1acc89/oh-my-zsh.sh#L191-L197)
- 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. — [templates/zshrc.zsh-template#L19-66](https://github.com/ohmyzsh/ohmyzsh/blob/86ef6555e068663736a33376e4055aca9c1acc89/templates/zshrc.zsh-template#L19-L66) [lib/misc.zsh#L4-16](https://github.com/ohmyzsh/ohmyzsh/blob/86ef6555e068663736a33376e4055aca9c1acc89/lib/misc.zsh#L4-L16) [lib/correction.zsh](https://github.com/ohmyzsh/ohmyzsh/blob/86ef6555e068663736a33376e4055aca9c1acc89/lib/correction.zsh) [oh-my-zsh.sh#L153](https://github.com/ohmyzsh/ohmyzsh/blob/86ef6555e068663736a33376e4055aca9c1acc89/oh-my-zsh.sh#L153)
- 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. — [lib/prompt_info_functions.zsh](https://github.com/ohmyzsh/ohmyzsh/blob/86ef6555e068663736a33376e4055aca9c1acc89/lib/prompt_info_functions.zsh) [lib/git.zsh#L179-236](https://github.com/ohmyzsh/ohmyzsh/blob/86ef6555e068663736a33376e4055aca9c1acc89/lib/git.zsh#L179-L236) [lib/nvm.zsh](https://github.com/ohmyzsh/ohmyzsh/blob/86ef6555e068663736a33376e4055aca9c1acc89/lib/nvm.zsh)
- 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. — [lib/git.zsh#L77-116](https://github.com/ohmyzsh/ohmyzsh/blob/86ef6555e068663736a33376e4055aca9c1acc89/lib/git.zsh#L77-L116) [lib/theme-and-appearance.zsh#L8-13](https://github.com/ohmyzsh/ohmyzsh/blob/86ef6555e068663736a33376e4055aca9c1acc89/lib/theme-and-appearance.zsh#L8-L13)
- 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. — [lib/async_prompt.zsh#L8-43](https://github.com/ohmyzsh/ohmyzsh/blob/86ef6555e068663736a33376e4055aca9c1acc89/lib/async_prompt.zsh#L8-L43)
- 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. — [lib/cli.zsh#L3-21](https://github.com/ohmyzsh/ohmyzsh/blob/86ef6555e068663736a33376e4055aca9c1acc89/lib/cli.zsh#L3-L21) [lib/cli.zsh#L25-35](https://github.com/ohmyzsh/ohmyzsh/blob/86ef6555e068663736a33376e4055aca9c1acc89/lib/cli.zsh#L25-L35) [lib/cli.zsh#L205-226](https://github.com/ohmyzsh/ohmyzsh/blob/86ef6555e068663736a33376e4055aca9c1acc89/lib/cli.zsh#L205-L226)
- 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. — [themes/random.zsh-theme](https://github.com/ohmyzsh/ohmyzsh/blob/86ef6555e068663736a33376e4055aca9c1acc89/themes/random.zsh-theme) [plugins/themes/themes.plugin.zsh](https://github.com/ohmyzsh/ohmyzsh/blob/86ef6555e068663736a33376e4055aca9c1acc89/plugins/themes/themes.plugin.zsh)
- 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/. — [.github/dependencies.yml](https://github.com/ohmyzsh/ohmyzsh/blob/86ef6555e068663736a33376e4055aca9c1acc89/.github/dependencies.yml) [.github/workflows/dependencies/updater.py](https://github.com/ohmyzsh/ohmyzsh/blob/86ef6555e068663736a33376e4055aca9c1acc89/.github/workflows/dependencies/updater.py)
- 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. — [lib/termsupport.zsh#L111-116](https://github.com/ohmyzsh/ohmyzsh/blob/86ef6555e068663736a33376e4055aca9c1acc89/lib/termsupport.zsh#L111-L116) [lib/async_prompt.zsh#L144-145](https://github.com/ohmyzsh/ohmyzsh/blob/86ef6555e068663736a33376e4055aca9c1acc89/lib/async_prompt.zsh#L144-L145) [lib/git.zsh#L207-213](https://github.com/ohmyzsh/ohmyzsh/blob/86ef6555e068663736a33376e4055aca9c1acc89/lib/git.zsh#L207-L213)
- Plugin README convention: `omz plugin info <name>` looks for $ZSH_CUSTOM/plugins/<name>/README.md then $ZSH/plugins/<name>/README.md and pages it through glow/bat/less — each plugin is expected to ship a README documenting its aliases. — [lib/cli.zsh#L418-454](https://github.com/ohmyzsh/ohmyzsh/blob/86ef6555e068663736a33376e4055aca9c1acc89/lib/cli.zsh#L418-L454) [README.md#L167-170](https://github.com/ohmyzsh/ohmyzsh/blob/86ef6555e068663736a33376e4055aca9c1acc89/README.md#L167-L170)

Every claim links to its cited files at the pinned commit. Citations identify source evidence; they do not establish runtime correctness. Independent CodeVetter scan — not reviewed by upstream maintainers.

## Public product links

- [CodeVetter](https://codevetter.com/)
- [Download](https://codevetter.com/download)
- [Documentation](https://codevetter.com/docs/)
- [Source](https://github.com/Codevetter/codevetter)