ircuitry documentation

Overview

An ircuitry workspace holds one or more bots. Each bot has a node graph (its behaviour) and one or more server connections. A graph reacts to incoming IRC events through trigger nodes, runs logic/data nodes, and performs effects through action nodes. The same graph fires for events from every server the bot is on.

• No code required. Drag nodes, wire them, set a few fields. (There is still a Code node if you want it.)
• IRCv3 native. Capabilities, message tags, account-tag, labeled-response, typing, reactions, redaction and more are nodes.
• Local & private. Everything lives in your workspace folder on disk; secrets are kept out of exports.
• Extensible. Bake your own nodes from existing ones, install community nodes/workflows, or drive the app over MCP.

Install & first run

1. Grab a build from the latest release (Windows .exe/.zip, Linux .deb/.AppImage/.zip, macOS .zip). The builds are self-contained, no runtime to install.
2. Launch it. Your workspace is created at ~/ircuitry (override with the IRCUITRY_HOME environment variable).
3. A starter bot tab is waiting. Open the Connection inspector, set a server (e.g. irc.libera.chat : 6697, TLS on), a nick and the channels to join.
4. Press Play in the title bar to connect. The Event Console shows the handshake and everything coming in.

The first run also registers the ircuitry:// link handler so one-click installs from this site work.

The interface

Title bar

A single glossy bar holds the app icon, your bots as scrollable cartridge tabs, and a tool cluster on the right:

• Play / Stop - connect or disconnect the active bot.
• Test - dry-run a command against your graph without touching IRC.
• History - a timeline of every run, with the exact node path and pin values.
• Notifications - achievements and important events.
• Network map - a live graph of every bot, server and channel (see below).
• File - new/import/export bots, workspace actions.
• More - the rest: secrets, node library, tutorial, settings.

Canvas

The main area is the node graph. Drag empty space to pan, scroll to zoom, and a minimap sits in the corner. Double-click empty space (or Ctrl+K) for Quick Add to drop a node by name. Right-click for the context menu (cut/copy/paste/duplicate, mute, bake, tidy, delete).

Node palette & Node Library

The palette lists every built-in node by category. The Node Library (in the More menu) manages your installed community nodes - install from clipboard, update, or uninstall.

Inspector

Select a node to edit its parameters in the right panel. Select nothing (or the bot itself) to get the Connection inspector: bot name, the reusable Servers list, and per-server settings (host/port, TLS, SASL account/password, nick/ident/real-name, channels, auto-reconnect, connect-on-startup).

Nodes, pins & wires

Every node has input pins on the left and output pins on the right. Pins come in three flavours:

• Exec pins (square, Exec) carry control flow. A trigger pulses its exec output, which runs the next node, and so on - this is the order things happen in. Exec only connects to Exec.
• Data pins (round) carry values, pulled on demand. There are five data kinds, and the kind just colours the pin and any wire from it (a hint, e.g. User = a nick): Text User Channel Number Bool. Any of these five can wire into any data input.
• Tool pins (round, Tool) are special: they carry an AI tool definition and only connect Tool to Tool (an AI Tool node into Ask AI).

A node can mix them. On Command has a square then (Exec) plus round args (Text), nick (User) and channel (Channel) outputs. A node with only round pins - like Text Transform (text in → result out, no exec) - is a pure data node: nothing "runs" it; its output is computed on demand when something downstream pulls it.

Drag from one pin to another to wire them. A node with no incoming exec runs as a pure data node when something pulls its output. Mute a node (press M) to skip it without deleting it.

Tokens & variables

Most text fields accept {tokens} that expand at run time:

Use Set Variable to stash a value and read it later anywhere with {name}. JSON values can be walked with dot paths and iterated with For Each.

Bot commands & replies

The classic shape is On Command -> do something -> Reply.

• On Command has a prefix (default !), a command word, and the contexts it answers in: public (in a channel), private (a private message that has channel context), and pm (a direct query). It outputs the args, the nick and the channel.
• Reply sends a line back to wherever the command came from. Threaded Reply correlates the reply to the triggering message (IRCv3 +reply) so clients can thread it, and attaches +draft/invoked-by / channel-context where appropriate.
• Owner controls: build admin commands behind a Filter: from account node so only allow-listed accounts (not spoofable nicks) can run them.

The dedicated Test panel lets you type a command and watch it run with no live connection - perfect for building and for the test workflows below.

IRCv3

ircuitry speaks modern IRCv3. The Ircv3 category (22 nodes) exposes capabilities, message tags and the drafts as plain nodes, so a client/server/bot developer can drive and verify each feature from a command:

• Capabilities & tags - read negotiated caps, read/attach arbitrary message tags, see the account tag, msgid, time (server-time), and the label for labeled-response correlation.
• Typing - send +typing=active/paused/done (!typing start / !typing stop).
• Reactions - +draft/react via TAGMSG.
• Redaction - request message REDACT on a target msgid.
• Multiline, chathistory, account-notify, away-notify, setname, metadata and friends, where supported.

