Filthy

September 1, 2026 · View on GitHub

A disgustingly clean ZSH prompt

Overview

Based on the great pure theme by @sindresorhus and @mafredri, but with a few notable changes.

  • Prompt character is green when previous command was successful, red when not.
  • Git repo info shown in RPROMPT.
  • Path is shown relative to git-root when in a repository.
  • Current commit/tag shown if HEAD is detached.
  • 'Initial' status is shown in a new repo
  • User and host always shown in RPROMPT, green for standard users, red if privileged.
  • Command execution time shows in ms if less than one second has elapsed.
  • Temporary messages can be displayed in the pre-prompt, e.g. to show feedback after an asynchronous command has completed. Just echo the text you want to display to ${ZDOTDIR:-$HOME}/.promptmsg. The message is automagically cleared once shown.

Install

Can be installed with npm or manually. Requires git 1.7.10+ and ZSH 4.3.17+.

fswatch is optional. Install it (brew install fswatch, apt install fswatch) to get live git updates.

(To show current tag/commit when head is detached, git 2.0.0+ is required. Otherwise it just shows 'no branch')

npm

npm install --global filthy-prompt

That's it. Skip to Getting started.

Zulu

zulu install filthy
zulu theme filthy

Manually

  1. Either…
  • Clone this repo
  • add it as a submodule, or
  • just download filthy.zsh
  1. Symlink filthy.zsh to somewhere in $fpath with the name prompt_filthy_setup.

Example

$ ln -s "$PWD/filthy.zsh" /usr/local/share/zsh/site-functions/prompt_filthy_setup

Run echo $fpath to see possible locations.

For a user-specific installation (which would not require escalated privileges), simply add a directory to $fpath for that user:

# .zshenv or .zshrc
fpath=( "$HOME/.zfunctions" $fpath )

Then install the theme there:

$ ln -s "$PWD/filthy.zsh" "$HOME/.zfunctions/prompt_filthy_setup"

Getting started

Initialize the prompt system (if not so already) and choose filthy:

# .zshrc
autoload -U promptinit && promptinit
prompt filthy

Options

FILTHY_CMD_MAX_EXEC_TIME

The max execution time of a process before its run time is shown when it exits. Defaults to 5 seconds.

FILTHY_SHOW_EXIT_CODE=1

Prints a nice exit code in front of the prompt character when the previous command exited with a status not equal to 0

FILTHY_SHOW_VERSIONS='node zsh php ruby python'

Chooses which language versions to display in $RPROMPT

FILTHY_ALWAYS_SHOW_FULL_PATH=1

Do not show relative paths when $PWD is within a git repository

FILTHY_LIVE_GIT_OFF=1

Turn off live git updates

FILTHY_LIVE_GIT_LATENCY

How long, in seconds, fswatch batches up filesystem events before waking the prompt. Defaults to 0.5. Raise it in very busy repositories.

FILTHY_FETCH_INTERVAL

How often, in seconds, to fetch from the remote in the background. Defaults to 180. Set it to 0 to never fetch, in which case the ahead/behind counts only move when you fetch or pull yourself.

FILTHY_CI_STATUS_INTERVAL

How often, in seconds, to ask hub for the CI status. Defaults to 30.

Live git updates

When fswatch is installed, filthy watches the repository you're in and refreshes the git segment while the prompt is idle. Commit, stage or switch branches in another terminal and the prompt updates on its own, without you having to press a key.

Without fswatch everything still works, the git segment just updates when a new prompt is drawn, as it always has. Set FILTHY_LIVE_GIT_OFF=1 to turn live updates off even when fswatch is available.

The git segment is always rendered in a background worker, so a slow repository never blocks the prompt or holds up your typing.

Example

# .zshrc

autoload -U promptinit && promptinit

# optionally define some options
FILTHY_CMD_MAX_EXEC_TIME=10

prompt filthy

Tips

Base16 Ocean theme with the Nitti Light font (18pt) is a beautiful combination, as seen in the screenshot above. Just make sure you have anti-aliasing enabled in your Terminal.

To have commands colorized as seen in the screenshot install zsh-syntax-highlighting.

Integration

oh-my-zsh

  1. Symlink (or copy) filthy.zsh to ~/.oh-my-zsh/custom/filthy.zsh-theme
  2. Add ZSH_THEME="filthy" to your .zshrc file.

prezto

Set zstyle ':prezto:module:prompt' theme 'filthy' in ~/.zpreztorc.

License

MIT © James Dinsdale