Skip to content
Desktop notifications for local and remote long-running commands in iTerm2 and Zsh.
Python Shell
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.
notifications change `send` arguments handlers and improve README Nov 10, 2019
.travis.yml logging and other improvements Nov 10, 2019
LICENSE hello world Nov 5, 2019 change `send` arguments handlers and improve README Nov 10, 2019 change `send` arguments handlers and improve README Nov 10, 2019 change `send` arguments handlers and improve README Nov 10, 2019 change `send` arguments handlers and improve README Nov 10, 2019

iTerm-notify Build Status

Desktop notifications for local and remote long-running commands in iTerm2 and Zsh, Fish or Bash.


iTerm-notify hooks into your shell and iTerm to send you Desktop notifications when those commands you started and forgot about in some tab finally finish. To use it, follow the instructions below to run the script with iTerm and load (or in your shell's initialization file.

Once iTerm-notify is hooked up, you can also use iterm-notify send TITLE MESSAGE to immediately send notifications from the shell.


  • iTerm2 with the Python API enabled with version > 3.8 of the Python Runtime (at the time of writing, this is only available with the beta)
  • Zsh, Fish or Bash (with bash-preexec)


  1. Clone this repository
  2. Create your "identity file" by entering a random string as the first line in $HOME/.iterm-notify-identity
  3. Symlink to ~/Library/ApplicationSupport/iTerm2/Scripts/AutoLaunch/
  4. Source (Zsh, Bash) or (Fish) in your shell initialization file
  5. Start from iTerm2's Scripts menu (Scripts > AutoLaunch >
  6. Copy the identity file and init.*sh (and source it!) on any other machine you want to receive notifications from.
  7. For Bash: download and install bash-preexec (bundled with iTerm2's shell integration)

Supported shells

iTerm-notify needs to track commands starting and finishing and it can work out of the box with shells that provide hooks around the prompt, such as Zsh's preexec/precmd hooks or Fish events. In Bash, bash-preexec (which is bundled with iTerm2's shell integration) is required and must be loaded before

Users of other shells can try to make it work by rolling out their own integration:

  • iterm-notify before-command COMMAND_LINE must be called before executing every command, passing whatever the user typed on the prompt as the first argument

  • iterm-notify after-command EXIT_CODE must be called after the command finished, passing it the exit code as the first argument


iTerm-notify uses iTerm2's support for Custom Control Sequences to send text from the shell to iTerm which in turn forwards the text to Python-based "daemon" (if the "identity" matches). So, tracking commands works correctly in these scenarios:

  • Zsh, Fish or Bash running locally or in an SSH session, even when nested or in iTerm's buried sessions
  • Zsh or Bash running locally in TMUX
  • TMUX in an SSH session, but not SSH in a TMUX session


The behavior of iterm-notify can be modified by using iterm-notify config-set, giving a parameter and its value as first and second arguments, or giving - as the first and only argument, and parameters and their values one per line on STDIN.

To persist your setting just add calls to iterm-notify config-set to your shell's initialization file, after sourcing

  • Set the notification backend:

    iterm-notify config-set notifications-backend terminal-notifier 

    Supported backends:

    • iterm: notifies using a modal alert using iTerm2's own Alert mechanism; can only display notification title and text (no sound, etc)
    • osascript (default): shows notification in Notification Center using display notification from Apple Script's StandardAdditions.osax; can show title, message and play sounds, but no custom icons
    • terminal-notifier: requires manual installation of and (...)/ must be in $PATH; can show title, message, icons and play sounds
  • Customize the notifications (check above for what will actually work with your preferred backend):

    iterm-notify config-set - <<'FOO'
        success-title Command finished successfully!
        success-icon /path/to/success-icon.png
        success-sound Glass

    Replace "success" with "failure" for, well, customizing failure notifications. The value for icon can also be an URL when using the terminal-notifier; backend. Try this. Wow. The value for sound should be a sound name, you can find a list in Sound Preferences.

    The value for title can also be a Python format string using any of these placeholders:

    • exit_code: the command's exit code
    • command_line: the full command line typed by the user at the prompt
    • duration_second: the command's duration, in seconds
  • Set a different timeout for notifications:

    iterm-notify config-set command-complete-timeout 15
You can’t perform that action at this time.