bIRC documentation.

bIRC is a native macOS IRC client with IRCv3 support. This page is a complete tour. In the app, type /help for the command list or /help <command> for one command, and press ⌘? to open this page.

Getting started

Open the Servers window (the toolbar button, or ⌘0), add a server, choose a nick, and connect. bIRC registers, joins your auto-join channels, and remembers your servers, identities, and window layout between launches. Reopen the main window any time with ⌘1.

A server you've opened lives in the source list on the left. Disconnect keeps the session and its windows (offline, with a Reconnect banner); Close takes it offline and hides it from the list (reopen it from the Servers window — history is kept); Delete removes a conversation and purges its stored history. When you quit, every live connection sends a graceful QUIT; on launch your open servers come back, and the ones you flagged Connect on launch reconnect automatically.

Connecting & networks

Each server is a profile in the Servers window. Connection options (edited in the profile, applied on the next reconnect):

• TLS — connect over TLS directly, or use STARTTLS to upgrade a plaintext connection in-band. A minimum TLS version can be set.
• WebSocket — for a network that exposes only a ws:// / wss:// endpoint, paste that URL as the server address (use wss:// for TLS).
• STS — if a network advertises Strict Transport Security, bIRC upgrades to TLS automatically and remembers the secure port for the policy's lifetime.
• Alternate servers — list extra host:port entries; bIRC tries them in order and sticks to whichever one works.
• IP protocol — Automatic (Happy Eyeballs), IPv4-only, or IPv6-only.
• Auto-join — channels (with keys, stored in your Keychain) join on connect and every reconnect. Optional join pacing staggers them; auto-join on invite joins when you're invited.
• Reconnect — automatic with exponential backoff; a dropped network is detected in a second or two and reconnect waits for the network to return rather than burning retries. /reconnect forces it; /quit goes offline without reconnecting.

When your Mac sleeps, bIRC sends a graceful QUIT to every live connection and reconnects exactly those on wake (the per-server sleep quit message sets the reason). Optionally it can also mark you away when your display sleeps, and keep the Mac awake while connected or during transfers.

Identity & authentication

• Nick & alternates — a primary nick plus a list of fallbacks tried on a collision. bIRC can keep trying to regain your primary nick on a timer. /nick <newnick> changes it live.
• Username & real name — the ident and gecos; /setname <real name> updates the real name live (IRCv3 SETNAME).
• SASL — Off, PLAIN, SCRAM-SHA-256, or EXTERNAL. PLAIN and SCRAM use an account name and password; EXTERNAL uses your client certificate and needs no password.
• CertFP — import a client certificate (a .p12); bIRC presents it for SASL EXTERNAL / certificate fingerprint auth. The certificate and passphrase live in your Keychain; the fingerprint is stored alongside the profile.
• OAuth (OAUTHBEARER) — sign in with an OAuth 2.0 token (the mechanism soju and SSO deployments use). bIRC does the auth-code + PKCE flow in your browser and refreshes the token silently; you re-authorize only when a refresh fails.
• Away — /away [message] marks you away, /back clears it. An optional away nick switches automatically while away, and bIRC can auto-return you when you speak.
• Account registration — /register [account] [email] <password> and /verify [account] <code> on networks that support it.

Services like NickServ are reached with ordinary messages, e.g. /msg NickServ IDENTIFY <password>. Per-server connect commands run automatically on every registration.

Privacy & proxies

