One Config, One Watchdog: Rebuilding My ii IRC Setup Again
I’ve written about ii (IRC it) twice already. Back in 2018 I covered the basics: stunnel for TLS, a tiny shell script to connect and join channels, multitail to watch several at once. In 2025 I rewrote the whole thing to stop manually sleeping and praying, with proper connection checks, per-network authentication, and one script to start, stop, and inspect everything.
That second version served me well for over a year, and it’s also the one still published in my dotfiles. But living with it daily turned up a problem neither post mentioned, and fixing it properly meant touching almost every part of the setup again.
The problem: two scripts, one truth, duplicated
ii-start managed the networks, channels, and connections. ii-sway, the desktop integration bound to sway keybinds, had its own hardcoded idea of which channel lived on which network, because it needed that mapping to send a message or tail a log file to the right place. Every time I wanted to add a channel, I was editing both files and hoping I’d kept them in sync. I hadn’t always.
The fix was to stop treating that as two problems. Both scripts now source a single file, ~/.config/ii/networks.conf, which defines the networks, their channels, their display names, and the order to iterate them in:
declare -A SERVERS=(
["lb"]="127.0.0.1:6698:your_nick"
["sn"]="127.0.0.1:6697:your_nick"
["of"]="127.0.0.1:6699:your_nick"
)
declare -A CHANNELS=(
["lb"]="#archlinux #sway #bash"
["sn"]="#f1"
["of"]="#wayland"
)
declare -A NETWORK_NAMES=(
["lb"]="Libera Chat"
["sn"]="Snoonet"
["of"]="OFTC"
)
NETWORK_ORDER=(lb sn of)
Adding a channel is now a one-line edit in one file, and ii-start, ii-sway, and the new list-channels subcommand all pick it up without anything else changing.
ii-sway stopped hardcoding anything
With the config centralised, ii-sway could stop being a case statement with channel names baked into it. It now builds a channel → network lookup from networks.conf at startup and resolves whatever channel name it’s given against that, whether typed with or without the leading #:
declare -A CHANNEL_NETWORK=()
for net in "${NETWORK_ORDER[@]}"; do
for ch in ${CHANNELS[$net]}; do
CHANNEL_NETWORK["$ch"]="$net"
done
done
resolve_channel() {
local want="$1"
for ch in "${!CHANNEL_NETWORK[@]}"; do
if [[ "$ch" == "$want" || "${ch#\#}" == "$want" ]]; then
echo "${CHANNEL_NETWORK[$ch]} $ch"
return 0
fi
done
return 1
}
That one function is what lets compose (a wofi prompt to fire off a quick message to any channel) and monitor (tail a single channel’s log in its own kitty window) work against every configured channel instead of a fixed list. My sway keybinds for it now look like this:
bindsym $mod+i exec ~/bin/ii-sway chat
bindsym $mod+Shift+i exec ~/bin/ii-sway quick-chat
bindsym $mod+Ctrl+i exec ~/bin/ii-sway compose
bindsym $mod+Alt+i exec ~/bin/ii-sway status
# Individual IRC channel monitoring (names match networks.conf, # optional)
bindsym $mod+F1 exec ~/bin/ii-sway monitor archlinux
bindsym $mod+F2 exec ~/bin/ii-sway monitor sway
bindsym $mod+F3 exec ~/bin/ii-sway monitor bash
bindsym $mod+F4 exec ~/bin/ii-sway monitor wayland
bindsym $mod+F5 exec ~/bin/ii-sway monitor f1
bindsym $mod+Shift+F1 exec ~/bin/ii-sway monitor
The last binding, with no channel name, opens a wofi picker listing every channel from the shared config, which is also what compose falls back to.
A sudo call that would have hung forever
The 2025 version’s check_stunnel function would try sudo systemctl start stunnel if the service wasn’t already running. That was fine when I ran ii-start by hand from a terminal, since I’d just get a password prompt. It was a landmine for anything that runs without a TTY, which is exactly what both the sway keybinds and the new watchdog service below do. An interactive sudo with no terminal to answer it just hangs, silently, forever.
check_stunnel now only checks:
check_stunnel() {
if systemctl is-active --quiet stunnel; then
echo "✓ stunnel service already running"
return 0
fi
echo "✗ stunnel service is not running"
echo " One-time fix: sudo systemctl enable --now stunnel"
return 1
}
Enabling the system-level stunnel service once, with sudo systemctl enable --now stunnel, means it starts at boot and nothing in my own scripts ever needs to ask for a password again.
The actual point of the rebuild: a watchdog that never stops
Everything above was cleanup. The reason I did any of it was to add something the 2018 and 2025 versions never had: a process that keeps IRC connected without me noticing it dropped. ii-start gained a watchdog subcommand that loops forever, and for each configured network checks whether its ii process is still alive. If it isn’t, it reconnects, re-authenticates, and rejoins that network’s channels, then carries on:
watchdog() {
local interval="${WATCHDOG_INTERVAL:-30}"
while true; do
if ! systemctl is-active --quiet stunnel; then
echo "$(date -Is) [watchdog] stunnel is down"
notify-send "ii IRC watchdog" "stunnel isn't running" --urgency=critical
else
for name in "${NETWORK_ORDER[@]}"; do
if ! pgrep -f "ii -i $IRC_HOME/$name/ " >/dev/null; then
echo "$(date -Is) [watchdog] $name is down, reconnecting..."
start_ii_instance "$name" && authenticate "$name" && join_channels "$name"
fi
done
fi
sleep "$interval"
done
}
That’s wired into a systemd user unit so it starts with my session and restarts itself if it ever dies outright:
[Unit]
Description=ii IRC auto-reconnect watchdog (networks/channels in ~/.config/ii/networks.conf)
After=network-online.target graphical-session.target
Wants=network-online.target
StartLimitIntervalSec=0
[Service]
Type=simple
ExecStart=/home/ajibola/bin/ii-start watchdog
Restart=always
RestartSec=10
[Install]
WantedBy=default.target
systemctl --user enable --now ii-irc.service and I stopped thinking about whether IRC was still connected. Mostly.
The PATH bug systemd found for me
“Mostly,” because the first time this ran, it failed on every single network with ii: command not found, over and over, exactly the kind of noisy failure a watchdog is supposed to prevent rather than cause. ii isn’t a distro package here, it’s built from the suckless source and lives at ~/git/ii/ii, which ends up on my $PATH through logic in zshenv that only runs for interactive shells.
A systemd --user service doesn’t source any of that. systemctl --user show-environment showed exactly what I’d have expected if I’d thought about it first: PATH=/usr/local/bin:/usr/bin, nothing else. The watchdog had a perfectly good connection-and-reconnect loop that could never find the one binary it existed to run.
The fix is a small resolution block at the top of ii-start, tried once at startup rather than on every reconnect attempt:
II_BIN="$(command -v ii 2>/dev/null || true)"
if [ -z "$II_BIN" ]; then
for candidate in "$HOME/git/ii/ii" "$HOME/.local/bin/ii" /usr/local/bin/ii /usr/bin/ii; do
if [ -x "$candidate" ]; then II_BIN="$candidate"; break; fi
done
fi
and using "$II_BIN" instead of the bare ii everywhere the script actually invokes it. It’s a one-line symptom of a wider rule worth remembering for anything you plan to run under systemd --user: whatever your interactive shell adds to $PATH doesn’t exist there, so resolve paths explicitly rather than trusting an environment that service will never see.
Living with it
Day to day, none of this changed how I actually talk on IRC, which is still the appeal of ii in the first place: it’s files and pipes, tail and echo, nothing more exotic than that under the hood. What changed is that I stopped being the thing keeping it connected. The watchdog starts with my session and handles drops on its own, $mod+i opens every live channel in one multitail window, $mod+F1 through $mod+F5 jump straight to a single channel I check often, and $mod+Ctrl+i fires off a one-line message through wofi without opening a chat window at all. Adding a new channel is one line in networks.conf, picked up everywhere at once.
The full scripts, the systemd unit, and an example networks.conf are in my dotfiles on GitHub: bin/ii-start, bin/ii-sway, ii/networks.conf.example, and systemd/user/ii-irc.service. Copy the example config to ~/.config/ii/networks.conf, fill in your own nick and channels, symlink the service file into ~/.config/systemd/user/, and systemctl --user enable --now ii-irc.service is the only step left.
Two rewrites in, I doubt this is the last one. But it’s the first version where IRC staying connected isn’t something I have to remember to check.