The IPC Model

VMSC uses Electron's ipcMain.handle / ipcRenderer.invoke request-response pattern for all renderer-to-main communication. Channels follow the convention namespace:action. Push events from main to renderer use ipcRenderer.on with dedicated event names.

The `safeHandle` Pattern

Every handler that can throw is registered via safeHandle, which wraps the handler in a try/catch. Instead of letting the error propagate (which would crash the main process), it returns a sentinel object:

function safeHandle(channel, handler) {
  ipcMain.handle(channel, async (...args) => {
    try {
      return await handler(...args)
    } catch (err) {
      return { __ipcError: true, error: err.message }
    }
  })
}

The `invoke()` Wrapper

On the renderer side, the preload script wraps ipcRenderer.invoke to detect __ipcError responses and convert them back into thrown errors. This means renderer code can use standard try/catch or .catch() on every API call:

async function invoke(channel, ...args) {
  const result = await ipcRenderer.invoke(channel, ...args)
  if (result && typeof result === 'object' && result.__ipcError) {
    throw new Error(result.error || 'IPC error')
  }
  return result
}

The `premiumHandle` Pattern

AI-related channels use premiumHandle, which extends safeHandle by checking the user's license tier before invoking the handler. If the user lacks AI access, it immediately returns a tier-gate error without executing the handler.

Push Events (Main → Renderer)

Some namespaces include subscription methods (e.g. onStreamEvent, onParamUpdate) that register ipcRenderer.on listeners. These return an unsubscribe function for cleanup in React useEffect hooks:

// Renderer usage
useEffect(() => {
  const unsub = window.api.events.onStreamEvent((event) => {
    // handle incoming stream event
  })
  return unsub // cleanup on unmount
}, [])

Tier Limit Enforcement

Channels that create or modify gated resources (rules, actions, goals) check tier limits in the main process using wouldExceedLimit() and wouldExceedEnabledLimit(). If a limit would be exceeded, the handler returns an __ipcError with a descriptive message. This enforcement cannot be bypassed from the renderer.

Window

Custom title bar controls. These bypass safeHandle since they are trivial operations.

IPC window:minimize

Minimize the main application window.

Parameters

None

Returns

void

IPC window:maximize

Toggle maximize/restore on the main window.

Parameters

None

Returns

void

IPC window:close

Set the quitting flag and call app.quit(). This triggers a graceful shutdown of all services.

Parameters

None

Returns

void

TikTok

Connect to TikTok LIVE streams via the built-in connector or TikFinity bridge. The mode is determined by sources.tiktok.mode in the config.

IPC tiktok:connect

Connect to a TikTok LIVE room. If mode is tikfinity, connects via the TikFinity WebSocket bridge instead. Reads connection parameters from the config store, with optional overrides from the provided config object.

Parameters

Name	Type	Description
`config`	`Record<string, unknown>`	Optional overrides (e.g. `{ username }`). Falls back to stored config values.

Returns

void on success. Throws on connection failure.

IPC tiktok:disconnect

Disconnect from both the TikTok source and TikFinity source.

Parameters

None

Returns

void

IPC tiktok:status

Get the current connection status. Returns the status from whichever source mode is active.

Parameters

None

Returns

{ connected: boolean, roomId?: string, viewerCount?: number, error?: string }

TikTok Profile

Fetch and cache the streamer's TikTok profile data (avatar, follower count, live status) using a headless browser scrape.

IPC tiktokProfile:login

Fetch the TikTok profile for the configured username. Opens a hidden BrowserWindow, navigates to the user's TikTok page, extracts profile data from rehydration JSON or DOM scraping, and checks live status via tiktok-live-connector. Caches the result in config.

Parameters

None (reads username from sources.tiktok.username)

Returns

{ username, nickname, avatarUrl, followerCount, followingCount, likeCount, isLive, bio, verified, roomId, viewerCount, lastUpdated, error? }

IPC tiktokProfile:getProfile

Return the cached TikTok profile from config without fetching.

Parameters

None

Returns

Cached profile object or null

IPC tiktokProfile:disconnect

Clear the cached TikTok profile from config.

Parameters

None

Returns

{ success: true }

VRChat

VRChat OSC output, avatar parameter scanning, and live parameter listener. OSC parameters are throttle-batched at 200ms intervals to prevent flooding the renderer.

IPC vrchat:initialize

Initialize the VRChat OSC output with the current config (host, port, chatbox settings).

Parameters

None (reads from outputs.vrchat config)

Returns

void. Throws on failure.

IPC vrchat:testParameter

Send a test OSC parameter to VRChat.

Parameters

Name	Type	Description
`name`	`string`	OSC parameter address (e.g. `/avatar/parameters/MyBool`)
`value`	`unknown`	Parameter value (bool, int, or float)
`type`	`string?`	Optional type hint: `"bool"`, `"int"`, or `"float"`

