tmux-notify

Tmux plugin to notify you when processes are finished.

Table of Contents

• Use cases
• Pre-requisites
• Install
• Usage
• Configuration
  • Enable verbose notification
  • Change monitor update period
  • Add additional shell suffixes
  • Enable telegram channel notifications
  • Execute custom notification commands
• How does it work
• Other use cases
  • Use inside a docker container
• Contributing
• References

Use cases

• When you have already started a process in a pane and wish to be notified (i.e. you can't use a manual trigger).
• Working in different containers (Docker) -> can't choose the shell -> and can't use a shell-level feature.
• Working over ssh, but your Tmux is on the client side.

Pre-requisites

• Bash
• Tmux
• notify-send or osascript.
• Optional: wget (for telegram notifications).

Install

Using Tmux Plugin Manager, add:

set -g @plugin 'rickstaa/tmux-notify'

to your .tmux.conf.

Use prefix + I to install.

Usage

• prefix + m: Start monitoring a pane and notify when it finishes.

• prefix + alt + m: Start monitoring a pane, return it in focus and notify when it finishes.

• prefix + M: Cancel monitoring of a pane.

Configuration

Enable verbose notification

The default notification text is Tmux pane task completed!. This tool also contains a verbose output option which gives more information about the pane, window, and session the task has completed.

To enable this, put set -g @tnotify-verbose 'on' in the .tmux.conf config file.

Change the verbose notification message

To change the verbose notification text, put set -g @tnotify-verbose-msg 'put your notification text here' in the .tmux.conf config file. You can use all the Tmux variables in your notification text. Some useful Tmux aliases are:

• #D: Pane id
• #P: Pane index
• #T: Pane title
• #S: Session name
• #I: Window index
• #W: Window name

For the complete list of aliases and variables, you are referred to the FORMATS section of the tmux manual. You can also add a notification title using set -g @tnotify-verbose-title. Doing so will move the verbose notification text into the notification body.

Change monitor update period

By default, the monitor sleep period is set to 10 seconds. This means that tmux-notify checks the pane activity every 10 seconds.

Put set -g @tnotify-sleep-duration 'desired duration' in the .tmux.conf file to change this duration.

Add additional shell suffixes

The Tmux notify script uses your shell prompt suffix to check whether a command has finished. By default, it looks for the $, # and % suffixes.

Put set -g @tnotify-prompt-suffixes 'put your comma-separated bash suffix list here' in the .tmux.conf file to add additional suffixes.

Enable telegram channel notifications

By default, the tool only sent operating system notifications. It can, however, also send a message to a user-specified telegram channel.

Put set -g @tnotify-telegram-bot-id 'your telegram bot id' and set -g @tnotify-telegram-channel-id 'your channel id' in the .tmux.conf config file to enable this.

After enabling this option, the following key bindings are available:

• prefix + ctrl + m: Start monitoring pane and notify in bash and telegram when it finishes.

• prefix + ctrl + alt + m: Start monitoring a pane, return it in focus and notify in bash and telegram when it finishes.

Additionally, you can use the set -g @tnotify-telegram-all 'on' option to send all notifications to telegram.

Execute custom notification commands

You can execute a custom command after a process has finished by putting set -g @tnotify-custom-cmd 'your custom command here' in the .tmux.conf file. The custom command is executed in the pane where the process has finished. If you want to execute multiple commands, you can also put them in a bash script and execute this script (i.e. set -g @tnotify-custom-cmd 'bash /path/to/script.sh').

How does it work

A naive approach. Checks if pane content ends with the bash prompt suffixes mentioned above every 10 seconds.

Other use cases

Use inside a docker container

Because tmux-notify uses libnotify to send notifications, it needs access to the host's D-Bus socket. An excellent guide on how to do this can be found here. You can also check out the examples/docker folder for an example.

Contributing

Feel free to open an issue if you have ideas on how to make this GitHub action better or if you want to report a bug! All contributions are welcome 🚀. Please consult the contribution guidelines for more information.

References

• The initial version of this tool was developed by @ChanderG.
• Icon created with svg made by @chanut from www.flaticon.com