Improve documentation / add examples of custom modules

[ixzh]

For example, I want to show #{forecast} from 'aaronpowell/tmux-weather'.

I put set -g @catppuccin_status_modules_right "#{forecast} application session". didn't seem work.

[vladimir-popov]

Maybe this readme can help https://github.com/catppuccin/tmux/blob/main/custom/README.md

[89iuv]

In order to include another plugin, you need to write a custom module that uses that plugin.

[zeidlos]

Is there a possibility for any further documentation on this?
I can't get the stuff from 'custom/README' to work at all.

[89iuv]

Paste here your module config and i can have a look over it.

[omurilo]

I use the example file has on custom folder and my plugin doesn't load.

[Myzel394]

In order to include another plugin, you need to write a custom module that uses that plugin.

I'm facing the same issue. I want to include a different plugin but have no idea how to properly add it. I was able to create a dummy "Hello World" module that displayed correctly, but how do I call a plugin? I'm specifically talking about adding the module https://github.com/vascomfnunes/tmux-kripto

EDIT

Nevermind, seems like I figured it out ^^

For anyone coming across this, here's my script:

#!/bin/bash

show_kripto() {
  local index=$1
  local icon="$(get_tmux_option "@catppuccin_kripto_icon" "")"
  local color="$(get_tmux_option "@catppuccin_kripto_color" "#ffffff")"
  local text="$(get_tmux_option "@catppuccin_kripto_text" "#{kripto}")"

  local module=$( build_status_module "$index" "$icon" "$color" "$text" )

  echo "$module"
}

[qadzek]

Is there a possibility for any further documentation on this? I can't get the stuff from 'custom/README' to work at all.

How to create your own module?

In this guide, I will show you how to create your own module. We will start by displaying some static text, then we will use the output from the uptime command and finally we utilize an external script.

Basics

First, we have to create a new module. We will name our module my_module, so we will create a file called my_module.sh.