Returns

void

IPC vrchat:testChatbox

Send a test chatbox message to VRChat.

Parameters

Name	Type	Description
`message`	`string`	Text to display in the VRChat chatbox

Returns

void

IPC vrchat:status

Get the current VRChat OSC connection status.

Parameters

None

Returns

{ connected: boolean, host: string, port: number }

IPC vrchat:scanAvatars

Scan the VRChat OSC cache directory for avatar parameter definitions.

Parameters

None (reads cache path from config)

Returns

Array of avatar objects with their parameters.

IPC vrchat:getAvatars

Get the list of previously scanned avatars from the avatar scanner cache.

Parameters

None

Returns

Array of avatar objects.

IPC vrchat:getAllParameters

Get a deduplicated list of all parameters across all scanned avatars.

Parameters

None

Returns

Array of parameter objects with name, type, and default value.

IPC vrchat:getAvatarParameters

Get the list of known OSC parameters from the VRChat output driver (parameters discovered via live OSC traffic).

Parameters

None

Returns

Array of known parameter objects.

IPC vrchat:getCachePath

Get the configured VRChat OSC cache directory path, or the default path if none is set.

Parameters

None

Returns

string — Absolute path to the OSC cache directory.

IPC vrchat:selectCachePath

Open a native directory picker dialog for the user to select a VRChat OSC cache path.

Parameters

None

Returns

string | null — Selected path, or null if cancelled.

IPC vrchat:startListener

Start the OSC listener to receive parameter updates from VRChat. Updates are throttle-batched at 200ms and pushed to the renderer via the vrchat-param-update event.

Parameters

None (reads receive port and host from config)

Returns

{ success: true }

IPC vrchat:stopListener

Stop the OSC listener and clean up throttle buffers.

Parameters

None

Returns

{ success: true }

IPC vrchat:getListenerStatus

Get the current OSC listener status including live parameter snapshot.

Parameters

None

Returns

{ running: boolean, port: number, liveParams: Record<string, any> }

PUSH vrchat-param-update

Pushed from main to renderer when an OSC parameter update is received. Batched at 200ms intervals with deduplication (latest value per address wins).

Payload

{ address: string, value: any, type: string }

OSC Monitor

Debug tool for inspecting raw OSC traffic between VMSC and VRChat.

IPC osc:getPackets

Get the buffer of captured OSC packets.

Parameters

None

Returns

Array of packet objects with address, args, direction, and timestamp.

IPC osc:clear

Clear the packet capture buffer.

Parameters

None

Returns

{ success: true }

IPC osc:pause

Pause packet capture (packets are still received but not buffered).

Parameters

None

Returns

{ success: true }

IPC osc:resume

Resume packet capture after a pause.

Parameters

None

Returns

{ success: true }

IPC osc:isPaused

Check whether packet capture is currently paused.

Parameters

None

Returns

boolean

PUSH osc-packet

Pushed from main to renderer in real-time as OSC packets are captured.

Payload

Packet object with address, args, direction, and timestamp.

PiShock

Control PiShock devices via WebSocket. Supports vibrate, beep, and emergency stop. Shocker devices are discovered via the PiShock API.

IPC pishock:initialize

Initialize the PiShock WebSocket connection with credentials from the config store.

Parameters

None (reads from outputs.pishock config)

Returns

void. Throws on connection failure.

IPC pishock:testVibrate

Send a test vibration command to a specific shocker.

Parameters

Name	Type	Description
`shockerId`	`string`	Shocker device ID
`intensity`	`number`	Vibration intensity (0–100)
`duration`	`number`	Duration in seconds (1–15)

Returns

void

IPC pishock:testBeep

Send a test beep command to a specific shocker.

Parameters

Name	Type	Description
`shockerId`	`string`	Shocker device ID
`duration`	`number`	Duration in seconds

Returns

void

IPC pishock:emergencyStop

Enable or disable the emergency stop state. When active, all PiShock commands are blocked.

Parameters

Name	Type	Description
`active`	`boolean`	`true` to engage emergency stop, `false` to release

Returns

void

IPC pishock:status

Get PiShock connection status, emergency stop state, and last error.

Parameters

None

Returns

{ connected: boolean, emergencyStopped: boolean, lastError: string | null, shockers: Array }

IPC pishock:refreshShockers

Re-query the PiShock API for available shocker devices.

Parameters

None

Returns

Array of shocker device objects.

Rules

CRUD operations for automation rules. Creating and enabling rules is subject to tier limits.

IPC rules:getAll

Get all rules from the config store.

Parameters

None

Returns

Rule[]

IPC rules:save

Create or update a rule. New rules are subject to tier limit checks.

Parameters

