Hyperzsh is a zsh theme that puts git state and the last exit code in the prompt

A theme scoped to one workflow

Hyperzsh is described as a z shell theme designed to complement a git-focused workflow, and the README's own framing is that it gives you a clear overview of the branch you are working on and the status of your repository throughout the development process without cluttering your terminal.

The word git-focused is doing the work. This is not a general purpose prompt with a git section, it is a prompt built around git and the four questions a git-heavy day raises: which branch am I on, is the tree dirty, how long since I committed, and did the last command fail.

The README lists what the prompt shows, in order: the current working directory, the git branch, the current SHA as an optional item, the exit code of the last command, the time since the last commit, and the git status.

That order is a design decision. The exit code sits between the SHA and the commit time, which puts the most immediately actionable signal in the middle of the line rather than at the end where a shell normally puts it.

There is also a right hand prompt, which the README says displays the current branch, the time since the last commit, and the commit status of the repository.

The project is MIT licensed, credited to Tyler Reckart, with the last push on 2026-05-21 and no GitHub releases published. The repository is small: a `hyperzsh.zsh-theme` file at the root, a `package.json`, a `screenshots/` directory with a demo animation and a prompt example, and the usual governance files including `CONTRIBUTING.md` and `CODE_OF_CONDUCT.md`.

Three ways to install it

The theme installs through whichever zsh plugin manager you already use, and the README covers all three.

For antigen users, the step is a single line: add `antigen bundle tylerreckart/hyperzsh` to your `.zshrc`, and antigen will clone and load the hyperzsh repository automatically the next time you start a zsh session.

For oh-my-zsh users, the steps are to create the custom themes directory, download the theme file into it, edit your `.zshrc` and change the theme variable:

2. `wget -O $ZSH_CUSTOM/themes/hyperzsh.zsh-theme https://raw.githubusercontent.com/tylerreckart/hyperzsh/master/hyperzsh.zsh-theme`  

followed by editing `~/.zshrc` and setting `ZSH_THEME="hyperzsh"` in place of whatever theme name was there.

For zgen users, you add `zgen load tylerreckart/hyperzsh` to your `.zshrc` with your other zgen load statements, and `zgen save` plus zgen will handle cloning the repository for you.

That the README documents three routes is a small sign of age and of care: antigen and zgen are both less common now than they were, and a theme that only documents oh-my-zsh would leave a chunk of users stranded.

The oh-my-zsh route has one wrinkle worth knowing, and it is the same wrinkle every custom oh-my-zsh theme has. You are downloading a single file from a branch of a repository, so your theme is a copy that does not update when the repository does. If you want to follow upstream changes you have to re-download the file, and if you have edited it, you have to re-apply your edits. The antigen and zgen routes clone the repository instead, so they track the upstream by default, at the cost of the repository sitting in your plugin directory.

Reading the prompt string

The README shows how the prompt is composed, and that is the best documentation of what the theme does, because a zsh prompt is just a string built from function calls.

# The prompt
# PROMPT='$(_user_host)$(_python_venv)%{$fg[cyan]%}%c $(git_prompt_info)%{$reset_color%}$(git_prompt_short_sha)%{$fg[magenta]%}$(_git_time_since_commit)$(git_prompt_status)${_return_status}➜ '

# Prompt with SHA
PROMPT='$(_user_host)$(_python_venv)%{$fg[cyan]%}%c $(git_prompt_info)%{$reset_color%}$(git_prompt_short_sha)%{$fg[magenta]%}$(_git_time_since_commit)$(git_prompt_status)${_return_status}➜ '

Reading that left to right: the user and host, the Python virtual environment, the working directory in cyan, the git branch information, the reset, the short SHA, the time since the commit in magenta, the git status, the return status of the last command, and the prompt arrow.

Two details are worth pulling out. The `%{$...%}` pairs are zsh's markers for a zero width sequence, which is how the colour codes are inserted without the shell counting them as printable characters and misaligning the cursor. And the last piece, `${_return_status}`, is a parameter expansion rather than a command substitution, which is the cheap way to show the previous exit status without running a subprocess on every prompt.

The two lines in the block are the same string with one difference, and that difference is the whole of the SHA feature. The commented line is the default prompt and the uncommented one is the same prompt with the short SHA enabled, which is the README's instruction: edit `hyperzsh.zsh-theme`, un-comment the prompt with SHA and make sure the default prompt is commented out or removed.

