Getting Started with WeeChat

WeeChat is one of the most powerful and extensible IRC clients available today. Its name stands for "Wee Enhanced Environment for Chat," and it runs entirely in the terminal, making it lightweight, fast, and perfect for remote use over SSH. Whether you are a Linux enthusiast, a sysadmin who lives in the terminal, or simply someone who wants a fast, customizable IRC experience without the bloat of graphical applications, WeeChat is an excellent choice. This guide will walk you through everything you need to know to get WeeChat installed, configured, and connected to TwistedNET IRC.

What Is WeeChat and Why Choose It?

WeeChat is a free, open-source IRC client that runs in your terminal. First released in 2003, it has evolved into one of the most feature-rich IRC clients available on any platform. Unlike graphical clients that rely on heavy GUI frameworks, WeeChat uses the ncurses library to render its interface directly in the terminal, which means it uses minimal system resources and can run on virtually any system with a terminal emulator.

There are several compelling reasons to choose WeeChat over other IRC clients. First, it is incredibly lightweight. WeeChat typically uses less than 30 MB of RAM, compared to hundreds of megabytes or even gigabytes consumed by Electron-based chat applications. Second, it is highly extensible through plugins and scripts written in Python, Perl, Ruby, Lua, Tcl, JavaScript, PHP, and even Guile Scheme. Third, it can run on a remote server and be accessed via SSH from anywhere, giving you a persistent IRC session that never disconnects. Fourth, it supports modern IRC features through its IRCv3 implementation, including SASL authentication, server-side message history, and capability negotiation.

WeeChat also supports multiple protocols beyond IRC, including Matrix and Slack through relay plugins, making it a versatile unified chat client. But for this guide, we will focus on its core purpose: connecting to IRC networks like TwistedNET.

Installing WeeChat

WeeChat is available in the package repositories of virtually every Linux distribution, and it can also be installed on macOS and Windows. Here is how to install it on the most common platforms.

Debian / Ubuntu / Linux Mint:

sudo apt update
sudo apt install weechat

For the latest version, you can add WeeChat's official repository:

sudo mkdir -p /etc/apt/keyrings
sudo curl -fsSL https://weechat.org/dev/info/apt_key/ | sudo gpg --dearmor -o /etc/apt/keyrings/weechat.gpg
echo "deb [signed-by=/etc/apt/keyrings/weechat.gpg] https://weechat.org/ubuntu $(lsb_release -cs) main" | sudo tee /etc/apt/sources.list.d/weechat.list
sudo apt update
sudo apt install weechat

Fedora / RHEL / CentOS:

sudo dnf install weechat

Arch Linux:

sudo pacman -S weechat

macOS (using Homebrew):

brew install weechat

Windows:

On Windows, the recommended approach is to use Windows Subsystem for Linux (WSL) and then install WeeChat using the Linux instructions above. Alternatively, you can use Cygwin with the WeeChat package. Native Windows builds are also available through the WeeChat website.

First Launch and Interface Overview

Once installed, launch WeeChat by simply typing weechat in your terminal. You will be greeted by the WeeChat core buffer, which displays version information and a few helpful tips.

weechat

The WeeChat interface is divided into several areas. At the top, you will see the title bar showing the current buffer name and topic. The main area in the center is where messages appear. On the left side (if enabled), you will see the buffer list showing all open channels and private messages. At the bottom, there is the input bar where you type messages and commands, and below that, the status bar showing your nick, the current time, and other information.

All WeeChat commands are prefixed with a forward slash (/). If you type text without a leading slash, it is sent as a message to the current channel. Here are the most important commands to know right away:

/help                  - Show help for all commands
/help <command>        - Show help for a specific command
/set                   - View and change settings
/quit                  - Exit WeeChat

Connecting to TwistedNET

Now for the good part: connecting to TwistedNET's IRC servers. We will add TwistedNET as a server, configure SSL encryption, set your nickname, and connect. All of this is done through WeeChat commands.

First, add TwistedNET as a server:

/server add twistednet irc.twistednet.org/6697 -ssl

This command tells WeeChat to create a new server entry called "twistednet" that connects to irc.twistednet.org on port 6697 using SSL encryption. The -ssl flag is essential because TwistedNET requires encrypted connections to protect your privacy.

