Tmux plugin to notify you when processes are finished.
Note
Notifications are sent via libnotify, and visual bells are raised in the Tmux window. Visual bells can be mapped (in the terminal level) to the X11 urgency bit and handled by your window manager.
- Use cases
- Pre-requisites
- Install
- Usage
- Configuration
- How does it work
- Other use cases
- Contributing
- References
- 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.
- Bash
- Tmux
notify-send
orosascript
.- Optional:
wget
(for telegram notifications).
Note
Works on Linux and macOS (note: only actively tested on Linux).
Using Tmux Plugin Manager, add:
set -g @plugin 'rickstaa/tmux-notify'
to your .tmux.conf
.
Use prefix I
to install.
-
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.
Important
There is a known issue with alt-based Tmux shortcuts on osx. If you encounter problems, please check this post for a workaround.
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.
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.
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.
Warning
Remember that there is a trade-off between notification speed (short sleep duration) and the amount of memory this tool needs.
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.
Note
Feel free to open a pull request or issue if you think your shell prompt suffix should be included by default.
Warning
This feature requires wget to be installed on your system.
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'
andset -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.
Note
You can get your telegram bot id by creating a bot using BotFather and your channel id by sending your channel invite link to the @username_to_id_bot
bot.
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'
).
Warning
The custom command is executed using the eval
command, so be careful with what you put in here.
Note
Please consider contributing to this repository if your custom command is useful for others.
A naive approach. Checks if pane content ends with the bash prompt suffixes mentioned above every 10 seconds.
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.
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.
- The initial version of this tool was developed by @ChanderG.
- Icon created with svg made by @chanut from www.flaticon.com