WeeChat is a text based chat client that runs on many different platforms like Linux, Mac OS X, various BSD variants and Windows (through cygwin). WeeChat is mainly used for IRC, aims to be fast, light and extensible and is a more modern alternative to IRSSI.

After switching from Campfire to Slack for the thoughtbot company chat, more of us started using WeeChat together with the Slack IRC gateway.

WeeChat can be installed either on your local machine or on a server.

Installing WeeChat on a server lets you always be online, even when you are not at your computer. This means that you will never miss a message in the channels you are connected to or any direct message or mention.

For instructions on installing WeeChat on a server check out the post Running WeeChat on a Server for IRC Backlogs.

Binary packages for the latest version of WeeChat are available for a bunch of different distributions like Debian (Backports) and Arch Linux. Installation is as simple as using your favorite package manager.

WeeChat is also available through Homebrew as weechat . When installing using Homebrew be sure to pass these options to enable script support for Lua, Perl, Python and Ruby scripts:

brew install weechat --with-lua --with-perl --with-python --with-ruby

For instructions specific to your distribution check out the WeeChat user’s guide.

First, get WeeChat up and running:

weechat

Then, add and connect to the Slack IRC gateway by issuing these commands inside of WeeChat:

/server add NAME HOST/6667 -autoconnect -ssl -ssl_dhkey_size=512 -password=PASSWORD -username=USERNAME -nicks=NICK /connect NAME

Where:

NAME is the name you want WeeChat to use when referring to this server.

is the name you want WeeChat to use when referring to this server. HOST is the Host as provided on the Gateways page.

is the as provided on the Gateways page. PASSWORD is the Pass as provided on the Gateways page.

is the as provided on the Gateways page. USERNAME is the User as provided on the Gateways page.

is the as provided on the Gateways page. NICK is your Slack username.

This command turns on the autoconnect feature, SSL encryption and sets the Diffie-Hellman key size to 512 . This is required since the WeeChat default value ( 2048 ) will cause errors during the SSL handshake with the Slack IRC gateway.

When you connect, the Slack IRC gateway will automatically join all channels that you already belong to.

If you want to join an existing channel or want to create a new one, use the /join command:

/join #yourchannel

In WeeChat, channels, private messages and connections to servers are displayed in what’s called buffers. By default WeeChat only displays one buffer at a time.

You can cycle between all open buffers by pressing Alt + Up / Down .

You can also switch between buffers using the /buffer command:

/buffer #general

Partial buffer names can be tab-completed.

Buffers are also numbered. You can jump between buffers using these numbers by pressing Alt + NUMBER or Esc and then NUMBER . To get a better overview of open buffers and their numbers, check out the buffers.pl plugin.

Buffers that have unseen activity are listed in the hotlist. To jump to the next buffer on the hotlist, press Alt + A . The hotlist is ordered by importance.

To leave a channel use the /part command. If you also want to close the current buffer use the /close command instead.

To send a direct message to another user, use the /query command:

/query calleerlandson Hello!

This will open a new buffer with your conversation.

The first buffer (buffer number 1) is the WeeChat core buffer. This buffer is used to interact with WeeChat and all servers you are connected to. When you issue commands like /help or /whois the output shows up in this buffer.

When you issue commands in the core buffer they get sent to its current target. The current target is either WeeChat itself or one of the servers you are connected to. You can see the current target on the line just above the buffer input field. To cycle between targets press Ctrl + X .

When issuing commands to WeeChat itself you don’t have to switch to the weechat target.

WeeChat is configured by issuing commands like /set , /unset , /server or /window . To get information about a command use the /help command like this:

/help COMMAND

Where COMMAND is the command you want information about.

If you issue the /help command without passing a command it will show you a list of all available commands.

WeeChat’s configuration is stored in files inside the ~/.weechat/ directory. To save the current configuration to disk use the /save command. To write the current layout configuration to disk use the /layout save command.

The current configuration is automatically saved to disk by WeeChat when you quit or certain other WeeChat commands. This prevents you from loosing your configuration but can also be a pain if you try to edit the files manually while WeeChat is running.