Next, set your desired nickname and fallback nicknames:

/set irc.server.twistednet.nicks "YourNick,YourNick_,YourNick__"
/set irc.server.twistednet.username "YourNick"
/set irc.server.twistednet.realname "Your Name"

If you have already registered your nickname with NickServ, configure SASL authentication so you are identified automatically on connect:

/set irc.server.twistednet.sasl_mechanism plain
/set irc.server.twistednet.sasl_username "YourNick"
/set irc.server.twistednet.sasl_password "YourPassword"

To automatically connect to TwistedNET when WeeChat starts:

/set irc.server.twistednet.autoconnect on

To automatically join channels when you connect:

/set irc.server.twistednet.autojoin "#twisted,#chat,#help"

Now connect to TwistedNET:

/connect twistednet

You should see connection messages scrolling by, and within seconds you will be connected to TwistedNET's IRC network. If you configured autojoin, you will automatically be placed in the specified channels.

Joining Channels and Basic Navigation

Once connected, you will want to join some chat rooms. Joining a channel is simple:

/join #twisted
/join #chat
/join #help

Each channel you join opens a new buffer in WeeChat. Navigating between buffers is one of the most important skills to learn. Here are the key navigation shortcuts:

Alt+Left / Alt+Right   - Switch to previous/next buffer
Alt+1 through Alt+9    - Jump to buffer number 1-9
Alt+0                  - Jump to buffer number 10
/buffer <number>       - Jump to a specific buffer number
/buffer <name>         - Jump to a buffer by name
Alt+A                  - Jump to next buffer with activity
F5 / F6                - Switch buffer list pages (if enabled)

To leave a channel:

/part #channelname
/part #channelname Goodbye everyone!

To close a buffer without parting (for example, to close a closed private message):

/close

To see who is in the current channel, use the nicklist. You can toggle the nicklist sidebar with:

/bar toggle nicklist

Or list users in the channel with:

/names

Essential Settings and Customization

WeeChat has hundreds of configurable settings. Here are the most important ones to set up for a comfortable experience.

Enable the buffer list sidebar:

/set buflist.look.enabled on

Enable mouse support: (allows clicking on buffers, scrolling, and more)

/mouse enable

Set your highlight words: (words that trigger a notification when someone says them)

/set weechat.look.highlight "YourNick,YourName"

Enable URL detection:

/set weechat.look.highlight_regex "https?://\S+"

Set the time format:

/set weechat.look.buffer_time_format "%H:%M:%S"

Smart filter to reduce join/part/quit noise:

/set irc.look.smart_filter on
/filter add irc_smart * irc_smart_filter *

This is one of the most appreciated settings. It hides join/part/quit messages from users who have not spoken recently, keeping your channel view focused on actual conversation rather than connection noise.

Save your settings:

/save

WeeChat stores all configuration in plain text files in the ~/.config/weechat/ directory (or ~/.weechat/ on older installations). You can also edit these files directly, but using the /set command is safer because it validates your input.

NickServ Registration and Authentication

Registering your nickname with NickServ ensures that nobody else can use it. This is an important step that you should complete as soon as you have connected. Learn more about NickServ and other services in our IRC commands guide.

To register your nickname for the first time:

/msg NickServ REGISTER YourPassword [email protected]

After registration, you should configure WeeChat to automatically identify with NickServ when you connect. The best method is SASL, which we configured earlier. But if SASL is not available, you can use the NickServ command method:

/set irc.server.twistednet.command "/msg NickServ IDENTIFY YourPassword"

To secure your password storage, WeeChat supports encrypted password storage using its secure data feature:

/secure passphrase MySecretPassphrase
/secure set twistednet_password YourNickServPassword
/set irc.server.twistednet.sasl_password "${sec.data.twistednet_password}"

This stores your password encrypted on disk, and WeeChat will prompt you for your passphrase when it starts, or you can configure it to read from a file.

Useful Plugins and Scripts

One of WeeChat's greatest strengths is its plugin and script ecosystem. The WeeChat script repository contains hundreds of community-contributed scripts that add functionality to your client. Here are some of the most popular and useful ones.

First, install the script manager if it is not already available:

/script

This opens the script manager buffer where you can browse, install, and update scripts. Some essential scripts include:

