An oh-my-zsh plugin that shows you how many outdated Homebrew packages you have — right in your terminal MOTD.

Uses a stale-while-revalidate cache so your prompt is never blocked ⚡ The heavy brew update && brew outdated runs in the background; the display is an instant file read.

• 🚀 Zero-delay login — reads from cache, refreshes in background
• 🔄 Stale-while-revalidate — always shows something, updates behind the scenes
• 📦 First-run sync — no cache yet? Fetches synchronously so you always get output
• ⏱️ Configurable TTL — default 3 hours, set whatever you like
• 🖥️ Cross-platform — works on macOS and Linux
• 📋 Verbose mode — optionally list the outdated package names

Clone into your custom plugins directory:

git clone https://github.com/xalior/zsh-brew-outdated.git \
  ${ZSH_CUSTOM:-~/.oh-my-zsh/custom}/plugins/brew-outdated

Then add brew-outdated to your plugin list in ~/.zshrc:

plugins=(... brew-outdated)

zinit light xalior/zsh-brew-outdated

antigen bundle xalior/zsh-brew-outdated

Set these before oh-my-zsh is loaded in your ~/.zshrc:

Example:

BREW_OUTDATED_CACHE_TTL=7200      # refresh every 2 hours
BREW_OUTDATED_VERBOSE=true         # show package names
plugins=(... brew-outdated)
source $ZSH/oh-my-zsh.sh

Default:

7 outdated Homebrew package(s)

Verbose (BREW_OUTDATED_VERBOSE=true):

7 outdated Homebrew package(s)
ffmpeg
git
node
[email protected]
ripgrep
sqlite
wget

1. Plugin registers a precmd hook so output appears after your other MOTD (neofetch, fastfetch, etc.)
2. Checks the cache file's age against the TTL
3. If stale, spawns a background job to run brew update && brew outdated 🔄
4. If no cache exists at all, fetches synchronously so you always see output on first run
5. Displays from cache instantly — zero prompt delay ⚡

The plugin refreshes its cache when you open a shell, but Homebrew's own autoupdate tap can keep your formulae database fresh in the background via launchd — even when you haven't opened a terminal in a while.

brew tap homebrew/autoupdate
brew autoupdate start 43200 --cleanup   # every 12 hours

This pairs nicely with the plugin: brew autoupdate keeps brew update running on a schedule, so when the plugin checks brew outdated the results are already up to date — making the background refresh even faster. ⚡

Without brew autoupdate, the plugin handles everything on its own — it just means the background refresh includes a brew update which takes a few seconds longer.

• zsh + brew
• Works with oh-my-zsh, zinit, antigen, or manual sourcing

MIT — go wild 🤘