By default all messages containing your nickname will be highlighted. You might want other messages to be highlighted as well. For example, if you would like all messages that mention the word “fika” to be highlighted you can configure that by typing:

/set weechat.look.highlight fika

Tell WeeChat to highlight messages containing other words by separating them with commas:

/set weechat.look.highlight fika,pr,cats

The Slack IRC gateway uses the IRC voice feature to indicate user activity. A user is automatically voiced when active and devoiced when inactive. Users that are using the Slack web interface are constantly voiced and devoiced and this creates a lot of noise in WeeChat buffers. To filter out these messages you can add this filter:

/filter add hidevoices irc.NAME.* irc_mode (\+|\-)v

Where NAME is the name of your server in WeeChat.

By default WeeChat only uses a handful of colors to color the nicknames in buffers. In channels with a lot of people this can become confusing. This command lets WeeChat use a couple more colors:

/set weechat.color.chat_nick_colors red,green,brown,blue,magenta,cyan,white,lightred,lightgreen,yellow,lightblue,lightmagenta,lightcyan

To review what colors you are using you can use the /color command.

If you are running WeeChat in GNU Screen it is important that the TERM environment variable is set to screen-256color in order for WeeChat to be able to display all the above colors. You can force this by adding this line to your .screenrc :

term screen-256color

WeeChat is extensible through scripts written in an array of different languages. Scripts are listed on the Script section of the WeeChat website.

You can also browse listed scripts inside WeeChat using the /script command without any arguments:

/script

This will open an interactive buffer where you can browse, install, remove and load scripts.

Below I walk you through installing some scripts that I find usable in general and some with Slack in particular.

Buffers provides a sidebar where all open buffers are listed with their number. This gives me a much better overview of my buffers. The sidebar also shows which buffers has unread messages and highlights.

Install Buffers using the /script command:

/script install buffers.pl

By default Buffers will color the buffer names depending on activity in them. If you also want to know how many messages and highlights the buffers have you can tell Buffers to display a hotlist counter:

/set buffers.look.hotlist_counter on

Navigating through all the different WeeChat configuration options can be hard. Interactive set lets you set configuration options interactively.

Install Interactive set using the /script command:

/script install iset.pl

When you use the /iset command a buffer with all options is opened. Navigate the list by using your arrow keys or PgUp or PgDn .

Highmon is a highlight monitor. It creates a buffer containing all highlighted messages in other buffers. This script is great for quickly reviewing all my mentions to see if something important has come up.

Install Highmon using the /script command:

/script install highmon.pl

I keep a small Highmon buffer at the top of my WeeChat window at all times. This way, I just have to glance at the WeeChat window to see I have any new important highlights.

To do this, split your window into two horizontal splits; One small at the top for Highmon, and one large below for your chat buffers:

/window splith 20 /buffer highmon /window 1

Save this layout to disk to persist it during restarts:

/layout save

Slacklog (written by fellow thoughtbotter Pat Brisbin) pulls chat history from the Slack API and prints it into the buffer as backlog whenever you join a new channel.

Since Slacklog is not yet published on the WeeChat website you have to install it from your shell:

curl https://raw.githubusercontent.com/thoughtbot/weechat-slacklog/master/slacklog.rb -o ~/.weechat/ruby/slacklog.rb

Load it in WeeChat:

/script load slacklog.rb

Create an API token on the Slack API website and configure Slacklog with your Slack server and API token:

/set plugins.var.ruby.slacklog.servers NAME /set plugins.var.ruby.slacklog.NAME.api_token TOKEN

Where:

NAME is the name you gave your Slack IRC server.

is the name you gave your Slack IRC server. TOKEN is the token as specified on the Slack API website.

By default, Slacklog pulls in the 100 latest messages. If you want to change this number you can set it to a value between 1 and 1000 using this option:

/set plugins.var.ruby.slacklog.count 500

Colorize Lines lets me color messages in the same color as the nicknames of the users that posted them. This helps me distinguish between messages more easily.

Install Colorize Lines using the /script command:

/script install colorize_lines.pl

Messages posted from now on will be colorized.

Scripts can be auto loaded by WeeChat on startup. To tell WeeChat to auto load a script use the /script command: