rickstaa/tmux-notify

Tmux plugin to notify you when processes are finished.

tmux-notify

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.

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).

Note

Works on Linux and macOS (note: only actively tested on Linux).

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.

Important

There is a known issue with alt-based Tmux shortcuts on osx. If you encounter problems, please check this post for a workaround.

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.

Warning

Remember that there is a trade-off between notification speed (short sleep duration) and the amount of memory this tool needs.

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.

Note

Feel free to open a pull request or issue if you think your shell prompt suffix should be included by default.

Enable telegram channel notifications

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' 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.

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.

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').

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.

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

tmux-notify's Issues

Add ability to change key maps

I want to change the keymap to prefix - n. Because prefix-m for activating mouse. How can I do that?

Monitoring a local pane that has nested remote tmux not working

Describe the bug
When monitoring a pane that has a nested remote tmux (with status bar at the bottom) session the monitor doesn't work. I guess the plugin reads the status bar instead of the prompt, the status bar "blocks" the prompt.

To Reproduce
Steps to reproduce the behavior:

1. ssh to remote
2. Open tmux session with status bar at the bottom on the remote
3. Execute a command to monitor later on remote
4. Monitor the local pane
5. Wait for the command to finish and see the monitor is still monitoring

Expected behavior
I don't know how the plugin can know where the prompt is exactly but I guess we need to figure this out.

Desktop (please complete the following information):

• OS: Ubuntu 20.04.3 LTS

Improve bash script formatting

It would be nice to improve the bash code format to the guidelines given in this blog post.

Option to enable visual bell

I think it would be helpful the have the ability to enable a tmux visual bell with the notification (see this post).

Include process/pane info in notification

Include some kind of identification of the process / pane in the notification.

Execute custom commands when processes are complete

I am using tmux on a server, and I want to make the tmux on a server send a notification to my desktop when processes are complete. It seems that tmux-notify currently only send notifications via notify-send. However, it seems that notify-send can not send notifications to remote desktop (i.e., my personal desktop).

I think allowing executing custom commands when processes are complete is helpful in this case. I can write a script that sends an email to my mailbox or a script that logs in to my personal desktop and execute zenity or something else to prompt a notification on my personal desktop.

Add tags to the repo

Feature/suggestion: tag the repo with tmux and tmux-plugins so it can be more easily found

[IMPORTANT] Project unmaintained. Please migrate to 'rickstaa/tmux-notify'

oh I agree, I typically despise forks as people are too quick to fork rather than try to work with maintainers. but in the case where a maintainer has ghosted the repo and people are using it I think it's the only way. GitHub Support historically doesn't intervene when I wish they would.

