bIRC documentation.
bIRC is a native macOS IRC client with IRCv3 support. 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 (usewss://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.
/reconnectforces it, and/quitgoes 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,/backclears 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 (+#channelvoiced 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 IRCv3labeled-responsewhere 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
| /msg | Send a private message to a nick or channel without opening a window. |
| /query | Open a private-message window with a nick (optionally send a line). |
| /me | Send an action (emote) to the current conversation. |
| /slap | Slap someone around a bit with a large trout (a classic mIRC action). |
| /amsg | Send a message to every channel you're in. |
| /ame | Send an action to every channel you're in. |
| /notice | Send a NOTICE (no automatic reply) to a target. |
| /ctcp | Send a CTCP request (VERSION, TIME, PING, …) to a target. |
| /ctcpreply | Send a CTCP reply to a target. |
| /ping | Measure round-trip time to a user via CTCP PING. |
| /dcc | Direct client-to-client file transfer and chat (send / chat / get / close / list). |
Channel membership
| /join (/j) | Join a channel, optionally with its key. |
| /part (/leave) | Leave a channel. |
| /topic | Show or set the current channel's topic. |
| /names | List the members of a channel. |
| /invite | Invite a user to a channel. |
| /kick | Remove a user from the current channel. |
| /kickban (/kb) | Ban then kick a user from the current channel. |
| /cycle (/hop, /rejoin) | Leave and immediately rejoin a channel. |
| /knock | Ask for an invite to an invite-only channel. |
| /rename | Rename the current channel (where supported). |
Modes
| /mode | View or change channel and user modes. |
| /op · /deop | Give or remove channel-operator status (+o / -o). |
| /voice · /devoice | Give or remove voice (+v / -v). |
| /ban · /unban | Add or remove a ban (+b / -b) in the current channel. |
| /banaccount (/accountban) | Ban a user by their account (IRCv3 account-extban), where the network supports it. |
Identity & presence
| /nick | Change your nickname. |
| /away · /back | Mark yourself away (with an optional reason), or clear it. |
| /setname | Change your real name (gecos). |
Queries
| /whois | Look up information about a user. |
| /whowas | Look up a user who has signed off. |
| /who | List users matching a mask. |
| /ison | Check whether one or more nicks are online. |
| /userhost | Get the hostmask of one or more nicks. |
| /monitor (/notify, /watch) | Watch nicks for online/offline status — the Notify List (+ / - / list / status / clear). |
| /list | Browse the server's channel list. |
Operator & server
| /register · /verify | Register an account with the network, then verify it. |
| /oper | Authenticate as an IRC operator. |
| /kill | Forcibly disconnect a user (operator only). |
| /wallops | Broadcast a WALLOPS message (operator only). |
| /motd | Show the server's message of the day. |
| /version · /time | Show the server's version or local time. |
| /lusers | Show user and server counts. |
| /admin · /info | Show the server's admin contact or software info. |
| /links | List the servers on the network. |
| /stats | Query server statistics. |
Reactions, redaction & metadata
| /react · /unreact | Add or remove an emoji/text reaction on the most recent message. |
| /redact (/delete) | Redact your last message (struck through and marked, not removed). |
| /metadata | Open the metadata panel, or run a raw METADATA command. |
| /isupport | Show the server's advertised ISUPPORT tokens. |
Ignore & silence
| /ignore | Locally ignore a nick or mask (optionally by category), or list current ignores. |
| /unignore | Stop ignoring a user. |
| /silence | Server-side ignore, if the network supports SILENCE. |
Encryption (FiSH)
| /key (/setkey) | Set the FiSH encryption key for a conversation. |
| /delkey | Remove the FiSH key for a conversation. |
| /showkey | Show whether a conversation is encrypted. |
| /keyx | Start a DH1080 key exchange (queries only). |
Client & connection
| /help | List commands, or show help for one command. |
| /clear · /clearall | Clear this window's transcript, or every window's. |
| /close | Close this window, or a named channel or DM (/close #channel, /close nick) — history is kept. |
| /closeall | Close every DM and channel window on this server — /closeall dms or /closeall channels to close just those. |
| /allserv | Run a command on every connection. |
| /cap | Show the IRCv3 capabilities negotiated on this connection. |
| /history | Load server-side history (CHATHISTORY) for this conversation. |
| /loadlog (/loadlogs) | Load earlier messages from stored history. |
| /quit (/disconnect) | Disconnect from the server (the session stays open). |
| /reconnect | Reconnect the current server. |
| /connect (/server) | Reconnect this server (a different host ⇒ use the Servers window). |
| /quote (/raw) | Send a raw IRC command to the server. |
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 —/silenceis 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. 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. Drop files on a conversation or paste an image to upload them. bIRC asks first, and in a DM a drop can go by DCC instead. 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 —
⌘⇧Fsearches stored history across this conversation, this network, or all networks (offline-capable).⌘Ffinds within the loaded transcript. - Clear —
/clear(or⌘K) clears the current transcript, and/clearallclears every window. This is display-only — stored history is untouched. - Plain-text logs — a separate, optional per-profile feature that writes greppable
.logfiles 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//unreactact 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 —
/redactdeletes 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/⌃⇧Hfor 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
Tabto complete, press again to cycle through multiple matches (⇧Tabcycles backwards). Nicks are offered most recent speaker first, then alphabetically.Tabwith 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 ondraft/multilinenetworks).↑/↓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/⌃Nalways 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 and layout properties and scoped to the message log (no positioning, generated content, 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
| .privmsg · .own | A message from someone · a message you sent. |
| .notice · .action | A NOTICE · a /me action. |
| .join · .part · .quit · .kick | Membership lines. |
| .mode · .nick · .topic | A mode change · a nick change · a topic line. |
| .server · .error | Server/status lines · error lines. |
| .highlight | A line that mentions you. |
| .history | Replayed history lines (dimmed by default). |
Line-part classes
| .line | Any transcript line (the whole row). |
| .t · .m | The timestamp · everything after it: the author and the message text. |
| .t-repeat | A timestamp hidden because it reads the same as the line above's (Hide repeated timestamps). |
| .author · .text | The author part of a message, notice or /me line (<nick>, -nick-, * nick) · the message text alone. |
| .author-nick | The nick alone inside .author (without its < >, - - or /me marker). |
| .sender · .url | The sender's nick in a message line · a web link. |
| .glyph | The marker that starts an event or /me line (→, ←, • — or * with mIRC-style markers). |
| .reply · .oper · .reactions | A quoted-reply preview · the operator pill · reaction chips. |
| .react · .redacted | One reaction chip · a redacted message's placeholder. |
| .card · .card-title · .card-desc | A link-preview card and its title / description. |
| .card-thumb · .card-body · .card-site | A link card's thumbnail · its text (site, title and description) · its site name. |
| .img-load · .inline-img | An inline image's click-to-load link · the loaded image. |
| .vid-load · .inline-video | An inline video's click-to-load link · the loaded player. |
| .daychange | The date-change divider. |
| .marker | The unread divider: a line drawn as border-top, in the mention color. |
Text-formatting classes (mIRC)
| .irc-bold · .irc-italic · .irc-underline | Text sent as bold · italic · underlined. |
| .irc-strikethrough · .irc-monospace | Text sent struck through · monospace. |
| .irc-fg0 … .irc-fg98 | Text colors — one class per palette color. |
| .irc-bg0 … .irc-bg98 | Background colors — one class per palette color. |
Theme variables
| --birc-bg · --birc-text | Background · default text. |
| --birc-accent · --birc-link | Your scheme's accent · link color (the accent, unless your scheme sets its own). |
| --birc-meta · --birc-highlight | Muted (timestamp) color · mention color. |
| --birc-join · --birc-notice · --birc-action | Join/part/quit · notice · action colors. |
| --birc-server · --birc-kick | Server / status lines · kick and error lines. |
| --birc-mode · --birc-topic | Mode and nick-change lines · topic lines. |
| --birc-oper-bg · --birc-reply-border | The operator pill's background · a quoted reply's left border. |
| --birc-card-border · --birc-card-hover | A link card's border · its background on hover. |
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. Scripting needs bIRC Pro.
Sending & printing
| birc.say(target, text) | Send a message. It shows in the window like a typed one, but output hooks don't see it. |
| birc.action(target, text) | Send a /me action, shown the same way. |
| birc.notice(target, text) | Send a notice. It shows in the window like a typed one, but output hooks don't see it. |
| birc.command(line) | Run a command as if typed in the connection's active window (the leading / is optional). Built-in commands and aliases work. Script commands don't run this way, so a script can't loop. bIRC reports an error in the script's console instead. |
| birc.raw(line) | Send a raw IRC line, like /quote. |
| birc.print(text) | Print a line locally, in the connection's active window. |
| birc.printTo(target, text) | Print a line in a channel or query window, opening it if needed. |
Hooks & timers
| birc.on(type, fn) | Run fn(event) for an inbound event (types below) before bIRC handles it. Return birc.EAT, false or {eat: true} to hide it. A message, action, notice, CTCP or invite is then dropped: nothing is shown, stored or notified. For join, part, quit, kick, nickchange, mode, topic, away, connect and disconnect, only the line and its sound go: bIRC still processes the event (the member list, topic, your nick, the connection, connect commands, auto-perform). A raw hook only observes. EAT does nothing there. Return {text: "…"} to replace the text of a message, action or notice, which is then shown, stored and logged. Every hook gets the original event. The first drop wins, otherwise the last {text}. To change what's sent, use output. |
| birc.on('output', fn) | Rewrite or suppress your outgoing chat text: messages, /me actions and notices, including /amsg, /ame and multi-line pastes. fn({kind, target, text, network}). Return {text: "…"} to change what's sent, or birc.EAT / false to cancel. Each hook sees the text the one before it returned. Script sends aren't filtered, so a hook can't loop. |
| birc.on('load' | 'unload', fn) | load runs after the script's code, each time it loads (at launch, when turned on, after a save). unload runs when it's turned off, saved again or removed, when Pro ends, and when bIRC quits (before it disconnects, so a script gets no disconnect on quit). |
| birc.onCommand(name, fn) | Register a /command. fn(args) gets everything typed after the name, as one string. The name is case-insensitive and can't override a built-in. If two scripts register the same name, only one of them runs. |
| birc.onComplete(fn) | Add Tab-completion candidates, offered alongside nicks. fn(word, {target?, network}) returns an array, synchronously. target is absent in the server window. |
| birc.setTimeout(fn, ms) · birc.setInterval(fn, ms) | Run fn() once after ms milliseconds, or every ms (0 to 24 hours). A timer set inside a hook keeps that hook's connection. Each returns an id. |
| birc.clearTimeout(id) · birc.clearInterval(id) | Cancel a timer. |
Reading the connection
| birc.channels() | The channels you're in on this connection. |
| birc.members(channel) | A channel's members, each with its highest mode prefix ("@alice", "bob"). |
| birc.userInfo(channel, nick) | {nick, prefix, isBot, isAway, host?, account?}, with prefix holding all of the member's mode prefixes, highest first ("@+"). null when the channel isn't open or the nick isn't in it. |
| birc.channelInfo(name) | {name, modes, modeString, count, joined, topic?}. modes maps a flag to true and a mode with an argument to that argument ({n: true, k: "key"}), modeString is "+nk key", count is the member count and joined is false once you've left. null when that channel isn't open. |
| birc.history(target [, limit]) | The last lines of an open channel or query window as {nick?, text}, from memory: 50 by default, up to 500. text is the message without the nick, or the whole line when there's no nick (joins, server lines). |
| birc.ignores() · birc.monitored() | Your ignore masks · your watched (MONITOR) nicks. |
| birc.sameNick(a, b) | Whether two names are the same user (CASEMAPPING-aware). |
| birc.strip(text) | Remove mIRC formatting codes from a string. |
| birc.info(key) | The low-level lookup behind the live properties below. |
Properties (live, for the triggering connection)
| birc.nick · birc.network · birc.server | Your nick · the network name (the server's own, else the server's name in bIRC) · the address you connect to. |
| birc.channel · birc.target · birc.topic | The active window's channel / target / topic on that connection (null when not applicable, e.g. the server window or a DCC chat — so birc.channel || birc.nick works). In an event hook, read the event's own e.channel / e.target. |
| birc.uptime.system · .app · .server | Seconds since the Mac started · since bIRC started · since this connection registered (null when it isn't connected). |
| birc.os.name · .version · .build | "macOS" · the OS version ("27.2") · its build ("26B123"). |
| birc.hw.model · .identifier | The Mac's name ("MacBook Pro (14-inch, M5 Pro)") · its model identifier ("Mac17,9"). |
| birc.cpu.name · .cores · .coreTypes | The CPU ("Apple M5 Pro") · its cores ("18") · its cores per type, fastest first ("6 Super + 12 Performance"). |
| birc.memory.total · birc.gpu.name · .cores | Installed memory in bytes · the GPU ("Apple M5 Pro") · its cores ("20"). |
| birc.disk.total · .free | The startup disk's size · its free space as Finder counts it, both in bytes. |
| birc.display.name · .resolution | The main display's name · its resolution in pixels ("2560x1440"). |
| birc.version · birc.appName · birc.website | App identity. |
| birc.apiVersion · birc.EAT | The script-API version (currently 2) · the drop-event sentinel. |
The uptime, OS and hardware values are strings, numbers included, so convert before doing math: Number(birc.uptime.app) + 60. A value this Mac doesn't have is null.
Storage, network & other connections
| birc.store.get / set / delete / keys | Per-script key/value storage that survives relaunch. Values are strings: set stores String(value), so store an object as JSON.stringify(obj). get returns null for an unset key. |
| birc.fetch(url) | GET an https URL, through the connection's proxy if it has one → Promise<{status, text}>, the body read as UTF-8. Every HTTP status resolves. It rejects with a short reason when the URL isn't https, the proxy can't be used, the body is over 256 KB, it times out (15 s idle, 30 s total) or the request fails. Off by default: turn on Allow network for the script in the Scripts window. |
| birc.to(name) | Another network, by its birc.network name (case-insensitive): .command, .say, .notice, .action and .print(text [, target]) act on it. A call reports an error when no network has that name. |
| console.log / info / warn / error | Debug output to the script's own Console (not the chat window — that's birc.print). |
Events
Every event object has type and network, and all but raw and output have isMe and isBacklog (true or false). A field that doesn't apply or isn't known is absent. nick, user, host and prefix (nick!user@host) describe who did it.
| message · action | A channel or private message · a /me. nick, user, host, prefix, target (the channel, or your nick in a private message), text, account, tags. isMe is true for your own line echoed back, isBacklog for replayed history. |
| notice | A notice, with the same fields as a message. |
| join · part · quit | Someone joined · left · quit. nick, user, host, prefix, isMe, plus channel (join and part), account and realname (join, on servers that send them) and reason (part and quit). |
| kick | nick (who kicked), target (who was kicked), channel, reason. isMe is true when you did the kicking. |
| nickchange | oldNick, newNick, nick (the old nick), isMe (it was you). |
| mode | nick (who set it), target and channel (the channel, or your nick for a user mode), modes ("+o"), params (["alice"]). |
| topic | A topic change, or the topic sent when you join. channel, text (empty or absent when there's none), nick (who set it, absent for the topic sent on join). |
| invite | nick (who invited), target (who was invited), channel. |
| ctcp · ctcpreply | A CTCP request · a CTCP reply (not /me, which is action). nick, user, host, prefix, target, command ("VERSION"), payload (the text after it). |
| away | Someone's away status changed (away-notify). nick, user, host, prefix, text (the away message, absent when they're back), isMe. |
| connect | You're registered on the network. nick (your nick). |
| disconnect | The connection ended. reason: "clientInitiated", "serverClosed" or "error", with the error's message in text. |
| raw | Every line from the server. command (the verb, or a numeric as text), numeric (numerics only), params, raw (the whole line), prefix, nick, user, host, tags. Observe only: returning a drop or {text} does nothing. |
| output | Your outgoing chat text, before it's sent: {kind, target, text, network}, with kind "message", "action" or "notice". See birc.on('output') above. |
tags holds the IRCv3 message tags ({key: value}, "" for a tag without a value). birc.on('load') and birc.on('unload') are the two lifecycle hooks.
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
| ⌘? | Open this help |
| ⌘, | Settings |
| ⌘1 | Main window |
| ⌘0 | Servers window |
| ⌘⇧T | File Transfers window |
| ⌘⌥S | Scripts window |
| ⌘⇧M | Mentions inbox |
| ⌘D | Jump to conversation… |
| ⌘] · ⌘[ | Next / previous conversation |
| ⌘⇧] · ⌘⇧[ | Next / previous unread conversation |
| ⌘⌥→ · ⌘⌥← | Next / previous server |
| ⌥⌃→ · ⌥⌃← | Next / previous active server |
| ⌘⇧↓ · ⌘⇧↑ | Next / previous highlight |
| ⌘⌃→ · ⌘⌃← | Focus next / previous split pane |
| ⌘⌃B | Jump to present (newest messages) |
| ⌘⇧U | Mark all as read |
| ⌘F | Find in the transcript |
| ⌘G · ⌘⇧G | Find next / previous |
| ⌘⇧F | Search stored history |
| ⌘= · ⌘- | Increase / decrease font size |
| ⌘K | Clear scrollback (the focused conversation) |
| ⌘⌥0 | Hide / show the member list |
| ⌘⇧I | Channel Properties (focused channel/DM) |
| ⌘L | Load earlier history (focused channel/DM) |
| Tab · ⇧Tab | Complete a nick or command / cycle backwards (nothing typed: everyone, recent speakers first) |
| ⇧↩ · ⌥↩ | New line while composing (↩ sends) |
| ↑ · ↓ | Input history (from the first / last line of a multi-line message) |
| ⌃P · ⌃N | Input history, always |
| ⌘B · ⌘I · ⌘U | Bold / italic / underline while composing |
| ⌃⇧C · ⌃⇧H | Text / background color palette while composing |
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
/topicprints 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
/clearallscope. - 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 and the Pro feature list, plus Restore Purchases (App Store) or your license key (direct download).
Per-server options (identity, SASL, proxy, encoding, auto-join, automation, alerts, advanced) live in the Servers window's profile editor, not here.