So the SHA is not a setting you flip, it is a line you uncomment. That is a deliberate choice for a single file theme, since it keeps the default configuration readable, but it does mean the file has two prompt definitions that can drift apart if you edit one and not the other.

Status indicators and the variables behind them

The status indicators are the part of the theme you are most likely to want to change, and the README gives a complete table with the variable name, the symbol and the meaning.

`ZSH_THEME_GIT_PROMPT_UNTRACKED` marks untracked files, `ZSH_THEME_GIT_PROMPT_ADDED` marks files added to git, `ZSH_THEME_GIT_PROMPT_MODIFIED` marks modified files, `ZSH_THEME_GIT_PROMPT_DELETED` marks deleted files, `ZSH_THEME_GIT_PROMPT_RENAMED` marks renamed files, `ZSH_THEME_GIT_PROMPT_UNMERGED` marks unmerged files, `ZSH_THEME_GIT_PROMPT_AHEAD` marks a repository ahead of the current branch, and `ZSH_THEME_GIT_PROMPT_DIRTY` marks a dirty repository.

Every one of those is a variable rather than a hardcoded character, so overriding a single variable in your `.zshrc` replaces one symbol without touching the rest. That is what makes the theme configurable rather than merely editable.

The symbols are chosen to be visually distinct rather than to be conventional. The dirty repository mark and the deleted files mark are the closest pair, differing only by the weight of the stroke, so a user who cares about telling them apart has a reason to change them. The ahead mark and the dirty mark are similar in shape at small sizes.

That is a fair criticism of any theme that uses text symbols: the rendering depends on the font, and the same character can look different or missing depending on the terminal and the size. The README's own answer to this is the tone of the options section, where the author notes that everything from the icons to the colours is customizable to whatever you want.

The right hand prompt has its own set of variables, all prefixed with `ZSH_THEME_GIT_TIME_SINCE_COMMIT`, and they control the colour of the elapsed time rather than the time itself: `SHORT` is green, `MEDIUM` is yellow, `LONG` is red and `NEUTRAL` is white.

So the elapsed time is a signal, not just information. A recent commit is green, a stale one is red, which means the colour is doing the work of telling you whether you have been idle too long.

What the repository contains, and what to expect

The repository is small and mostly documentation, which is normal for a theme, but two details are worth noting if you plan to maintain it.

The `package.json` describes the project as `hyperzsh` at version 1.5.0, with the description a hyperminimal zsh prompt, the main entry point `index.js`, and the keywords zsh, theme and hyperterm. The `main` field points at an `index.js` that the top level listing does not show, so the npm manifest is out of step with the repository contents. There is no `publishConfig` and no files field either, so publishing this package to a registry is not obviously the intent.

The test script is `gulp test`, with the dev dependencies being gulp at 3.9.1 and gulp-lintspaces at 0.4.1. So the check is a lint for trailing whitespace rather than a behavioural test, which is the right scope for a theme file but is worth knowing: there is nothing verifying that the prompt renders correctly, and the `.npmignore` at the root suggests someone once intended to publish.

The screenshots directory holds a demo animation and an image of the SHA prompt, so the visual expectation is documented even though there is no live demo page.

The alternative approaches are the other themes people use, and the difference is mostly about scope. oh-my-zsh ships themes of its own, which are simpler and cover less. The popular third party prompt frameworks go the other way, adding segments for language version managers, cloud sessions, battery and time, and they are maintained and configurable to a degree a single file theme is not. This theme wins on doing one thing well and staying readable in a single file, and loses on everything outside git.

If the file you need is not this one, the honest summary is that Hyperzsh is a small, readable, MIT licensed starting point whose indicators you can override one variable at a time.

Editorial conclusion

Adopt Hyperzsh when your day is spent in a git working tree and you want the branch, the repository status and the previous command's exit code visible without running anything. Do not adopt it if you want a prompt that covers every tool in your stack, since the theme is scoped to git and provides no language or virtual environment sections beyond what the prompt string references. Verify first that the indicators you want are enabled by default, since the short SHA is off until you edit the theme file, that the status symbols do not clash with the ones your terminal font already renders, and that the version you take is the one you read, since the package manifest is at 1.5.0 with the last push on 2026-05-21 and no published releases.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. README
4. tylerreckart/hyperzsh on GitHub