Name	Type	Description
`rule`	`Rule`	Full rule object. If `id` matches an existing rule, it is updated; otherwise a new rule is created.

Returns

void. Returns __ipcError if tier limit exceeded.

IPC rules:delete

Delete a rule by ID.

Parameters

Name	Type	Description
`id`	`string`	Rule ID to delete

Returns

void

IPC rules:setEnabled

Enable or disable a rule. Enabling is subject to tier limit on the number of enabled rules.

Parameters

Name	Type	Description
`id`	`string`	Rule ID
`enabled`	`boolean`	New enabled state

Returns

void. Returns __ipcError if enabling would exceed limit.

IPC rules:duplicate

Clone a rule with a new ID and "(Copy)" suffix. Subject to tier limits.

Parameters

Name	Type	Description
`id`	`string`	ID of the rule to duplicate

Returns

The cloned Rule object, or { error }.

Actions

CRUD operations for action definitions. Actions define what happens when a rule triggers (e.g. send OSC, vibrate PiShock, play audio).

IPC actions:getAll

Get all action definitions from the config store.

Parameters

None

Returns

ActionDefinition[]

IPC actions:save

Create or update an action definition. New actions are subject to tier limits. Also broadcasts an actions update to the TikFinity source.

Parameters

Name	Type	Description
`action`	`ActionDefinition`	Full action object

Returns

void

IPC actions:delete

Delete an action by ID. Broadcasts an actions update to TikFinity.

Parameters

Name	Type	Description
`id`	`string`	Action ID to delete

Returns

void

IPC actions:duplicate

Clone an action with a new ID and "(Copy)" suffix. Subject to tier limits.

Parameters

Name	Type	Description
`id`	`string`	ID of the action to duplicate

Returns

The cloned ActionDefinition object, or { error }.

IPC actions:browseScript

Open a native file picker dialog for selecting a script or executable file to use with the Script Runner action target.

Parameters

None

Returns

string | null — Selected file path, or null if cancelled.

Profiles

Named configuration profiles. Each profile stores a snapshot of rules, actions, goals, and output configs. Switching profiles swaps the live data and enforces tier limits on the loaded data.

IPC profiles:getAll

Get all saved profiles. Includes self-repair if the stored value is corrupted.

Parameters

None

Returns

Profile[]

IPC profiles:getActive

Get the active profile ID.

Parameters

None

Returns

string — Active profile ID (defaults to "default")

IPC profiles:save

Create or update a profile.

Parameters

Name	Type	Description
`profile`	`Profile`	Full profile object

Returns

{ success: true }

IPC profiles:delete

Delete a profile by ID. Cannot delete the default profile. If the active profile is deleted, switches to default.

Parameters

Name	Type	Description
`id`	`string`	Profile ID to delete

Returns

{ success: true } or { error: string }

IPC profiles:switch

Switch to a different profile. Saves the current live state into the active profile before loading the target. Loaded data is clamped to tier limits to prevent a profile saved while Premium from exceeding Free caps after downgrade.

Parameters

Name	Type	Description
`id`	`string`	Target profile ID to switch to

Returns

{ success: true, profileName: string } or { error: string }

IPC profiles:create

Create a new profile that inherits the current live rules, actions, goals, and output configs.

Parameters

Name	Type	Description
`name`	`string`	Display name for the new profile

Returns

The newly created Profile object.

IPC profiles:duplicate

Clone an existing profile. If duplicating the active or default profile, uses live state; otherwise clones from stored data.

Parameters

Name	Type	Description
`id`	`string`	Profile ID to duplicate

Returns

The cloned Profile object.

IPC profiles:rename

Rename a profile. Cannot rename the default profile.

Parameters

Name	Type	Description
`id`	`string`	Profile ID
`name`	`string`	New display name

Returns

{ success: true } or { error: string }

Config

Read, write, import, and export the application configuration. Write operations enforce tier limits for rules, actions, and goals.

IPC config:getAll

Get the entire configuration object.

Parameters

None

Returns

Complete config object (sources, outputs, rules, actions, goals, plugins, etc.)

IPC config:get

Get a single config value by dot-notation path.

Parameters

Name	Type	Description
`key`	`string`	Dot-notation path (e.g. `"outputs.vrchat.host"`)

Returns

The value at the specified path, or undefined.

IPC config:set

Set a config value by dot-notation path. Tier limits are enforced if writing to rules, actions, or goals. Emits a config-changed event.

Parameters

Name	Type	Description
`key`	`string`	Dot-notation config path
`value`	`unknown`	Value to set

Returns

void

IPC config:reset

Reset all configuration to factory defaults. Also clears Patreon auth state.

Parameters

None

Returns

void

IPC config:export

Export configuration to a JSON file via a native save dialog. Supports selective export and optional viewer database inclusion.

Parameters

