Setting up WeeChat on OS X

Posted on 2014-11-11

Hanging out in IRC channels is a great way to learn the nooks and crannies of
programming languages and tools. I’ve tried several desktop IRC clients in the
past, but each one felt more like a nuisance, and eventually I’d stop using IRC
entirely until I came across the next app to try. Since these days I spend a lot of time
inside a tmux session, I’d much rather have IRC
in my terminal, rather than granting valuable screen real-estate (and, more importantly,
attention) to a separate native app.

The main contenders for terminal IRC seem to be irssi
and WeeChat.
I went with WeeChat, since it seemed to be the more modern and actively
maintained of the two. Both are popular options, and you probably can’t go wrong
with irssi either. Even though WeeChat is allegedly the more “user-friendly” client, I
encountered some bumps getting it set up on OS X (Yosemite)– hence this post.
A lot of what I learned was cribbed from the WeeChat quickstart
guide, so I
highly recommend reading through it if, like me, you’re just getting started.

Below is a screenshot of what you’ll end up with at the end of this post. Note
that I’m using custom terminal colours,
so YMMV on that front. Also, the culmination of my experimentation is
on github if you want to
skip these ramblings.

Installation

If you’re interested in a command-line IRC program for OS X, I’m going to assume
you have Homebrew installed, or at least know how to get it.
Install WeeChat with:

brew install weechat --with-perl --with-python

The --with-perl --with-python flags are important if you want to use WeeChat
scripts, since most of the popular ones are written
in one of those two languages. You can also add --with-lua and --with-ruby
if you think you’ll need plugins from those languages.

Running WeeChat

You start WeeChat, predictably enough, by entering weechat in your terminal
app of choice. After that, things can be a bit bewildering. The first time run doesn’t give
you any hints for how to connect to a server, configure the program, or
do much of anything. The magic command to get you started is /help. This lists
the available commands used to interact with WeeChat. Each command should be
prefixed with a /, and you can (and should) run /help {command} to get more
information about the important ones.

A few essential commands and hotkeys:

/quit exits WeeChat

/set is used to read & write your WeeChat configuration. The contents of
/help set is one of the first things you should read as a new WeeChat user.

/save saves your current configuration to various config files, in
~/.weechat by default. Out of the box, WeeChat also saves your up-to-date
configuration any time you exit the program.

/close closes the current “buffer”. If you’re familiar with vim, WeeChat’s
concept of buffers is similar. Otherwise, just assume that a buffer maps
one-to-one to a connected IRC channel for now.

/join {channel} joins an IRC channel (once you’re connected to a server;
more on that in the next section).

Use Alt + arrow keys to switch buffers

Use PageUp/PageDown to scroll text in the current buffer

Connecting to Freenode

Freenode is where the majority of programming IRC talk
happens, so let’s connect to it. WeeChat comes with basic Freenode
configuration out of the box, which is nice and convenient. I’m going to assume
you have a Freenode account (or will connect without one); registering there is
outside the scope of this post.

You can run /set irc.server.freenode.* to see all of the available freenode
settings. I configured the following settings (substitute your own values where
applicable):

I’m a little fuzzy on whether SASL
authentication helps much if you’re already
connecting over SSL, but I turned it on anyways. This
post has more
information on that.

Once you’ve entered these settings, /quit and restart WeeChat, and on the next
startup WeeChat should try and auto-connect to Freenode.

SSL Certificate Errors

One glitch I hit pretty early was that OS X apparently doesn’t ship with the SSL CA
certificates needed to connect to Freenode over SSL. Of course, you could
leave SSL off, but after following the news for the last few years, that
just seems irresponsible. The error message I got looked like this:

Back in WeeChat, the following command will point to the CA file that you just
created:

/set weechat.network.gnutls_ca_file "/usr/share/curl/ca-bundle.crt"

Now restart WeeChat and it should finally connect to Freenode successfully!

Securing your password

If you followed the connection instructions above, your IRC password is now
stored in plain text in your WeeChat config file, which is, um, not ideal.
Fortunately, WeeChat has the /secure command, which lets you store sensitive
information in an encrypted local file, and will prompt you
for a password to unlock it on startup. The user guide has a nice
section on using this
feature.

WeeChat Scripts

You can customize and extend WeeChat by installing various “scripts”. It comes with
a built-in script manager (try /help script), and tons of
scripts are available for installation. As mentioned
earlier, you need to have support for a plugin’s language (generally perl or
python) compiled in for them to be installable.

The buffers.pl and
iset.pl plugins are essential.
Assuming you built WeeChat with perl support, you can install them
with the following commands:

Buffers.pl gives you an always-visible list of the buffers that you have open
(in my opinion this should be built-in to WeeChat). You can tweak it a bit if
you want, but it works great out of the box. iset is a nice UI for interactively
editing your WeeChat configuration, rather than entering verbose /set commands
every time you want to change something. Install it and read /help iset for more
details.

Filtering out join/leaves. In many IRC channels the actual conversation can
be drowned out by tons of join and leave messages. WeeChat has a nice way of
intelligently filtering these out as needed; run
/filter add irc_smart * irc_smart_filter * to activate it.

WeeChat lets you easily customize your keyboard hotkeys. I’m a complete hotkey
junkie, so this is one of my favourite features. Read /help key for more info.

Conclusion

It’s only been two weeks, but I’m really enjoying WeeChat so far. For the first
time, having IRC open feels natural and unobtrusive to my workflow. While the
initial learning curve can be quite steep, once you understand how things are
laid out WeeChat is really fun to explore and customize. My weechat
config is online if you
want to crib some settings. And if you have questions or need help, #weechat
on freenode is a great place to ask.