Scrapwire Scripting

Scrapwire scripts are written in Rhai and let you react to events, send messages, and add your own commands to the terminal client. Scripts live in the platform config directory (for example ~/.config/scrapwire/scripts/), use the .rhai extension, and auto-load and compile at startup. A syntax error in one script does not block the others, and a "Reload Scripts" command (F1) re-scans without a restart.

Scripting is a feature of the TUI (terminal) client only. The native macOS GUI does not expose Rhai scripting.

Read the full scripting guide (SCRIPTING.md)

The scrapwire:: API

Every API function lives under the scrapwire:: namespace, so there are no bare globals to collide with. Scripts use it to send messages (send_conversation, send_dm, send_whisper), inspect state (conversations, members, me), persist data (store/load), register commands (add_menu_item), write locally (send_local), and tune limits (rate_limit). Each script also gets its own isolated, JSON-backed key-value store that survives restarts.

Event handlers

Scripts can define optional event handlers that fire as things happen in the client:

• on_startup and on_shutdown run as the client starts and stops.
• on_message(conv_id, sender, text, is_group) runs on every incoming message.
• on_join(conv_id, member_name) runs when a member joins a conversation.

The Script Menu (F2)

Each script can populate a filterable command palette, the Script Menu, opened with F2. A script's create_user_menu(ctx) adds items; selecting an item invokes the callback you registered for it, so you can turn any script routine into a custom command.

Sandbox and rate limits

Scripts run in a sandbox. Each call is capped at 1,000,000 operations, call nesting is limited to 64, and strings are limited to 1 MiB. Imports are blocked, and functions cannot reach top-level let/const state (state flows through parameters or the store/load API).

Sends are rate limited as well: a hard safety cap of 10 calls per second per script, plus an implicit 60-second per-callback interval unless a script calls scrapwire::rate_limit() to set a custom interval.

Headless and --exec modes

Scripts do not require the interactive TUI. In headless mode (--headless) there is no TUI, but handlers still fire and send_local writes to stdout, which is useful for building custom message loggers. --exec mode runs a single script function from the command line and then exits (./scrapwire --exec script.rhai:function [args...]).