Any server can connect through a proxy (set per profile): SOCKS5, HTTP CONNECT, SOCKS4, or Automatic (your Mac's system SOCKS proxy). Hostnames resolve at the proxy, so your DNS lookups don't leak — essential for Tor (there's a built-in Tor preset for SOCKS5 on 127.0.0.1:9050). Out-of-band fetches (inline images, link previews, file uploads, DCC over a proxy) go through the same per-profile proxy, and fail closed rather than leak if the proxy can't be used.

Channels, queries & messages

• Join / leave — /join #channel [key] and /part [channel] [reason]. /cycle (aka /hop, /rejoin) leaves and rejoins.
• Private messages — /msg <target> <message> sends without opening a window; /query <nick> opens a DM window.
• Actions & notices — /me <action> emotes; /notice <target> <message> sends a notice.
• To every channel — /amsg <message> and /ame <action> fan out to every channel you're in.
• Across every connection — /allserv <command> runs any command on every open server (e.g. /allserv away lunch).
• CTCP — /ctcp <target> <command> (VERSION, TIME, PING, …); /ping <nick> measures round-trip time.

Pasting multiple lines sends one message per line — as a single coherent batch on networks that support draft/multiline. A large paste asks first (the threshold is in Settings), and on a server that hosts files it can offer to upload the text and post a link instead of flooding the channel (see FILEHOST).

Command reference

Every built-in slash command, grouped as in the app's /help. Aliases are shown in parentheses. Anything bIRC doesn't recognise as a built-in is sent to the server as-is; /quote (aka /raw) sends a raw IRC line, and /quote HELP asks the server for its own help.

Messaging & windows

Channel membership

Modes

Identity & presence

Queries

Operator & server

Reactions, redaction & metadata

Ignore & silence

Encryption (FiSH)

Client & connection

Moderation & modes

The membership shortcuts (/op, /deop, /voice, /devoice, /ban, /unban) take one or more nicks/masks and apply to the current channel; /mode is the escape hatch for anything else, parsed from what the server advertises in ISUPPORT (no hardcoded mode letters). The same actions are on the nick-list right-click menu under Moderation.

Channel Properties (the channel right-click, or ⌘I) is one sheet with three tabs: General (topic, join-on-connect, password, notification level, highlight and join/part visibility, keep-history) edited as a staged draft with Save/Cancel; Modes (the channel-mode matrix); and Access Lists (ban / exception / invite editors, loaded on demand).

Ignore & highlight

• Ignore — /ignore [nick|mask] [private|channel|notice|ctcp …] ignores a user, optionally only for certain message categories; with no argument it lists current ignores. Manage it live in the Ignored toolbar popover. Ignores are local and persist per profile; /silence is the server-side equivalent.
• Highlights — your nick always highlights; add custom keywords with a scope (everywhere / only in some channels / everywhere except some) and either whole-word or regular-expression matching. Exclude words veto a highlight even when your nick appears. Edited in the profile's Alerts pane.
• Highlight-spam veto — a message that mass-pings the channel won't highlight you (on by default).
• Inbound flood auto-ignore — a user flooding you is temporarily dropped, with a one-time notice.

Message encryption (FiSH)

bIRC speaks FiSH/blowcrypt (Blowfish ECB) for per-conversation encryption, interoperable with other FiSH clients. Set a shared key with /key [target] <key>, or do an automatic DH1080 key exchange in a query with /keyx. /showkey shows whether a conversation is encrypted and /delkey removes the key. There's also an Encryption submenu on a channel/DM. Keys are stored in your Keychain and survive reconnects. A lock icon marks an encrypted conversation in the sidebar.

File transfers (DCC)

Send and receive files and chat peer-to-peer with /dcc (send / chat / get / close / list), or use the nick-list right-click and drag-and-drop. The peer defaults to the current DM partner. Because bIRC is sandboxed, sending and saving use the native file panels.

• Passive (reverse) DCC — works for both send and chat, so transfers go through when one side is behind NAT.
• RESUME — interrupted downloads and uploads resume from where they stopped.
• Auto-accept — offers from trusted nick/host masks save automatically to a folder you choose; everything else prompts.
• Advertised address — for active offers, pick how your address is found: your local interface, a manual IP, an external-IP lookup service, or Query router (NAT-PMP / PCP / UPnP) which forwards a port and learns your public IP so offers work behind NAT.
• Over a proxy — DCC can route through the profile's proxy (SOCKS5 BIND for listening); there's a per-profile opt-out to send DCC directly while everything else stays proxied. Going direct reveals your real IP.

File transfers appear in the File Transfers window (⌘⇧T); DCC chats appear as ordinary conversations in the sidebar.

File & paste uploads (FILEHOST)

On a server or bouncer that advertises FILEHOST (the IRCv3 draft/FILEHOST or soju's soju.im/FILEHOST), the paperclip in a channel/DM composer uploads a file to the server's host and inserts the returned link — usable in channels, unlike peer-to-peer DCC. A large paste can also be uploaded as a link instead of flooding. If the button is dimmed, click it for the reason (no token, an insecure host on a TLS connection, or a SASL mechanism without a usable HTTP credential). Uploads go through the profile's proxy and refuse plain http on an encrypted connection.

Notifications & mentions

There are two layers:

• In-app indicators — sidebar unread counts and highlight coloring. Always on, no permission needed.
• macOS notifications — Notification Center banners and the Dock badge. Two independent switches (Settings → Notifications), both off by default: one for mentions, DMs and nicks coming online, one for services notices and WALLOPS. Turning on either asks macOS for permission. Per-event system sounds are configurable.

Each switch then narrows down: a per-network mute (profile Alerts pane), then per-channel Mute or Notify for all messages (the channel menu and Channel Properties). You're notified for DMs, highlights and nicks coming online (the first switch), and — when its own switch is on — services notices (NickServ / ChanServ) and operator WALLOPS addressed to you (the second); never for messages in a conversation you're actively viewing.

The Mentions inbox (⌘⇧M) is a persistent, cross-network list of every highlight, newest first, click-to-reveal — it opens even with every server disconnected. The Notify List (/monitor, or the Notify List popover) watches nicks and notifies you when they come online, using IRCv3 MONITOR where available and ISON polling otherwise.

History, search & logs

• Keep message history (per profile, on by default) — stores messages in a local searchable database so conversations come back with scrollback after a restart, even offline.
• Scrollback — scroll up, use the sidebar's Load Earlier Messages, or /loadlog [count] to page older messages back in.
• Server history — /history [count] pulls server-side history (CHATHISTORY) for the conversation; on a bouncer, missed messages replay automatically on reconnect.
• Search — ⌘⇧F searches stored history across this conversation, this network, or all networks (offline-capable). ⌘F finds within the loaded transcript.
• Clear — /clear (or ⌘K) clears the current transcript; /clearall clears every window. This is display-only — stored history is untouched.
• Plain-text logs — a separate, optional per-profile feature that writes greppable .log files to disk (continuous or daily). It's distinct from the history database and off by default. There's also an on-demand Export Log….

Server profiles sync across your Macs via iCloud (on by default); passwords and keys ride iCloud Keychain. The local history database stays on each Mac.

Reactions, replies & metadata

• Reactions — right-click a message to react, or /react / /unreact the most recent one. (Some networks strip reaction tags, in which case the option is hidden.)
• Replies — right-click → Reply threads your next message to that one; a quote chip shows above the composer, and clicking a reply quote jumps to its parent (with a Back button).
• Redaction — /redact deletes your last message where the network supports it; redacted lines are struck and marked, not silently removed.
• Metadata — view and edit IRCv3 metadata (avatar, color, pronouns, status, …) in the metadata panel; profiles show in WHOIS and the nick list.
• Typing indicators — sent and shown where the network supports them (per-profile toggle).

Appearance, media & input

• Themes — choose the transcript font and size, and a color scheme (System, built-in, or your own).
• mIRC formatting — bold, italic, underline, and color render in the transcript; compose with ⌘B/⌘I/⌘U or the right-click menu, or strip formatting from messages.
• Nick colors & timestamps — colored nicks (on by default), a configurable timestamp format, date-change separators, and an unread marker.
• Inline media — images, video, and OpenGraph link previews can render in the transcript. All are off by default (they fetch remote content) and, when on, load through the profile's proxy over https only.
• Emoji — type :shortcode: for an emoji picker and auto-replace, with a skin-tone preference.
• Input — tab-completion of nicks and commands, per-window input history, spell-check underline, and copy-on-select.

Custom transcript CSS

A custom color scheme can carry your own CSS, layered over the transcript — sanitized to safe visual properties and scoped to the message log (no layout, positioning, or remote resources). Edit it in the scheme editor's Custom CSS tab, which shows this same reference and a few ready-made recipes.

Message-type classes

Line-part classes

Theme variables

Use them with var(--birc-accent) — e.g. a rail on mentions: .highlight { border-left: 3px solid var(--birc-accent); padding-left: 8px; }

Bouncers (soju)

bIRC works with any bouncer, and ZNC/soju replay is handled automatically. With soju specifically, the server row's right-click offers soju Manager… to list, add, edit, and remove the bouncer's upstream networks from inside the app. (Note: a ZNC older than 1.10.0 may strip message IDs, which disables reactions, reply-jump, and redaction on that connection.)

Scripting

Extend bIRC with sandboxed JavaScript: observe events, register your own /commands, rewrite or suppress incoming and outgoing messages, run timers, persist state, add tab-completions, and do proxied https lookups — through the birc API. Scripts are plain .js files managed in the Scripts window (⌘⌥S), enabled globally or per profile, with import/export and a save-time safety check. They run in an isolated context with no file or ambient network access — only the birc object and a console.

Sending & printing

Hooks & timers

Reading the connection

Properties (live, for the triggering connection)

Storage, network & other connections

Events

birc.on(type, fn) takes one of: message, notice, action, join, part, quit, kick, nickchange, mode, topic, invite, ctcp, ctcpreply, away, connect, disconnect, and raw (every inbound line), plus the lifecycle load / unload. The event object carries the relevant of nick, user, host, prefix, target, channel, text, network, account, realname, reason, params, tags, isMe, and isBacklog; outbound message hooks also get kind ("message" / "action" / "notice"), and a raw event is {command, numeric?, params, prefix, nick, tags, raw}.

Windows & navigation

bIRC is a single source-list window: servers and their channels/queries on the left, the conversation on the right with an optional member list. Open up to three conversations side by side — right-click a conversation → Open in Split (or ⌥-click). Other windows: Servers (⌘0), File Transfers (⌘⇧T), Scripts (⌘⌥S), Mentions (⌘⇧M), and Settings (⌘,). A Raw Log and Channel List are on the toolbar. Move around entirely from the keyboard — see the shortcuts below.

Keyboard shortcuts

Settings

Settings (⌘,) is organised into:

• General — reopen last session, keep-awake-while-connected, away-on-display-sleep, away-when-idle.
• bIRC Pro — your Pro status, the Pro feature list, and Restore Purchases.
• Appearance — font, size, and color schemes (create / import / edit / export).
• Messages — join/part visibility (all / hide / smart), nick colors, timestamps, date separators, unread marker, strip-formatting, highlight color, highlight-spam detection.
• Input — spell-check, copy-on-select, paste thresholds, transcript buffer size, emoji completion and skin tone.
• Commands — command aliases and text auto-replace, plus the /clearall scope.
• Notifications — the two notification switches (mentions/DMs/online nicks, and services notices/WALLOPS) and per-event sounds.
• File Transfers — DCC advertised address and port range, passive mode, auto-accept and trusted senders, keep-awake-during-transfers.
• Privacy — remote content toggles (network icon, avatars, inline images/video, link previews — all off by default) and inbound-flood auto-ignore.
• iCloud — sync server profiles and identities across your Macs (on by default), and remove bIRC's data from iCloud.

Per-server options (identity, SASL, proxy, encoding, auto-join, automation, alerts, advanced) live in the Servers window's profile editor, not here.