/script install buffers.pl       # Enhanced buffer list
/script install iset.pl          # Interactive settings editor
/script install colorize_nicks.py # Color nicknames in chat
/script install urlgrab.py       # Collect and list URLs
/script install go.py            # Quick buffer switcher
/script install autosort.py      # Auto-sort buffer list

The go.py script is particularly useful. Once installed, pressing Alt+G opens a quick-switch bar where you can type a buffer name to jump to it instantly. This is invaluable when you have many channels open.

The colorize_nicks.py script assigns a consistent color to each nickname in the channel, making it much easier to follow conversations between multiple people. Each person gets their own color, so you can visually track who is saying what.

Split Windows and Layouts

WeeChat supports split windows, allowing you to view multiple channels simultaneously. This is especially useful on large terminal windows or wide monitors.

/window splith         - Split the window horizontally
/window splitv         - Split the window vertically
/window merge          - Merge the current window
/window merge all      - Merge all windows into one

Alt+L                  - Toggle between split layouts
/window zoom           - Zoom in/out on current window

You can navigate between split windows using Alt+W followed by an arrow key, or by clicking with the mouse if mouse support is enabled. Split windows are particularly useful for monitoring a busy help channel while chatting in another, or for keeping an eye on server messages while participating in conversation.

To save your current layout so it persists across restarts:

/layout store
/save

Running WeeChat on a Remote Server via SSH

One of the most powerful use cases for WeeChat is running it on a remote server. This gives you a persistent IRC connection that stays online 24/7, even when your local machine is powered off. You simply SSH into the server whenever you want to check IRC.

The best way to achieve this is by combining WeeChat with a terminal multiplexer like tmux or screen. Here is how to set it up with tmux:

# SSH into your remote server
ssh [email protected]

# Start a new tmux session named "irc"
tmux new -s irc

# Launch WeeChat inside tmux
weechat

When you need to disconnect from SSH but keep WeeChat running, detach from tmux by pressing Ctrl+B then D. To reattach later:

ssh [email protected]
tmux attach -t irc

Your WeeChat session continues running in the background, maintaining your connection to TwistedNET, collecting messages in all your channels, and keeping your nickname registered. When you reattach, you can scroll back through everything you missed. This is the setup many experienced IRC users prefer, and it provides an always-on experience similar to what web-based clients like The Lounge offer, but with the full power of WeeChat's terminal interface.

WeeChat Relay for Mobile Access

WeeChat has a built-in relay feature that allows you to connect to your running WeeChat instance from mobile apps, web browsers, or other WeeChat instances. This means you can run WeeChat on your server and access it from your phone using apps like Glowing Bear (web) or WeeChatRN (iOS/Android).

# Set a relay password
/set relay.network.password "YourSecureRelayPassword"

# Set up a WebSocket relay for Glowing Bear
/relay add ssl.weechat 9001

# Or for a plain WebSocket relay (not recommended without HTTPS proxy)
/relay add weechat 9000

Once the relay is configured, you can open Glowing Bear in your mobile browser or install the WeeChatRN app and connect to your WeeChat instance remotely. This gives you the best of both worlds: a powerful terminal client on your server and a mobile-friendly interface on your phone, all sharing the same IRC session and message history.

Quick Reference: Essential WeeChat Commands

Here is a quick reference of the commands you will use most frequently in your day-to-day WeeChat experience. For a comprehensive list of all IRC commands, check our dedicated guide.

# Connection
/connect twistednet                     - Connect to TwistedNET
/disconnect twistednet                  - Disconnect from TwistedNET
/reconnect twistednet                   - Reconnect to TwistedNET

# Channels
/join #channel                          - Join a channel
/part #channel                          - Leave a channel
/topic New topic text                   - Set the channel topic
/names                                  - List users in channel

# Messaging
/msg NickName Hello there!              - Send a private message
/me is doing something                  - Send an action message
/notice NickName Important message      - Send a notice

# Nick Management
/nick NewNickname                       - Change your nickname
/msg NickServ IDENTIFY password         - Identify with NickServ
/whois NickName                         - View info about a user

# WeeChat
/close                                  - Close current buffer
/clear                                  - Clear current buffer
/save                                   - Save all settings
/upgrade                                - Upgrade WeeChat without disconnecting
/quit                                   - Exit WeeChat