Place this file in ~/.tmux/plugins/tmux/custom/. Note that this path might change to something like ~/.tmux/plugins/tmux-catppuccin/custom/ in the future, when this repo gets renamed (see #129).

Copy the following content to my_module.sh. It's not necessary to make this .sh file executable.

# shellcheck shell=bash

show_my_module() { # This must match the module name!
  local index icon color text module

  index=$1
  icon="$(get_tmux_option "@catppuccin_test_icon" "")"
  color="$(get_tmux_option "@catppuccin_test_color" "$thm_orange")"
  text="$(get_tmux_option "@catppuccin_test_text" "Hello world")"

  module=$(build_status_module "$index" "$icon" "$color" "$text")

  echo "$module"
}

Now we have to add our custom module to the list of modules in .tmux.conf:

set -g @catppuccin_status_modules_right 'my_module user host session'

Finally, reload our Tmux configuration by executing tmux source-file ~/.tmux.conf.

Advanced

Displaying a static Hello world is pretty boring, right? Let's try to display something more dynamic.

First, we will just display the time, to ensure we aren't showing a stale value, but something that's actually continuously updated.

In my_module.sh, replace the line starting with text= by:

text="$(get_tmux_option "@catppuccin_test_text" "#( date +%T )")"

Save the file and reload the Tmux config. Now you should see the current time getting updated every couple of seconds. To change how often the modules are updated, add set -g status-interval 2 to your configuration.

Note that here we are just executing the date +%T command. To display, for example, how long our system has been running, we could use:

text="$(get_tmux_option "@catppuccin_test_text" "#( uptime -p | cut -d' ' -f2- )")"

This is a bit more advanced than the previous date command, because we use the pipe to combine two commands. uptime -p returns e.g. up 2 days, 20 hours, 25 minutes, but we don't need the up prefix, so we also use cut.

To change the icon of the module, just copy one from Nerd Fonts and insert it instead of the current icon (a checkbox).

To change the color of the module, change the color variable from "$thm_orange" to e.g. "$thm_cyan" (see all available colors) or use a hex color like "#00ff00".

Expert

Piping two commands was still possible inside our module file, but doing anything more complicated will quickly cause issues with quotes, parentheses etc. Let's create a companion script.

I will call it my_module_companion.sh and place it in my home directory, but it can be placed anywhere. Make it executable chmod u+x my_module_companion.sh.

In this final example, we will implement a request (#128) from a user, who wants to display their system's uptime, but in a more compact format: instead of 2 days, 21 hours, 52 minutes, they want to display 2d 21h 52m.

Add this to my_module_companion.sh:

#!/usr/bin/env bash

uptime_in_seconds=$(awk '{print int($1)}' /proc/uptime)

days=$((uptime_in_seconds / (60 * 60 * 24) ))
hours=$((uptime_in_seconds % (60 * 60 * 24) / (60 * 60)  ))
minutes=$((uptime_in_seconds % (60 * 60) / (60)  ))

echo "${days}d ${hours}h ${minutes}m"

Execute this script on the command-line to ensure it works correctly ./my_module_companion.sh

The script's output (in this case the text it echoes) will be displayed in our module. Replace the text variable by this line:

text="$(get_tmux_option "@catppuccin_test_text" "#($HOME/my_module_companion.sh)")"

Reload Tmux one more time and now you should see a compact uptime.

Note that we can generate the icon or the color dynamically as well, by having our script e.g. echo a hexadecimal color.

[fazlearefin]

Thanks I was able to get what I wanted following the guidance you provided.

For anyone trying to do the same, here is what I did (shows uptime as well as load average):

1. Create file called uptime.sh in $HOME/.tmux/plugins/tmux/custom with contents:

# shellcheck shell=bash

show_uptime() { # This must match the module name!
  local index icon color text module

  index=$1
  icon="$(get_tmux_option "@catppuccin_test_icon" "󱑆")"
  color="$(get_tmux_option "@catppuccin_test_color" "$thm_orange")"
  text="$(get_tmux_option "@catppuccin_test_text" "#( python3 $HOME/.tmux/plugins/tmux/custom/uptime_helper.py )")"

  module=$(build_status_module "$index" "$icon" "$color" "$text")

  echo "$module"
}

2. Create uptime_helper.py in $HOME/.tmux/plugins/tmux/custom with contents:

#!/usr/bin/env python3
import os


def get_uptime():
    with open("/proc/uptime", "r") as f:
        uptime_seconds = float(f.readline().split()[0])
        uptime_minutes, uptime_seconds = divmod(uptime_seconds, 60)
        uptime_hours, uptime_minutes = divmod(uptime_minutes, 60)
        uptime_days, uptime_hours = divmod(uptime_hours, 24)
        return int(uptime_days), int(uptime_hours), int(uptime_minutes)


def get_load_average():
    return os.getloadavg()


def format_uptime(days, hours, minutes):
    if days > 0:
        return f"{days}d {hours}h {minutes}m"
    elif hours > 0:
        return f"{hours}h {minutes}m"
    else:
        return f"{minutes}m"


def main():
    uptime_days, uptime_hours, uptime_minutes = get_uptime()
    load_avg = get_load_average()
    formatted_uptime = format_uptime(uptime_days, uptime_hours, uptime_minutes)
    formatted_load_avg = [f"{avg:.1f}" for avg in load_avg]
    print(f"{formatted_uptime} | {' '.join(formatted_load_avg)}")


if __name__ == "__main__":
    main()

3. Include the custom module uptime in $HOME/.tmux.conf

[sgoudham]

Hey 👋

I'd appreciate if either @qadzek or @fazlearefin could raise a PR to the custom docs section to improve it / add examples of custom modules. It's a shame for it to be buried in issues!

[qadzek]

I'd appreciate if either @qadzek or @fazlearefin could raise a PR to the custom docs section to improve it / add examples of custom modules. It's a shame for it to be buried in issues!

I will rewrite my guide a little and make a PR to add it to the custom docs section.

[qadzek]

@sgoudham: I have tried to make the instructions less wordy in the pull request than in the full guide above.

@ixzh: If you are still looking to include #{forecast} from aaronpowell/tmux-weather, it's pretty easy to do so. Just follow the instructions from that pull request and use this line: text="$( get_tmux_option "@catppuccin_<module_name>_text" " #{forecast} " )" . You just have to replace the module name. I installed that plugin, and it seems to be fully compatible with this catppuccin Tmux theme.