iterm2-countdown

A countdown timer for iTerm2's status bar. Set a target time from the terminal and see the remaining time in your status bar.

Installation

uv tool install git+https://github.com/sklum/iterm2-countdown.git

Then install the iTerm2 status bar component:

iterm2-countdown --install

iTerm2 Setup

1. Enable Python API: iTerm2 → Settings → General → Magic → Enable Python API
2. Restart iTerm2
3. Add the component: Settings → Profiles → Session → Configure Status Bar
4. Drag "Countdown Timer" to your status bar

Usage

# Set a countdown
iterm2-countdown 8:00 PM
iterm2-countdown 20:00
iterm2-countdown 5pm

# Check status
iterm2-countdown --status

# Clear countdown
iterm2-countdown --clear

If the specified time has already passed today, the countdown is automatically set for tomorrow.

Uninstall

iterm2-countdown --uninstall
uv tool uninstall iterm2-countdown