free, distributed and user-friendly IRC / Twitter / XMPP / Campfire / JabbR client for Linux, Windows and Mac OS X based on GNOME / GTK+

Smuxi Hooks / Scripts / Plugins

Language Support

After years of waiting we are more than happy to finally have scripting support in Smuxi! You are probably thinking right now "so which scripting language is it?! C#? VB.NET? JavaScript? Perl? Python? Ruby? Maybe even PHP?" and here comes the best part: ALL OF THEM AND MORE! More? What else there would be... well, if you really want you can write Smuxi hooks in C, C++ or even assembler ;)

How It Works

It's Magic! No, just kidding. This is pure Unix technology taken from the 70s ported to a powerful messaging client. If you know what Git hooks, Nagios checks/plugins or CGI scripts are, then you already know what Smuxi hooks are, if you don't then continue reading this paragraph. Any executable program in a special location (hook points) will be executed when a specific event happens, like receiving a message. This program gets all information passed as environment variables, like who send the message (SENDER), what was the message (MSG), when was it received (MSG_TIMESTAMP_UNIX) etc. This program is also able to execute Smuxi commands by writing hook commands to the standard output.

Currently there are 3 different types of Smuxi hook points:

Finding Hooks

Smuxi hooks are maintained in the smuxi-hooks git repository. So if you want to share your written hook simply create a pull request against that repository on GitHub, other Smuxi users will be very thankful! Here a list of some already implemented ones:

Installing Hooks

"Wow, I am completely amazed, but how can I install hooks?" For now you will need to either download the files of the hook into the same location into $HOME/.local/share/smuxi/hooks or by cloning the git repository and symlinking the files. Here is an example for each method:

Download Method

mkdir -p $HOME/.local/share/smuxi/hooks/frontend/command-manager/command-np/
cd $HOME/.local/share/smuxi/hooks/frontend/command-manager/command-np/
wget https://raw.github.com/meebey/smuxi-hooks/master/now-playing/frontend/command-manager/command-np/now-playing.sh
chmod +x now-playing.sh

Git Clone Method

cd $HOME
git clone https://github.com/meebey/smuxi-hooks.git
mkdir -p $HOME/.local/share/smuxi/hooks/frontend/command-manager/command-np/
cd $HOME/.local/share/smuxi/hooks/frontend/command-manager/command-np/
ln -s $HOME/smuxi-hooks/now-playing/frontend/command-manager/command-np/now-playing.sh

Location

Hooks are automatically activated when they are placed in the right location. So after putting them in the hook point location (see see Hook Points section) you don't need to do anything else.

The base location (without the hook point part) is for

Environment Variables

All variables are prefixed with SMUXI_ to prevent clash with other environment variables.

Hook State

Hooks are executed when the event occurs and have to exit so further processing can be done. If hooks need to retain state they can write their state to files of the current directory ($PWD). Each hook has its own state directory and can be found in $HOME/.local/share/smuxi/hook-state/$HOOK_PATH. The hook does not need to change to or create the state directory, as the hook runner will do this for the hook, guaranteed.

Hook Points

engine/protocol-manager/on-connected/

engine/protocol-manager/on-disconnected/

engine/protocol-manager/on-message-sent/

engine/protocol-manager/on-message-received/

engine/protocol-manager/on-presence-status-changed/ (>= 1.0)

This hook point is raised when the presence status of a protocol manager changes. This happens for example when an IRC connection toggles the away state.

Event specific environment variables:

engine/session/on-group-chat-person-added/

engine/session/on-group-chat-person-removed/

engine/session/on-group-chat-person-updated/

engine/session/on-event-message/ (>= 1.0)

This hook point raises event messages that usually begin with "-!-". This can be useful to track state changes that are shown as a message without having a dedicated hook point for it.

engine/session/command-$cmd/ (>= 1.0)

This hook point is raised on the engine side for commands, e.g. /some_command that isn't handled by the frontend or engine built-in commands. This is useful for commands that should be available for all frontends and isn't specific to the frontend environment.

frontend/command-manager/command-$cmd/

This hook point is raised on the frontend side for commands, e.g. /some_command that isn't handled by the frontend or engine built-in commands. This is useful for commands that rely on the frontend environment, like dealing with windows, notifications, D-Bus, etc.

Hook Commands

Session.Command $cmd $cmd_params...

Supported session commands can be found here.

Example:

echo "Session.Command /echo I am a hook!"

ProtocolManager.Command $cmd $cmd_params...

Supported protocol manager commands fully depends on the protocol manager implementation/type, thus you need to check the PROTOCOL_MANAGER_PROTOCOL environment variable first! Here you can find a list for IRC, Twitter, XMPP, JabbR and Campfire.

Example:

if [ "$SMUXI_PROTOCOL_MANAGER_PROTOCOL" = "IRC" ]; then
    echo "ProtocolManager.Command /topic This is the new topic"
fi