Name	Type	Description
`selective`	`string[]?`	Optional array of config keys to export (exports everything if omitted)
`options`	`{ includeViewerDb?: boolean }?`	Whether to include viewer database in the export

Returns

{ success: boolean, path: string }

IPC config:import

Import configuration from a JSON file via a native open dialog. Enforces tier limits on the imported data before applying. Supports replace and merge modes.

Parameters

Name	Type	Description
`mode`	`"replace" \| "merge"`	`replace` overwrites all config; `merge` adds to existing data

Returns

{ success: boolean, errors?: string[] }

IPC config:exportData

Export configuration as a JSON string (no file dialog). Used for clipboard-based export and drag-and-drop sharing.

Parameters

Name	Type	Description
`options`	`{ selective?: string[], includeViewerDb?: boolean }?`	Export options

Returns

string — JSON-serialized config data.

IPC config:importData

Import configuration from a JSON string (no file dialog). Enforces tier limits.

Parameters

Name	Type	Description
`jsonStr`	`string`	JSON string of config data
`mode`	`"replace" \| "merge"`	Import mode

Returns

{ success: boolean, errors?: string[] }

Events

Access the EventBus event history and subscribe to real-time stream events.

IPC events:getHistory

Get the rolling event history buffer from the EventBus.

Parameters

None

Returns

StreamEvent[]

IPC events:clearHistory

Clear the event history buffer.

Parameters

None

Returns

void

PUSH stream-event

Pushed from main to renderer whenever a new stream event occurs (chat, gift, follow, like, share, etc.).

Payload

StreamEvent — The normalized event object.

PUSH action-executed

Pushed from main to renderer after an action finishes execution.

Payload

Execution result object with action ID, status, and timing.

PUSH source-status

Pushed when a source's connection status changes.

Payload

Status object with source name and connected state.

PUSH source-error

Pushed when a source encounters a connection error.

Payload

Error object with source name and error message.

Queue

Inspect and control the action execution queue.

IPC queue:status

Get the current queue length and number of active execution pools.

Parameters

None

Returns

{ queueLength: number, activePools: number }

IPC queue:clear

Clear all pending items from the action queue.

Parameters

None

Returns

{ success: true }

PUSH gift-combined

Pushed when the queue combines multiple gift events into a single aggregated gift.

Payload

Combined gift result with total count and user info.

Debug

IPC debug:setMode

Enable or disable debug mode on the EventBus, which increases logging verbosity.

Parameters

Name	Type	Description
`enabled`	`boolean`	Whether to enable debug mode

Returns

void

Console

IPC console:execute

Execute a built-in console command. Supports commands like help, status, rules, actions, fire <type>, config get/set, version, uptime, and eval (dev-only). The eval command is restricted to dev mode for security.

Parameters

Name	Type	Description
`command`	`string`	Console command string (e.g. `"fire gift"`, `"config get outputs.vrchat"`)

Returns

{ output: string, error?: string }

Logs

Save, list, read, and delete log files stored in the user data directory.

IPC logs:save

Save log content to a file in the logs directory.

Parameters

Name	Type	Description
`name`	`string`	Log file name (sanitized for filesystem safety)
`content`	`string`	Log content to write

Returns

{ success: true, path: string }

IPC logs:list

List all saved log files, sorted by modification date (newest first).

Parameters

None

Returns

Array<{ name: string, size: number, modified: number }>

IPC logs:read

Read the content of a saved log file. Filename is sanitized to prevent path traversal.

Parameters

Name	Type	Description
`filename`	`string`	Log filename

Returns

{ content: string } or { error: "File not found" }

IPC logs:delete

Delete a saved log file.

Parameters

Name	Type	Description
`filename`	`string`	Log filename to delete

Returns

{ success: true }

Plugins

Manage user-installed plugins. Plugins are loaded from the plugins directory and can register custom event handlers and action targets.

IPC plugins:getAll

List all discovered plugins with their manifest info, enabled state, and any load errors.

Parameters

None

Returns

Array<{ name, version, description, author, type, enabled, error }>

IPC plugins:enable

Activate a plugin and persist it in the enabled list.

Parameters

Name	Type	Description
`name`	`string`	Plugin name from manifest

Returns

void

IPC plugins:disable

Deactivate a plugin and remove it from the enabled list.

Parameters

Name	Type	Description
`name`	`string`	Plugin name

Returns

void

IPC plugins:getDir

Get the absolute path to the plugins directory.

Parameters

None

Returns

string

Widgets

Detachable pop-out dashboard widgets (Live Feed, OSC Monitor, Goals, etc.). Each widget runs in its own BrowserWindow.

IPC widgets:open

Open a widget in a new pop-out window.

Parameters

Name	Type	Description
`componentId`	`string`	Widget component identifier (e.g. `"live-feed"`, `"osc-monitor"`)

