grayt-zsh-theme

September 8, 2026 · View on GitHub

A simple, yet informative, zsh theme.

This prompt focuses on:

  • Useful context for everyday development without a crowded prompt.
  • Simple styling that stays readable instead of becoming decoration.
  • Optional idle Git refreshes with Ref Fresh.
  • A stable two-line layout that keeps the command cursor predictable, even when the current directory or git branch name is long.
  • A few practical customization options without a pile of configuration.

Screenshots

This example shows a default zsh environment with no plugins sourcing the prompt. No configuration has been done; this is what it looks like out of the box. You can see a non-git directory, a clean git directory, an unclean git directory, and a non-zero return code.

The git branch and current directory both truncate when they get long enough to crowd the prompt. I'm using iTerm2 on MacOS, with the Hack font.

Installation

Clone this repository somewhere you keep zsh plugins, then source the theme from your ~/.zshrc.

# Assuming you clone plugins/themes in `~/.zsh`, but clone wherever you want.
git clone https://github.com/evanthegrayt/grayt-zsh-theme.git ~/.zsh/grayt-zsh-theme

# Put this in ~/.zshrc. If you cloned somewhere different, update the path.
source ~/.zsh/grayt-zsh-theme/grayt.zsh-theme

Restart your shell or re-source your ~/.zshrc.

source ~/.zshrc

Package Managers

Use your favorite zsh package manager by pointing it at this repository and sourcing grayt.zsh-theme.

With zinit:

zinit ice pick"grayt.zsh-theme"
zinit light evanthegrayt/grayt-zsh-theme

With zplug:

zplug "evanthegrayt/grayt-zsh-theme", as:theme

With antidote:

evanthegrayt/grayt-zsh-theme path:grayt.zsh-theme

With Oh My Zsh:

git clone https://github.com/evanthegrayt/grayt-zsh-theme.git \
  "${ZSH_CUSTOM:-$HOME/.oh-my-zsh/custom}/themes/grayt-zsh-theme"
ln -s \
  "${ZSH_CUSTOM:-$HOME/.oh-my-zsh/custom}/themes/grayt-zsh-theme/grayt.zsh-theme" \
  "${ZSH_CUSTOM:-$HOME/.oh-my-zsh/custom}/themes/grayt.zsh-theme"

ZSH_THEME="grayt"

Dependencies

This theme is standalone. It uses zsh's built-in prompt expansion and color helpers, and it shells out to git when the current directory is inside a repository. No zsh framework or git prompt plugin is required.

For idle prompt refreshes when Git branch or status changes happen in another terminal or application, use the optional Ref Fresh plugin.

Customization

Set customization variables before sourcing the theme. In the following examples, what you see is already the default.

Prompt colors use zsh color names:

GRAYT_PROMPT_COLOR=blue
GRAYT_PROMPT_TEXT_COLOR=grey

The current directory is truncated to 35 characters by default:

GRAYT_MAX_PWD_LENGTH=35
GRAYT_DISABLE_PWD_TRUNCATION=0

Git branch names are truncated to 20 characters by default. You can change the length and optionally strip a prefix or keep a suffix:

GRAYT_MAX_BRANCH_LENGTH=20
GRAYT_PREFIX_REGEX='^[^-]*-'
GRAYT_PREFIX_LENGTH=0
GRAYT_SUFFIX_LENGTH=8

You can also disable parts of the git prompt. Set a value to 1 to enable the setting:

GRAYT_HIDE_INFO=0
GRAYT_HIDE_STATUS=0
GRAYT_HIDE_DIRTY=0

Idle Git Refreshes

By default, grayt updates when zsh renders a new prompt. If you want branch and dirty-status changes from another terminal to appear while the prompt is idle, install Ref Fresh and load it before this theme.

git clone https://github.com/evanthegrayt/zsh-ref-fresh.git ~/.zsh/zsh-ref-fresh

REF_FRESH_ENABLE=1
source ~/.zsh/zsh-ref-fresh/zsh-ref-fresh.zsh
source ~/.zsh/grayt-zsh-theme/grayt.zsh-theme

Ref Fresh is separate on purpose: grayt stays standalone, and the refresh behavior can be used with other zsh prompts too.

Issues and Reporting Bugs

Please submit an issue if you find bugs.

Support this project

I love knowing when people find my work useful. Any kind of support is very much appreciated!