Same here, de-forking is my last resort 😅. However, the last response I received from the author was more than 3 years ago (see #16 (comment)) and I tried to contact him on all channels.

The de-forking just finished, and it looks like all the history was retained 🎉. The only contributor that is not shown any more is @bruno- because I think those initial commits were cherry-picks. Anyway, we are good to continue the maintained on my new orphan repository 👍🏻. Alternatively, as stated in #16 I'm also okay with transferring the repository to the https://github.com/tmux-plugins organization and maintaining it from there if @bruno-, @ctjhoa and @jbnicolai are interested. I think there it would even reach more people.

Originally posted by @rickstaa in #28 (comment)

As explained in the post above, @ChanderG no longer seems to maintain this repository 🙁. Since I wanted more control while maintaining this project, I detached my fork and will maintain this project there. I'm happy to detach it again in the future, might @ChanderG return to help me maintain it 👍🏻.

How to migrate to the new upstream

To migrate to the new upstream (i.e. https://github.com/rickstaa/tmux-notify), change the following line:

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

to:

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

in your .tmux.conf.

Support/docs for setting up host notifications from within a docker container

Is your feature request related to a problem? Please describe.
Tried running in a docker container, all deps installed (bash, notify-send).
Please offer support/docs for setting up host notifications from within a docker container.

Describe the solution you'd like
Be notified when a monitored process finishes in the docker container.

Describe alternatives you've considered
None, any suggestions are useful.

Additional context
None.

let user define their process completed key word

Is your feature request related to a problem? Please describe.
At first, I found it did not work on my terminal. Then I looked into the script. I found we use # or $ to check the process if it is stopped.
here
But my command line is like 🤣

Describe the solution you'd like
If my understanding of the notify.sh is correct. We might let it be a customizable variable to capture the completed event.

Protection against starting a monitor multiple times on the same pane.

Currently, it is possible to start a monitor session multiple times on the same pane. We might need to prohibit this.

Add screencast of plugin in action

The idea is good however it doesn't seem to work for me :( Running on CentOS system with 3.1c. When I do prefix + alt + m I get message saying pane is already being monitored, I run sleep 15 but when the command finished focus is not regained and no notifications. I would like to see how it should work.

Add the ability to change focus automatically when process finishes

I just noticed that @nat-chan created a very useful feature in his fork. This new feature automatically switches focus to the finished window. I think this would be good. I, however, think it should not be the default as it is currently in @nat-chan's branch.

Proposal

My Idea is to pull the changes of @nat-chan into my fork and modify them slightly such that user has two ways to monitor a pane:

• prefix + m: The regular pane monitor option.
• prefix + alt + m: Now the pane is monitored, and the focus is returned to the pane when it finishes.

Alternatively, we can of course also use a tmux-option to change this behaviour, but I think the above method would allow users to decide on a pane basis whether the want to return the focus. @ChanderG and @bruno- what do you think about this new feature?

The wrong pane is monitored after switching to another window

After starting the monitor, if you display new window, tmux-notify will begin monitoring the new window instead of the original window from which it was invoked.

Steps to reproduce

1. In a tmux pane, run the command sleep 100s.
2. Press prefix + m to start monitoring the pane.
3. Create a new window by pressing prefix + c or whatever key sequence you have new-window bound to.
4. Leave the new window idling at the command prompt. After about 10 seconds, you will receive a notification that the task has completed.
5. Switch back to the original window and pane and see that, in fact, sleep 100s is still running.

My environment is as follows

• Platform: Linux 5.11.2
• Tmux version: 3.1c
• TERM inside tmux: tmux-256color
• TERM outside tmux: rxvt-unicode-256color

Pressing `prefix + M` to cancel the monitor doesn't work

Upon pressing prefix + M, tmux displays the message Pane not monitored... even if the pane is actively being monitored.

Steps to reproduce

1. Press prefix + m to start monitoring a pane with an active task.
2. Press prefix + M to cancel the monitoring.

Expected behavior

Tmux should should display the message Pane monitoring canceled....

Actual behavior

Tmux displays the message Pane not monitored....

My environment is as follows

• Platform: Linux 5.11.2
• Tmux version: 3.1c
• TERM inside tmux: tmux-256color
• TERM outside tmux: rxvt-unicode-256color

Move the tmux-notify plugin to the tmux-plugins orginaization

@ChanderG @bruno- Maybe it's an idea after we merged #10 #15 that we transfer the plugin to the tmux-plugins orginaization? This way this in my opinion very useful plugin reached more people and resides at a more central place inside the community. In addition, we can also create pull requests for the plugin to be added to the list found in rothgar/awesome-tmux.

How to get the name of the monitored session in the custom command?

I have many sessions on my server, so I want to get the session name of the monitored session and attach it to the notification email. I tried tmux display-message -p '#S' (https://superuser.com/a/410197/1677998):

set -g @tnotify-custom-cmd 'echo $(tmux display-message -p \#S) finishes" | s-nail --subject="tmux complete notification" [email protected]'

However, it seems that the attached session is the last attached session instead of the monitored session. Then I tried to get the tty name of the monitored session and find the corresponding session (https://superuser.com/a/1202709/1677998):

# ~/session-name.sh

tty=$(tty)
#echo $tty
for s in $(tmux list-sessions -F '#{session_name}' 2>/dev/null); do
    tmux list-panes -F '#{pane_tty} #{session_name}' -t "$s"
done | grep "$tty " | awk '{print $2}'

set -g @tnotify-custom-cmd 'echo "\"$(bash $HOME/session-name.sh)\" finishes" | s-nail --subject="tmux complete notification" [email protected]'

However, tty=$(tty) returns a not a tty result.

I also tried https://superuser.com/a/1357132/1677998:

if [[ -n "$TMUX_PANE" ]]; then
    session_name=$(tmux list-panes -t "$TMUX_PANE" -F '#S' | head -n1)
fi

However, TMUX_PANE is not defined.

Is there any way to get the session name of the monitored session in the custom command? I need this because attaching up to ten sessions one by one to find the one that finishes is very painful.