Returns

Widget window info object.

IPC widgets:close

Close a pop-out widget window.

Parameters

Name	Type	Description
`componentId`	`string`	Widget component identifier

Returns

{ success: true }

IPC widgets:getOpen

Get the list of currently open widget IDs.

Parameters

None

Returns

string[]

IPC widgets:isOpen

Check if a specific widget is currently open.

Parameters

Name	Type	Description
`componentId`	`string`	Widget component identifier

Returns

boolean

IPC widgets:setAlwaysOnTop

Set whether a widget window stays on top of other windows.

Parameters

Name	Type	Description
`componentId`	`string`	Widget component identifier
`value`	`boolean`	Always-on-top state

Returns

{ success: true }

IPC widgets:setOpacity

Set the opacity of a widget window.

Parameters

Name	Type	Description
`componentId`	`string`	Widget component identifier
`value`	`number`	Opacity value (0.0 to 1.0)

Returns

{ success: true }

IPC widgets:getConfigs

Get saved widget configurations (position, size, always-on-top, opacity) for all widgets.

Parameters

None

Returns

Map of component IDs to widget config objects.

PUSH widget-closed

Pushed when a widget window is closed (by the user or programmatically).

Payload

string — The component ID of the closed widget.

Overlays

Stream overlay management. Overlays are served via the built-in HTTP/WebSocket server and rendered in OBS browser sources.

IPC overlays:getAll

Get all overlay definitions.

Parameters

None

Returns

Overlay[]

IPC overlays:save

Save the full array of overlay definitions (replaces all).

Parameters

Name	Type	Description
`overlays`	`Overlay[]`	Complete array of overlay definitions

Returns

void

IPC overlays:getServerPort

Get the port number the overlay HTTP server is running on.

Parameters

None

Returns

number (default: 7890)

IPC overlays:getServerBaseUrl

