tern-sidepulse

Tern window plugin · Oh My Pi sessions

Your OMP sessions in Tern. On SidePulse.

Keep running Oh My Pi inside Tern. tern-sidepulse watches the OMP panes in your open Tern windows, local and remote, and reports one row per session to SidePulse — working, waiting for input, completed, failed, or idle, named after its tab or pane — so the LEDs and the menu bar tell you when a session needs you. The plugin never reads a transcript, submits a prompt, approves an action, or changes a window layout.

  • Tern 0.9.12+
  • SidePulse with program status (sidepulse update, 2026-11-10+)
  • Python 3.10+
  • macOS
Synthetic illustration rendered from assets/demo.html — not a capture of Tern, OMP, or SidePulse, and not LED evidence. Durations are compressed. Provenance

What you see

One row per session, the most urgent on the LEDs.

Each OMP session visible in your open Tern windows, including sessions on attached remote hosts, appears as its own row in SidePulse's Agents list, named after its tab or pane. SidePulse drives the LEDs from the highest-priority state across your monitored agents; your configured animations apply.

  • Cyan Roll
    working

    Any session working (your configured working animation)

  • Amber Pulse
    waiting_for_input

    Any session waiting for input (an ask, an approval) outranks working

  • Solid Green
    completed

    A turn finished for 15 s, unless the session resumes first

  • Amber Pulse
    blocked_error

    A turn failed for 30 s, unless the session resumes first

  • Idle Pulse
    idle_ready

    Session open at the prompt (cleared when the pane or window closes)

Closing a pane, losing a host connection, disabling the plugin, or closing the last window clears the row within about 20 s. Multiple Tern windows viewing the same session deduplicate into one row on SidePulse (up to 32 rows, most urgent first).

How it works

From window state to per-session rows.

Each window sends a complete snapshot. One local coordinator deduplicates panes across windows and delivers one acknowledged program_status report per session to SidePulse.

  1. window.luau each Tern window

    Observes cx.agents:list() every 5 s and on agent events. Keeps OMP panes on connected hosts whose surface role is omp.session; sends a complete snapshot with tab or pane labels.

  2. bridge.py helper, per call

    python3 -I -S, an argument vector, a 4 s timeout, and bytecode under the plugin data directory.

  3. coordinator one per user

    Holds a singleton lock and 15 s window leases, deduplicates panes across windows (blocked_error › waiting_for_input › working › completed › idle_ready), and records scopes in program-scopes.json for crash recovery.

  4. program-status.sock SidePulse service

    Receives one program_status report per OMP session (salted scope hash, state, and label) over a private local socket.

Full detail: How it works · compatibility and the SidePulse wire contract.

Private by design

Six agent fields in, hashed scopes out.

The plugin never reads working directories, model names, prompts, assistant text, tool arguments, or transcript paths. SidePulse reports carry salted scope hashes rather than host keys or pane ids, and setting "labels": false in config.json stops sending tab and pane titles to SidePulse.

  • Reads six agent fields, never transcripts

    pane, state, kind, program, host, alive from each agent row, plus host keys, each pane's surface.role, and tab or pane titles. Labels go only to SidePulse (unless "labels": false is set) and never to logs, status, or disk (tests/test_privacy.py).

  • Salted scopes and local sockets

    Host keys never appear outside coordinator memory, and pane ids and host keys never leave the Mac: each row's SidePulse scope and program-scopes.json hold salted SHA-256 hashes only. Only if you configured a SidePulse relay or phone link does SidePulse forward labels, as it does Claude and Codex titles.

  • Private local files and sockets

    ~/.local/state/tern-sidepulse has mode 0700; ownership is checked and symlinks are refused. Runtime, ledger, and state files are written with mode 0600.

  • Bounded requests and state

    Window snapshots are budgeted to 192 KiB and coordinator requests are capped at 1 MiB across at most 32 concurrent connections. State is capped at 64 windows, 512 panes per window, and 32 delivered SidePulse rows.

  • Isolated helper execution

    Argument vectors, never a shell; -I -S isolation and a 4 s timeout. Failed calls back off at 500 · 2ⁿ ms, capped at 30 s.

  • Remote hosts need nothing installed

    No SidePulse, no helper, and no service on a remote host. OMP sessions are observed through the open Tern window connected to that host.

Read the privacy and hardening details · security policy.

One-time setup

Install once, then plain omp.

Install a copy or link a checkout. The next window snapshot picks up existing OMP sessions; nothing needs restarting.

  1. Install

    Install a copy from the default branch:

    tern plugin install github.com/alphastorm/tern-sidepulse

    Or link a checkout for development (saving any file in the checkout reloads the plugin):

    tern plugin link /absolute/path/to/tern-sidepulse
    tern plugin reload tern-sidepulse

    To pin a release, check out its tag and run tern plugin install /path/to/checkout. To update an installed copy, run tern plugin install --force github.com/alphastorm/tern-sidepulse; for a linked checkout, run git pull.

  2. Confirm it works

    Wait about 5 s after installing or linking. Open the Tern command palette and run tern-sidepulse: doctor. Expect a toast starting with ok: (ok: 0 issue(s); an accepted report is not an LED check). A toast starting with warn: or error: names a check that needs attention, such as receiver.

  3. Watch SidePulse

    Check SidePulse's menu-bar Agents list, or run sidepulse status when running headless. Each OMP session in your open Tern windows appears as its own row from origin Tern, labelled by its tab or pane title (OMP in Tern when unlabelled or when "labels": false is set).

Exercised

Exact versions, not “latest”.

The compatibility record names the exact versions and observations. Untested lifecycle cases stay explicit.

  • ExercisedTern 0.9.16 (41a10a5) · OMP 18.18.7SidePulse revision ad4a5217 (0.2.4.dev36+gad4a5217f, the inteliwear/sidepulse#72 merge) on macOS 27.2.1 (Apple Silicon): live rows, unlink clear, the 0.1.0-to-0.2.0 coordinator hand-off and a coordinator crash. The 78 s sleep/wake, full Tern quit and relaunch, and remote disconnect/reconnect checks ran with tern-sidepulse 0.1.0 on Tern 0.9.12 against SidePulse ffb1d3c2, including a remote Mac Studio over Tern remoting.
  • AutomatedUnit, transport, and integration suite on Python 3.10 and 3.13 in CIPlus luau-lsp analysis, the headless Luau 0.745 harness for window.luau, and the SidePulse ad4a5217 contract test.
  • Not yet exercisedA remote host that stays listed but drops to a non-connected stateAnd the two-window close-one case with OMP sessions in both windows.

Timings come from socket and state-file records; an accepted report is not an LED check. Read the compatibility and contract probe.

A narrow job

Use something else when you want more than a status.

This plugin reports per-session status from the OMP panes in your open Tern windows. It is not a remote client or an always-on remote monitor.

  • Open or answer an OMP session from your phoneOMP Session Gateway
  • More than 32 concurrent OMP sessions on SidePulseCapped at 32 rows (most urgent first) so SidePulse's 64-row table is not exhausted.
  • Status for remote hosts with no Tern window openNot this — remote hosts follow open windows.
  • Tern outside macOSNot supported.