bIRC documentation.

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, and auto-join on invite joins when you're invited.
• Reconnect — automatic with exponential backoff. A dead connection is detected by a keepalive ping, and reconnect waits for the network to come back rather than burning retries. A brief network hiccup is ridden out rather than treated as a disconnect — turn on Disconnect when the network drops in Settings › General if you'd rather have it spotted in a second or two. When a server permanently refuses the connection (banned, K-lined, unauthorized), bIRC stops retrying and shows the server's reason — reconnect manually to try again. /reconnect forces it, and /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, SCRAM-SHA-512, SCRAM-SHA-1, EXTERNAL, or OAUTHBEARER. PLAIN and SCRAM use an account name and password (pick the SCRAM variant your network advertises — Libera.Chat offers SCRAM-SHA-512). EXTERNAL uses your client certificate and needs no password. If the mechanism you picked isn't offered by the server, bIRC skips the doomed attempt and tells you exactly which mechanisms the server supports.
• CertFP — import a client certificate (a .p12) and bIRC presents it for SASL EXTERNAL / certificate fingerprint auth. The certificate and passphrase live in your Keychain, and 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). An HTTP proxy that asks for a login gets the profile's proxy username and password over Basic, Digest or NTLM. A Windows domain account is entered as DOMAIN\user or user@DOMAIN. 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, and /query <nick> opens a DM window.
• Actions & notices — /me <action> emotes, and /notice <target> <message> sends a notice.
• Messages to ops — on networks that support it (STATUSMSG), /msg @#channel <message> reaches only the channel's operators (+#channel voiced users, and so on). These show in the channel itself, marked (to @#channel) so everyone can tell they weren't seen by the whole channel.
• 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.
• Command replies — the reply to a command you type (/whois, /who, /ison, a failed command's error, …) appears in the conversation you typed it in, even if you've switched since (matched by IRCv3 labeled-response where the server supports it). Anything you didn't ask for stays in the server console. Turn it off in Settings → Messages to keep every reply in the console.
• Private notices — replies sent to you as notices (NickServ, ChanServ, a network's service bots) go to the server console by default. Settings → Messages can place them in the active conversation (shown where you're looking, not saved to that conversation's history) or in a conversation with the sender instead. An already-open conversation with the sender always shows their notices.

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 event-message visibility, keep-history) is edited as a staged draft with Save/Cancel. Modes is the channel-mode matrix. Access Lists holds the 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), and 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). Neither ever notifies for 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. Replayed lines render dimmed so they read as past. Turn off Dim replayed history in Settings → Messages to show them exactly like live messages.
• Server history — /history [count] pulls server-side history (CHATHISTORY) for the conversation. On a bouncer, missed messages replay automatically on reconnect. Turn on Show playback markers in Settings → Messages to frame each replayed block with “playback” / “end of playback” lines (off by default).
• 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, and /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. Reactions you've already added are shown checked, and picking one again removes it — on any message. Other… reacts with any emoji or text (with the system emoji picker a click away). /react / /unreact act on the most recent message. (Some networks strip reaction tags, in which case the React menu is shown disabled.)
• 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, size and line spacing (a multiple of the font size, or the font's default), and a color scheme (System, built-in, or your own). Match macOS appearance pairs a light and a dark scheme and switches between them with the system's light and dark mode.
• mIRC formatting — bold, italic, underline, and color render in the transcript. Compose with the Format menu, ⌘B/⌘I/⌘U, ⌃⇧C/⌃⇧H for the color palette, or the right-click menu. Formatting can also be stripped from incoming messages.
• Nick colors & timestamps — colored nicks in the transcript (on by default) and, with its own toggle, the same colors in the member list (off by default — away members stay dimmed), 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: press Tab to complete, press again to cycle through multiple matches (⇧Tab cycles backwards). Nicks are offered most recent speaker first, then alphabetically; Tab with nothing typed cycles through everyone in that order. A nick completed at the start of a line gets :  appended. ⇧↩ (or ⌥↩) starts a new line instead of sending — the lines go out like a multi-line paste (one message per line, or a single batch on draft/multiline networks). ↑ / ↓ recall per-window input history; in a multi-line message they move the cursor and recall history only from the first / last line, while ⌃P / ⌃N always recall. Plus 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. The System scheme can carry custom CSS too (Appearance → Edit Custom CSS), so a small tweak like alternate row colors keeps the native colors and the light/dark switching. For a rule that needs different colors per mode, use light-dark(<light>, <dark>) — the alternate row colors recipe does.

Message-type classes

Line-part classes

Text-formatting classes (mIRC)

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. For soju, bIRC can also manage the bouncer itself: in the Servers window, choose + → New soju Bouncer and enter your bouncer's address and account once. The address may also be a ws:// / wss:// WebSocket URL (use wss:// for TLS), for a bouncer that exposes only a WebSocket endpoint — the separate Port field applies unless the URL states its own port.

Selecting the bouncer shows its Networks — the upstream networks it connects to — live from the bouncer itself: list, add, edit, or remove them, and click Add beside a network (the In bIRC column) to turn it into its own server in bIRC, connected through the bouncer.

A network server added this way stores no address or password of its own — it references the bouncer, inherits its connection and authentication settings (edit the bouncer once, every network picks it up on its next reconnect), and binds to its network at registration. In the sidebar it's an ordinary server with a small link glyph: its own channels, history, notifications, and per-network settings. The bouncer itself never appears in the sidebar — it's configuration, not a chat connection. Deleting a bouncer keeps its network servers working: they absorb its settings and become standalone.

Bouncer entries need bIRC Pro. Without it, a bouncer can't be created or edited, but it can be deleted, and network servers it already created keep working. You don't need Pro to use soju: add a regular server per network with soju's username suffix as the SASL account (for example user/libera).

Already connected to soju as a plain server? Add a bouncer entry with its address and account, then add the networks you want — your existing profile keeps working, so you can retire it whenever you like. (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. Ready-made scripts are on the scripting examples page.

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, raw (every inbound line), and output (your outgoing chat text, before it's sent), 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. An output event is {kind, target, text, network} with kind one of "message" / "action" / "notice", and a raw event is {command, numeric?, params, prefix, nick, tags, raw}.

For example, to decorate every message as it's sent:

birc.on('output', function (e) {
  if (e.kind === 'message') return { text: e.text + ' — sent from bIRC' };
});

Windows & navigation

bIRC is a single source-list window: servers and their channels/queries on the left, the conversation on the right with a member list you can toggle via View → Hide Member List (⌘⌥0). Double-click a nick in the member list to open a DM with them (right-click for Whois, moderation, CTCP, file transfers and more).

Open up to three conversations side by side — right-click a conversation → Open in Split (or ⌥-click). Any conversation can also live in its own window: right-click it → Open in New Window, or click the pop-out button in its header. Its spot in the main window then shows Show and Move back. Selecting it anywhere brings that window forward, and closing the window moves it back. Detached windows return on relaunch when Reopen last session is on.

Other windows: Servers (⌘0), File Transfers (⌘⇧T), Scripts (⌘⌥S), Mentions (⌘⇧M), and Settings (⌘,). A Raw Log and Channel List are on the toolbar.

Keyboard shortcuts

Settings

Settings (⌘,) is organised into:

• General — reopen last session, ask before quitting while connected, keep-awake-while-connected, away-on-display-sleep, disconnect-when-the-network-drops, away-when-idle.
• Appearance — font, size, line spacing, and color schemes (create / import / edit / export), plus matching the macOS appearance with a light and a dark scheme, and custom CSS for the System scheme. Also whether the sidebar groups each server's conversations under Channels / Direct Messages headers (off by default).
• Messages — event-message visibility: join, part, quit, away, nick and account changes can show, hide, or (the default) show only from recent speakers and yourself — the member list always updates. Command-reply routing (replies to typed commands appear where you typed them — on by default) and private-notice placement (server console / active conversation / a conversation with the sender). Also topic-on-join lines (off by default — the topic always shows in the header bar, and /topic prints it on demand), nick colors (transcript and member list, each with its own toggle), timestamps, date separators, unread marker, strip-formatting, highlight color, highlight-spam detection.
• Input — spell-check, Apple Intelligence Writing Tools (off by default), 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.
• bIRC Pro — your Pro status, the Pro feature list, and Restore Purchases.

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