Get the full base URL of the overlay server (e.g. http://localhost:7890). Includes tunnel URL if active.

Parameters

None

Returns

string

IPC overlays:broadcastUpdate

Push a live update to all connected overlay clients for a specific overlay.

Parameters

Name	Type	Description
`overlayId`	`string`	Target overlay ID
`updateType`	`string`	Type of update (e.g. `"config"`, `"event"`, `"variable"`)
`data`	`any`	Update payload

Returns

void

IPC emulate-event

Fire a synthetic stream event for testing overlays without a live TikTok connection.

Parameters

Name	Type	Description
`eventData`	`any`	Synthetic event object matching the `StreamEvent` schema

Returns

void

IPC overlays:browseAsset

Open a native file picker for selecting overlay media assets (images, audio, video).

Parameters

Name	Type	Description
`mediaType`	`string`	Type filter: `"image"`, `"audio"`, or `"video"`

Returns

string | null

IPC overlays:copyFileToAssets

Copy an external file into the overlay assets directory so it can be served by the overlay HTTP server.

Parameters

Name	Type	Description
`sourcePath`	`string`	Absolute path to the source file

Returns

string — Relative asset path for use in overlay widgets.

IPC overlays:saveAssetFromBuffer

Save a binary buffer (e.g. cropped image data) as an overlay asset file.

Parameters

Name	Type	Description
`filename`	`string`	Target filename
`data`	`Uint8Array`	Raw binary data

Returns

string — Relative asset path.

PUSH overlays-changed

Pushed when overlay definitions are modified (from any source, including AI or config import).

Payload

Overlay[] — The updated overlay array.

AI

Local AI inference using GGUF models via node-llama-cpp. Most channels require Premium tier (marked with PREMIUM). The AI assistant can read rules/actions, execute actions, toggle rules, and navigate the UI.

IPC ai:getStatus

Get the current AI system status: model loaded, downloading, running inference, available models.

Parameters

None

Returns

{ installed: boolean, models: string[], activeModel: string | null, running: boolean, downloading: boolean, downloadProgress: number, loading: boolean, loadProgress: number }

IPC ai:getSystemSpecs

Get system hardware specs relevant to AI inference: RAM, CPU, GPU, VRAM, CUDA support.

Parameters

None

Returns

{ ramGB, cpuCores, cpuModel, gpuName, gpuVRAM, hasCuda, meetsMinimum }

IPC ai:getModelRegistry

Get the built-in model registry with available models, their sizes, and system requirements.

Parameters

None

Returns

Array<{ id, label, desc, sizeGB, minRAM, minVRAM, recommended }>

IPC PREMIUM ai:downloadModel

Download a model from the built-in registry. Progress is pushed via the ai-download-progress event.

Parameters

Name	Type	Description
`modelId`	`string`	Model ID from the registry

Returns

Download result with success status.

IPC PREMIUM ai:deleteModel

Delete a downloaded model file.

Parameters

Name	Type	Description
`modelId`	`string?`	Model ID to delete. If omitted, deletes the active model.

Returns

Deletion result.

IPC PREMIUM ai:switchModel

Load a different model into memory. Progress is pushed via ai-load-progress.

Parameters

Name	Type	Description
`modelId`	`string`	Model ID to load

Returns

Load result with success status.

IPC PREMIUM ai:unloadModel

Unload the currently loaded model from memory to free resources.

Parameters

None

Returns

Unload result.

IPC PREMIUM ai:chat

Send a message to the AI assistant and receive a response. The AI has access to a tool context including: reading rules/actions, executing actions, toggling rules, creating rules/actions, reading avatar parameters, and navigating the UI.

Parameters

Name	Type	Description
`message`	`string`	User message
`context`	`Record<string, unknown>?`	Optional context object for grounding the conversation

Returns

AI response with generated text and token usage.

IPC PREMIUM ai:getSettings

Get AI inference settings (temperature, top-p, max tokens, system prompt, etc.).

Parameters

None

Returns

AI settings object.

IPC PREMIUM ai:updateSettings

Update AI inference settings (partial update, only supplied keys are changed).

Parameters

Name	Type	Description
`partial`	`Record<string, unknown>`	Partial settings object

Returns

Updated settings object.

IPC PREMIUM ai:resetSettings

Reset AI settings to defaults.

Parameters

None

Returns

Default settings object.

IPC PREMIUM ai:getChats

Get all saved chat sessions.

Parameters

None

Returns

Array of chat session objects with metadata.

IPC ai:getChat

Get a single chat session by ID.

Parameters

Name	Type	Description
`chatId`	`string`	Chat session ID

Returns

Chat session object with full message history.

IPC PREMIUM ai:saveChat

Save a chat session (create or overwrite).

Parameters

Name	Type	Description
`chat`	`ChatSession`	Full chat session object

Returns

{ success: true }

IPC PREMIUM ai:deleteChat

Delete a saved chat session.

Parameters

Name	Type	Description
`chatId`	`string`	Chat session ID to delete

Returns

{ success: true }

IPC PREMIUM ai:getCustomModels

List user-provided GGUF model files in the models directory.

Parameters

None

Returns

Array of custom model file info objects.

IPC PREMIUM ai:loadCustomModel

Load a custom GGUF model file into memory. Progress is pushed via ai-load-progress.

Parameters

Name	Type	Description
`filename`	`string`	GGUF filename in the models directory

Returns

Load result.

IPC PREMIUM ai:getModelsDir

Get the absolute path to the models directory.

Parameters

None

Returns

string

IPC ai:getTokenCount

Get token usage from the last AI inference call.

Parameters

None

Returns

Token count object.

IPC PREMIUM ai:searchHuggingFace

Search the HuggingFace model hub for GGUF models.

Parameters

Name	Type	Description
`query`	`string`	Search query
`sort`	`string?`	Sort order (default: `"downloads"`)
`limit`	`number?`	Max results (default: 20)

Returns

Array of HuggingFace model result objects.

IPC ai:getHuggingFaceModelDetails

Get detailed info about a specific HuggingFace repository including available GGUF files.

Parameters

Name	Type	Description
`repoId`	`string`	HuggingFace repository ID (e.g. `"TheBloke/Llama-2-7B-GGUF"`)

Returns

Model details with available files, sizes, and quantization info.

IPC PREMIUM ai:downloadHuggingFaceModel

Download a specific GGUF file from HuggingFace. Progress is pushed via ai-download-progress.

Parameters

Name	Type	Description
`repoId`	`string`	HuggingFace repository ID
`filename`	`string`	GGUF filename to download
`downloadUrl`	`string`	Direct download URL

Returns

Download result.

PUSH ai-download-progress

Pushed during model downloads with progress information.

Payload

{ modelId?, percent, downloadedBytes, totalBytes, speed }

PUSH ai-load-progress

Pushed during model loading with a 0–100 progress value.

Payload

number (0–100)

PUSH ai-navigate

Pushed by the AI assistant to navigate the renderer to a specific page.

Payload

{ page: string }

Viewers

SQLite-backed viewer database. Tracks unique viewers with metadata, custom tags, and notes.

IPC viewers:getAll

Get all viewers from the database.

Parameters

None

Returns

Viewer[]

IPC viewers:get

Get a single viewer by unique ID.

Parameters

Name	Type	Description
`uniqueId`	`string`	Viewer's unique platform ID

Returns

Viewer | null

IPC viewers:update

Update viewer fields (partial update).

Parameters

Name	Type	Description
`uniqueId`	`string`	Viewer's unique ID
`updates`	`Record<string, unknown>`	Fields to update (e.g. `{ notes: "VIP" }`)

Returns

Updated Viewer or null

IPC viewers:delete

Delete a viewer from the database.

Parameters

Name	Type	Description
`uniqueId`	`string`	Viewer's unique ID

Returns

boolean

IPC viewers:addTag

Add a tag to a viewer.

Parameters

Name	Type	Description
`uniqueId`	`string`	Viewer's unique ID
`tag`	`string`	Tag to add

Returns

Updated Viewer or null

IPC viewers:removeTag

Remove a tag from a viewer.

Parameters

Name	Type	Description
`uniqueId`	`string`	Viewer's unique ID
`tag`	`string`	Tag to remove

Returns

Updated Viewer or null

IPC viewers:search

Full-text search across viewer usernames, nicknames, notes, and tags.

Parameters

Name	Type	Description
`query`	`string`	Search query

Returns

Viewer[]

IPC viewers:getByTag

Get all viewers with a specific tag.

Parameters

Name	Type	Description
`tag`	`string`	Tag to filter by

Returns

Viewer[]

IPC viewers:getStats

Get aggregate viewer database statistics (total viewers, active today, top gifters, etc.).

Parameters

None

Returns

Statistics object.

Toxicity

Chat toxicity filter. Uses pattern matching and keyword lists to detect and block toxic messages before they trigger rules.

IPC toxicity:getConfig

Get the current toxicity filter configuration (thresholds, word lists, enabled state).

Parameters

None

Returns

Toxicity config object.

IPC toxicity:configure

Update the toxicity filter configuration. Persists changes to the config store.

Parameters

Name	Type	Description
`config`	`Record<string, unknown>`	Partial config update

Returns

Updated config object.

IPC toxicity:getStats

Get toxicity filter statistics (messages scanned, blocked, block rate).

Parameters

None

Returns

Stats object.

IPC toxicity:resetStats

Reset toxicity filter statistics to zero.

Parameters

None

Returns

{ success: true }

IPC toxicity:test

Test a message against the toxicity filter without blocking it.

Parameters

Name	Type	Description
`message`	`string`	Message to test

Returns

Filter result with blocked status, matched patterns, and confidence.

PUSH toxicity-blocked

Pushed when a message is blocked by the toxicity filter.

Payload

Blocked message details with user, message content, and matched patterns.

Chat Logs

Per-viewer chat history stored by the ChatLogManager.

IPC chatlog:get

Get the full chat log for a specific viewer.

Parameters

Name	Type	Description
`viewerId`	`string`	Viewer's unique ID

Returns

Array of chat log entries.

IPC chatlog:search

Search a viewer's chat log for messages containing the query.

Parameters

Name	Type	Description
`viewerId`	`string`	Viewer's unique ID
`query`	`string`	Search query

Returns

Filtered array of matching chat log entries.

IPC chatlog:sessions

Get a list of all chat log sessions (one per stream session).

Parameters

None

Returns

Array of session objects with timestamps and message counts.

Tunnel

Cloudflare Tunnel management for exposing the overlay server over HTTPS without port forwarding.

IPC tunnel:provision

Provision a new tunnel subdomain for the user via the Gatekeeper server.

Parameters

Name	Type	Description
`userId`	`string`	User ID for tunnel allocation

Returns

Provisioning result with tunnel hostname.

IPC tunnel:start

Start the Cloudflare Tunnel process to begin proxying HTTPS traffic to the local overlay server.

Parameters

None

Returns

Start result with public URL.

IPC tunnel:stop

Stop the running Cloudflare Tunnel process.

Parameters

None

Returns

void

IPC tunnel:status

Get the current tunnel status (running, hostname, connection state).

Parameters

None

Returns

Tunnel status object.

License

Patreon-based license management via the Gatekeeper OAuth server.

IPC license:get-state

Get the current license state including tier, limits, user info, and token expiry.

Parameters

None

Returns

{ tier: string, limits: TierLimits, user?: UserInfo, expiresAt?: number }

IPC license:patreon-login

Open the Patreon OAuth flow in the user's default browser.

Parameters

None

Returns

{ status: "opened" }

IPC license:exchange-code

Exchange an OAuth authorization code for a JWT token via the Gatekeeper server.

Parameters

Name	Type	Description
`code`	`string`	OAuth authorization code from the Patreon callback

Returns

Exchange result with token and tier info.

IPC license:logout

Clear the stored JWT token and revert to Free tier.

Parameters

None

Returns

{ status: "ok" }

IPC license:refresh

Refresh the JWT token before it expires.

Parameters

None

Returns

{ success: boolean }

IPC license:setDevMode

Enable or disable dev mode for license testing. Only works in development builds; no-op in production.

Parameters

Name	Type	Description
`enabled`	`boolean`	Whether to enable dev mode (unlocks Premium features)

Returns

Updated license state.

PUSH license-state-changed

Pushed when the license state changes (login, logout, refresh, tier change).

Payload

Full license state object.

PUSH license-auth-complete

Pushed when the Patreon OAuth flow completes (success or failure).

Payload

{ success: boolean, error?: string }

CUDA

CUDA acceleration library management for AI inference. Downloads and manages CUDA-specific native libraries for GPU-accelerated inference.

IPC cuda:getStatus

Get the CUDA installation status including whether libraries are installed, current version, and GPU compatibility.

Parameters

None

Returns

CUDA status object with installed state, version, and GPU info.

IPC cuda:install

Download and install CUDA acceleration libraries. Unloads any active AI model first. Progress is pushed via cuda-download-progress.

Parameters

None

Returns

{ success: boolean, error?: string }

IPC cuda:cancelInstall

Cancel an in-progress CUDA library download.

Parameters

None

Returns

void

IPC cuda:checkUpdate

Check if a newer version of the CUDA libraries is available.

Parameters

None

Returns

Update check result with available version.

IPC cuda:remove

Remove installed CUDA libraries. Unloads the AI model and resets the llama instance to release DLL handles before deletion.

Parameters

None

Returns

{ success: boolean, error?: string }

IPC cuda:dismiss

Dismiss the CUDA installation prompt so it does not appear again.

Parameters

None

Returns

void

PUSH cuda-download-progress

Pushed during CUDA library download with progress info.

Payload

Progress object with percent, bytes, and speed.

App

Application metadata and developer tools.

IPC app:getVersion

Get the application version string.

Parameters

None

Returns

string (e.g. "1.2.3")

IPC app:isDevBuild

Check if the app is running as a development build.

Parameters

None

Returns

boolean

IPC app:openDevTools

Open the Chromium DevTools for the main renderer window.

Parameters

None

Returns

void

Shell

IPC shell:openExternal

Open a URL in the user's default browser.

Parameters

Name	Type	Description
`url`	`string`	URL to open

Returns

void

Updater

Auto-update system for distributing new versions.

IPC updater:check

Check for available updates.

Parameters

None

Returns

Update check result.

IPC updater:download

Download the available update.

Parameters

None

Returns

Download result.

IPC updater:install

Install the downloaded update and restart the application.

Parameters

None

Returns

void (app restarts)

IPC updater:status

Get the current updater status (checking, downloading, ready, error).

Parameters

None

Returns

Updater status object.

PUSH updater-status

Pushed when the updater status changes.

Payload

Updater status object with state, version, and progress.

Gifts

TikTok gift icon management.

IPC gifts:getIconPath

Get the absolute path to the gift icons directory.

Parameters

None

Returns

string

IPC gifts:updateDatabase

Fetch and cache the latest TikTok gift icons from the internet.

Parameters

None

Returns

Update result with number of icons downloaded.

Discord

Discord OAuth2 integration for user profile display.

IPC discord:startAuth

Start the Discord OAuth2 flow. Opens a browser to Discord's authorization page and starts a local HTTP server on port 19284 to catch the callback. Times out after 2 minutes.

Parameters

None (reads Client ID from config)

Returns

Discord profile object on success, or { error }.

IPC discord:getProfile

Get the cached Discord profile.

Parameters

None

Returns

Discord profile object or null.

IPC discord:disconnect

Clear the cached Discord profile and token.

Parameters

None

Returns

{ success: true }

LiveChecker

Polls TikTok to detect live/offline status changes.

IPC livecheck:start

Start polling for the configured TikTok user's live status.

Parameters

None (reads username from config)

Returns

{ success: true } or { error: string }

IPC livecheck:stop

Stop live status polling.

Parameters

None

Returns

{ success: true }

IPC livecheck:status

Get the current live checker status.

Parameters

None

Returns

{ polling: boolean, lastStatus: boolean | null, username: string }

Test

IPC test:fireEvent

Fire a synthetic stream event into the EventBus for end-to-end rule testing. Unlike debug events, these execute all matched rules including external actions (PiShock, OSC, etc.).

Parameters

Name	Type	Description
`event`	`StreamEvent`	Synthetic event object to fire

Returns

void

IPC Channels

The IPC Model

The safeHandle Pattern

The invoke() Wrapper

The premiumHandle Pattern

Push Events (Main → Renderer)

Tier Limit Enforcement

Window

Parameters

Returns

Parameters

Returns

Parameters

Returns

TikTok

Parameters

Returns

Parameters

Returns

Parameters

Returns

TikTok Profile

Parameters

Returns

Parameters

Returns

Parameters

Returns

VRChat

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Payload

OSC Monitor

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Payload

PiShock

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

The `safeHandle` Pattern

The `invoke()` Wrapper

The `premiumHandle` Pattern