Module ipc 

Tier-2 IPC helpers — write JSONL commands to the host.

Siblings spawned by mnml as Pty children (or Mount siblings) get MNML_IPC_DIR in env. The host tails $MNML_IPC_DIR/command for JSONL lines and dispatches each one into App::dispatch_command. This module wraps the wire format so siblings write typed helper calls instead of hand-rolling JSON.

Every helper is best-effort: silent no-op on missing env, silent no-op on IO error. Siblings should treat these as fire-and-forget notifications, not as commands they need to confirm succeeded.

mnml_bridge::toast("processing done");
mnml_bridge::set_activity_badge("agents", 3);
mnml_bridge::register_command(
    "my_sibling.open_dashboard",
    "Open Dashboard",
    Some("plugin"),
    &["<leader>md"],
);

Structs

NotifyOpts

Options for notify. All fields are optional-ish — see individual field docs.

Enums

ProgressStatus

Outcome of a progress notification.

SegmentSide

Statusline segment anchor.

ToastLevel

Toast severity level. Info + warn share the standard comment border (calm ambient); error gets a red border so failures stand out. Persistent toasts respect the same mapping.

Functions

notify

Fire an OS-level notification. Host emits OSC 9 + 777 escape sequences after the next render pass — Ghostty / iTerm2 / kitty / WezTerm route those to native banners. Terminals that don’t recognize the escape silently consume it.

progress_end

Finish a progress notification. Failed also fires a toast_error host-side; Success / Cancelled show the terminal status glyph and fade after ~2.5s.

progress_start

Start a progress notification — the host renders an animated Braille spinner + label. Repeat calls with the same id reset the item.

progress_update

Update an in-flight progress. label and percent are both optional — pass None to keep the previous value. Percent clamps to 0..=100 host-side.

register_command

Register a plugin command. It becomes runnable from the palette + optionally bound to one or more key chords in the host. Keyspec syntax mirrors mnml’s own keymap ("ctrl+shift+t", "<leader>xt", …).

set_activity_badge

Set a notification badge on an activity-bar section (or a manifest-registered Mount section, keyed by its manifest id). count = 0 clears the badge.

statusline_clear_segment

Remove a sibling statusline segment by id.

statusline_set_segment

Insert or update a sibling statusline segment. Sorted host-side by priority desc; each segment competes for its lane’s budget.

toast

Show a toast notification in the host. Non-blocking, fire-and-forget. Silent no-op when MNML_IPC_DIR is unset (sibling wasn’t spawned by mnml) or on any IO error.

toast_dismiss

Remove a persistent toast by id. No-op if the id isn’t currently pinned.

toast_error

toast_info

Level-tagged toast helpers — same wire shape as toast but with an explicit level field. info (default) + warn render with the comment border; error gets a red border.

toast_persistent

Pin a toast identified by id. Repeat calls with the same id update the text/level in place. Stays visible until toast_dismiss.

toast_warn