There is a growing set of IRCv3 testing workflows - install one, then drive it with bot commands to verify your client or server handles each feature.

DCC file transfer

ircuitry implements CTCP DCC SEND, including passive/reverse transfers and acknowledgements.

• On DCC Offer fires when someone offers you a file - it outputs the filename, size, sender nick, and the sender's authenticated account.
• Accept downloads to a path you choose (wire in {filename}), Reject declines, and Send offers a file to a nick.
• Good practice: gate Accept behind a from-account allow-list so only people you trust can send you files.

AI: Ask, tools & memory

ircuitry is provider-agnostic - point the AI nodes at any OpenAI-compatible endpoint (base URL + key + model).

• Ask AI takes a prompt and a system message and returns a reply. Wire nodes into its tools input and the model can call them.
• AI Tool defines a callable tool (name, description, any number of arguments). Wire its tool output into Ask AI; wire its call output to a sub-flow that ends in Tool Reply (whatever you feed Tool Reply is what the model gets back). Read arguments anywhere with {arg.NAME}.
• AI Memory remembers context across turns; Workflow Editor gives the model inward MCP tools to read and edit bot graphs; Programmer AI is a sandboxed coding agent confined to a codebase.
• Bake a node into a tool. A baked composite can be used as an AI tool two ways: (1) it contains an AI Tool sub-flow - Ask AI looks inside and uses it; or (2) tick Usable as an AI tool in the Bake dialog and the node's input pins become the model's arguments and its first output the result.

Baking your own nodes

Select a few wired nodes, right-click -> Bake into a node, and ircuitry bundles them into one reusable node - the pins are worked out from the wires crossing your selection. Or open the full Bake dialog to build a node from scratch in a little embedded editor.

• Expose an inner setting as a node parameter so whoever uses the node fills it in; hard-code the rest.
• Tick Usable as an AI tool to give the node a tool output.
• Submit sends it as a PR to the community-nodes repo, or Export writes a .ircnode file.

Community nodes are composites of built-in nodes (no opaque code blobs), so anyone can open one up and see exactly how it works.

Bot Bakery (merging)

The Bot Bakery merges two or more bots into one. It walks you through conflicts (e.g. two bots that both answer !help) and lets you resolve each. There is a matching Bot Factory on this site that does the same merge in the browser.

Network map

The button in the title bar opens a live node-link graph of your whole setup: bot nodes on the left, unique server hubs in the middle, and channel nodes on the right, wired by membership. Each bot-to-server wire is coloured by that bot's live connection status.

Community nodes & workflows

Browse community nodes and workflows right here. Two ways to install:

1. One-click install opens ircuitry and stages the item behind a confirm dialog (needs the app installed).
2. Copy, then in ircuitry open the Node Library and Install from clipboard (Ctrl+Shift+V).

After your first install, the gallery quietly checks your running app and tailors each card: Inspect shows the underlying graph, an Upgrade hint appears if a card needs a node your build is missing, and prerequisite community nodes are offered before a workflow that depends on them. Installed nodes auto-update.

Secrets & KEYS

Store API keys, passwords and tokens under KEYS and reference them as {{secret.NAME}}. Secrets are kept out of the workspace file and out of any export or submitted node, so you can share a graph safely.

Testing & the console

The Event Console renders every incoming line with friendly badges (the account tag, a bot marker) instead of raw tag soup, and exposes every tag to the graph. The Test panel dry-runs a command; the History panel records each run with the exact node path and the value on every pin, so you can see precisely what happened.

Keyboard shortcuts

Node reference

Every built-in node, generated from the app itself. Filter by name, then expand one for its pins and parameters.

File formats

.ircnode - a community node

JSON declaring one node: typeId, title, subtitle, icon (a Phosphor name), category, description, inputs/outputs ({name,kind}), params, and either a subgraph (a composite of other nodes) or code+language.

.ircbot - a workflow

JSON with format: "ircuitry.workflow.v1", name, description, author, category, tags, a nodes array ({id,type,x,y,params,...}) and a connections array ({from,fromPin,to,toPin}). Installing one adds a new bot tab.

Workspace

Lives at ~/ircuitry (or $IRCUITRY_HOME): your bots, the saved servers, installed community nodes (.ircnode files), secrets and achievements.

Command line & MCP

The same binary doubles as a CLI:

The app also serves a tiny read-only loopback endpoint (locked to this website's origin) so the gallery can detect which nodes your build has - it never takes any action on its own.

FAQ

Where are my files? ~/ircuitry (or wherever $IRCUITRY_HOME points).

Does it support TLS / SASL? Yes - per server, in the Connection inspector.

Can one bot be on several servers? Yes - a bot's graph reacts to events from all of its servers and routes replies back to the right one.

Is my data sent anywhere? No. Everything is local; AI nodes only call the endpoint you configure.

Found a bug or want a node? Open an issue, or PR a node.