Your OMP sessions in Tern. On SidePulse.
Exercised on macOS 27.2.1 with Tern 0.9.16, OMP 18.18.7, and SidePulse revision ad4a5217.
tern-sidepulse is a Tern window plugin. It puts the Oh My Pi (OMP) sessions visible in your open Tern windows, including sessions on attached remote hosts, on SidePulse — one SidePulse row per OMP session, named after its tab or pane: Tern supplies the window state, and SidePulse drives the LEDs and menu-bar status alongside your other monitored agents. The plugin never reads transcripts, submits prompts, approves actions, or changes window layouts.
Synthetic illustration rendered from assets/demo.html; not a capture and not LED evidence (provenance · MP4).
Get started · What you see · How it works · Privacy · Compatibility · Website · Changelog
Private by design: nothing listens on the network · six fields read per agent row · no transcripts, prompts, or working directories · SidePulse reports carry salted scope hashes, never host keys or pane ids ("labels": false hides tab and pane titles too) · nothing installed on remote hosts
Community project; not affiliated with or endorsed by the Oh My Pi, Tern, or SidePulse maintainers.
| OMP session in a visible Tern window | SidePulse row (state / mode) |
|---|---|
| Working | working (your configured working animation) |
Waiting for input (an ask, an approval) |
blocked / waiting_for_input; outranks working |
| A turn finished | done / completed for 15 s, unless the session resumes first |
| A turn failed | error / blocked_error for 30 s, unless the session resumes first |
| Open at the prompt | idle / idle_ready |
| Pane closed, host disconnected, plugin disabled, or last window closed | clear (removes the row within about 20 s) |
Each OMP session ((host, pane)) appears as its own row in SidePulse's Agents list, named after its user-given tab name or OMP pane title (OMP in Tern when unlabelled or when "labels": false is set in config.json; when a label contains ": ", SidePulse displays the text before ": " as the project). Multiple Tern windows viewing the same session deduplicate into one row by highest-priority state and newest non-empty label, and at most 32 rows are sent (most urgent first).
- macOS with Tern 0.9.12 or later (exercised versions are in docs/compatibility.md).
- SidePulse on the same Mac at a build that includes inteliwear/sidepulse#72 (merged 2026-11-10 as
ad4a5217), installed or updated withsidepulse updateon or after 2026-11-10 so the SidePulse service providesprogram-status.sock. For older SidePulse builds, usetern-sidepulse0.1.0(which reports one combined session). - Python 3.10 or later at a known absolute path: Homebrew's
/opt/homebrew/bin/python3or/usr/local/bin/python3, a versionedpython3.10–python3.14in either prefix, the python.org framework'spython3, or/usr/bin/python3only when the Command Line Tools provide it. Nothing is installed withpip. - Remote hosts need nothing installed: no SidePulse, no helper, and no service.
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-sidepulseOr install a copy from the default branch:
tern plugin install github.com/alphastorm/tern-sidepulseTo 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.
- Wait about 5 s after installing or linking so the window registers and picks up any existing OMP sessions (nothing needs restarting).
- Open the Tern command palette and run
tern-sidepulse: doctor. Expect a toast starting withok:(ok: 0 issue(s); an accepted report is not an LED check). A toast starting withwarn:orerror:names a check that needs attention, such asreceiverwhen SidePulse is stopped or predatesprogram-status.sock(sidepulse update);~/.local/state/tern-sidepulse/doctor.jsonlists each check and its remedy. - Check SidePulse's Agents list in the menu-bar app (or run
sidepulse statuswhen running headless): each OMP session in your open Tern windows appears as its own row from originTern, labelled by its tab or pane title (OMP in Ternwhen unlabelled or when"labels": falseis set).
From the Tern command palette:
| Command | Does |
|---|---|
tern-sidepulse: doctor |
Checks Python, the data and runtime directories, the coordinator, this window, and the SidePulse program-status.sock receiver (receiver check); shows a one-line toast and writes ~/.local/state/tern-sidepulse/doctor.json |
tern-sidepulse: resync |
Re-registers this window and resends every current row to SidePulse |
tern-sidepulse: disable |
Persists the disabled latch file, drops every registered window, clears every row this plugin has shown on SidePulse, and stops the coordinator |
tern-sidepulse: enable |
Removes the disabled latch file; this window registers right away and other open windows on their next 5 s cycle |
The same operations, plus status, from a shell in the plugin directory with Python 3.10 or later:
python3 bridge.py status --data-dir "$HOME/Library/Application Support/Tern/plugin-data/tern-sidepulse"
python3 bridge.py doctor --data-dir "$HOME/Library/Application Support/Tern/plugin-data/tern-sidepulse"
python3 bridge.py disable --data-dir "$HOME/Library/Application Support/Tern/plugin-data/tern-sidepulse"
python3 bridge.py enable --data-dir "$HOME/Library/Application Support/Tern/plugin-data/tern-sidepulse"Every CLI command prints one JSON object to stdout. An acknowledged report to SidePulse confirms local acceptance, not physical LED output.
To override Python discovery, SidePulse socket paths, or label delivery, create config.json in $HOME/Library/Application Support/Tern/plugin-data/tern-sidepulse (must be a regular file of at most 64 KiB, not a symlink; anything else is ignored):
{
"python": "/opt/homebrew/bin/python3.13",
"program_sockets": ["/custom/path/program-status.sock"],
"labels": false
}pythonsets the absolute path to a Python 3.10+ interpreter; reload the plugin (tern plugin reload tern-sidepulse) after changing it.program_socketsoverrides SidePulse's defaultprogram-status.sockcandidates in$XDG_STATE_HOME/sidepulse/agent-monitorand~/.local/state/sidepulse/agent-monitor(including SidePulse's/tmp/sidepulse-status-<uid>/<sha256(path)[:16]>.sockfallback when the socket path exceeds 96 bytes). For CLI and test launches,TERN_SIDEPULSE_PROGRAM_SOCKETS(:-separated) andbridge.py coordinator --program-socket PATH(repeatable) take precedence overprogram_sockets.labelsdefaults totrue. Setting"labels": falsestops sending tab and pane titles to SidePulse; every row then sends"title": ""and"display_name": "OMP in Tern".
program_sockets and labels are read when the coordinator starts. A running coordinator keeps its startup setting until it exits: run tern-sidepulse: disable (which clears the rows and stops the coordinator) and then tern-sidepulse: enable; the next window snapshot starts a coordinator that reads the new setting.
flowchart LR
W1["Tern window 1<br/>window.luau"] -- register / snapshot --> C["coordinator<br/>(one per user)"]
W2["Tern window 2<br/>window.luau"] -- register / snapshot --> C
C -- program_status reports --> S["SidePulse service<br/>program-status.sock"]
- Each Tern window runs an observer (the per-window
window.luauinstance) that checkscx.agents:list()every 5 s and onagent_state,agent_finished,pane_closed,session_ended, andbudgetevents (coalesced over 75 ms). It keeps OMP panes on connected hosts whose live surface role isomp.sessionand sends a complete snapshot (host key, pane id, state, any 15 s completion or 30 s failure notice, and an optional tab or pane label) throughbridge.pyto the local coordinator socket. - The first helper call spawns one background coordinator per user that holds a singleton lock, keeps one row per OMP session keyed by
(host, pane)and deduplicated across windows in priority order (blocked_error,waiting_for_input,working,completed,idle_ready) with the newest non-empty label, and sends oneprogram_statusreport per row (at most 32 rows, most urgent first) to SidePulse'sprogram-status.sockreceiver. Each row is addressed by a salted scope (tern-sidepulse-<24 hex>) and named by its tab or pane title (OMP in Ternwhen unlabelled or when"labels": falseis set). Only changed rows are sent, active rows (working,blocked,error) are refreshed every 300 s, and withdrawn rows send"state": "clear". Each window holds a 15 s lease (an expiry timer renewed by every complete snapshot); a closed window stops contributing when its lease expires, and the coordinator clears every shown scope and exits 5 s after the last lease ends (or after at most 60 s if SidePulse is unreachable). - The plugin data directory (
$HOME/Library/Application Support/Tern/plugin-data/tern-sidepulse) holdsidentity.json(whoseinstall_idsalts every scope hash), optionalconfig.json, thedisabledlatch file, andpycache/for Python bytecode. The runtime directory (~/.local/state/tern-sidepulse) holds a write-ahead scope ledger (program-scopes.json, salted scope hashes only) written before a scope's first report and pruned when its clear is acknowledged; if a coordinator crashes, the next coordinator keeps those inherited scopes for one 15 s lease so still-open panes are overwritten in place and closed panes are cleared when the lease ends. Live observations stay in memory only, and the SidePulse wire contract is documented in docs/compatibility.md.
The plugin reads pane, state, kind, program, host, and alive from each cx.agents:list() row; id, state, panes, kind, address, and name from cx.hosts:list(); and the surface.role of each pane. When a window has at least one OMP pane, it also calls cx.session:panes() and cx.session:tabs() at most once per 5 s pass to read pane, tab, and title from each pane and id and name from each tab. Each OMP pane is labelled with its user-given tab name (TabInfo.name) when non-blank, else the OMP pane's own PaneInfo.title (never TabInfo.title, which is whichever pane is focused in a split tab), cut to 256 bytes at a UTF-8 boundary in the window and sanitized in the coordinator (whitespace collapsed, control characters, lone surrogates, and private-use characters such as OMP's status glyph removed, trimmed, and capped at 96 characters). The plugin never reads working directories (cwd), model names, commands, prompts, assistant text, tool arguments, or transcript paths.
By default, sanitized labels are sent to SidePulse in each row's program_status report (context.title), and if you have configured a SidePulse relay or phone link, SidePulse forwards each row's latest update with status.title (cut to 192 bytes), provider, and session_id the same way it forwards Claude and Codex titles; with no relay or phone link configured, nothing leaves the Mac, and setting "labels": false in config.json stops sending labels to SidePulse altogether. Host keys (local, or a remote host's address, else name, else id:<n>) never appear outside coordinator memory, and pane ids and host keys never leave the Mac: SidePulse scopes (tern-sidepulse-<24 hex>), session_id, and program-scopes.json hold only salted sha256(install_id NUL host NUL pane)[:24] hashes (local status and doctor.json list pane ids of active outcome notices). Labels and host keys never appear in coordinator.log, doctor.json, bridge.py status output, coordinator acknowledgements, or program-scopes.json, and a rejected report logs fixed text only, never SidePulse's error string (status and doctor report row counts — rows by mode, rows_total, rows_labelled — and allow-listed integer window diagnostic counters in doctor.json, including label_tab, label_title, label_none, labels_unavailable, labels_dropped, host_fallback, and encode_failed; tests/test_privacy.py and tests/test_rows.py pin this). Report a vulnerability privately through SECURITY.md.
- Private local files and sockets: Nothing listens on the network.
~/.local/state/tern-sidepulse(mode0700, ownership checked, symlinks refused) holdscoordinator.sock,coordinator.lock,coordinator.log,doctor.json, andprogram-scopes.json; those files,identity.json, anddisabledare written with mode0600underumask 077, andcoordinator.sockis published by atomic rename afterlisten(16). - Bounded requests and state: Coordinator requests must be strict UTF-8 JSON (no
NaN/Infinity, deep nesting rejected), capped at 1 MiB, EOF-framed within a 2 s read deadline, and answered within a 0.5 s write deadline across at most 32 concurrent connections; the window keeps each encoded snapshot under 192 KiB by dropping labels and retrying once (labels_dropped). State is capped at 64 windows, 512 panes per window, 256 registration tokens, and 32 delivered SidePulse rows, with printable window keys of at most 64 characters, host keys of at most 128 bytes in the window and 128 characters in the coordinator, and labels of at most 96 characters after sanitizing (a malformed label is dropped without rejecting the snapshot). - Isolated helper execution: Helpers run as argument vectors (never through a shell) with
python3 -I -S -X pycache_prefix=<data>/pycacheand a 4 s timeout; runningpython3 bridge.py …from a shell setssys.dont_write_bytecode = Trueso no__pycache__is written into the plugin directory. Failed helper calls back off at500 * 2^nms (capped at 30 s), and interpreters below Python 3.10 (exit status 3,python_too_old) are skipped for the life of the window.
~/.local/state/tern-sidepulse/coordinator.log(rotated tocoordinator.log.1at 1 MiB) records lease expiries, enable/disable, delivery failures and recoveries, rejected reports, scopes inherited from a crashed coordinator, 5 s clock jumps, and errors, never payloads, labels, or host keys. When$HOMEis so deep that the socket path plus its 11-byte bind suffix would exceed 100 bytes, the runtime directory falls back to$TMPDIR/tern-sidepulseand then/tmp/tern-sidepulse-<uid>-<digest>;doctorprints the active path.~/.local/state/tern-sidepulse/doctor.jsonholds the full JSON report from the lastdoctorrun, andprogram-scopes.jsonlists the salted scope hashes currently registered with SidePulse.sidepulse status(orsidepulse live) shows SidePulse's own view of the current rows.- Tern's log (
tern::plugintarget) emits onewarn-level line when helper calls start failing (tern-sidepulse helper failing) and one when they recover (tern-sidepulse helper recovered). - Linked-checkout reloads: Tern watches a linked plugin directory and reloads on every file change inside it, including
.git/. Ifcore.fsmonitoris enabled globally, rungit config --local core.fsmonitor falsein the checkout so Git commands do not reload the plugin.
- Run tern-sidepulse: disable from the Tern palette (or
python3 bridge.py disable --data-dir "$HOME/Library/Application Support/Tern/plugin-data/tern-sidepulse"). This persists thedisabledlatch, drops every registered window, and clears the plugin's status on SidePulse so a late helper cannot restore an old state. - Unlink or remove the plugin:
tern plugin unlink tern-sidepulsefor a development link, ortern plugin remove tern-sidepulsefor an installed copy. - The coordinator stops on its own once its rows are cleared: within about 2 s, or at once if SidePulse is not running (
pgrep -f "bridge.py coordinator"checks whether it is still running). Rows it could not clear stay listed inprogram-scopes.jsonfor the next coordinator. - Tern keeps the plugin data directory (
$HOME/Library/Application Support/Tern/plugin-data/tern-sidepulse, containingidentity.json,disabled, andpycache/), so a later reinstall starts disabled until you run tern-sidepulse: enable. For a clean slate, delete~/.local/state/tern-sidepulse(or the fallback runtime path reported bydoctor) and the plugin data directory after step 3 completes.
- Brief turns: Tern samples agent state, so a turn that fails or completes within about 1 s may not emit an in-progress sample; the 15 s completion or 30 s failure notice still appears.
- Crashed coordinator with no later window: SidePulse keeps
program_statusrows in memory and no longer ages out non-donerows (inteliwear/sidepulse#72 comment). If a coordinator crashes (SIGKILL) and no Tern window ever starts another coordinator, its rows stay in SidePulse until SidePulse restarts or another coordinator starts and clears the scopes recorded inprogram-scopes.json. - 32-row cap: SidePulse shares a 64-row table across all providers and evicts the least recently updated row, so
tern-sidepulsesends at most 32 rows, ordered by urgency (blocked_error,waiting_for_input,working,completed,idle_ready). - Done rows after a SidePulse restart: When SidePulse restarts, the coordinator resubmits every current row except
completed(done) rows so an older turn does not read as a fresh completion; those rows go out again when their state changes. - Label refresh interval: Labels are read on the 5 s reconciliation pass (without a title-event subscription), so tab and pane renames take up to 5 s to appear on SidePulse.
- Remote hosts follow open windows: Remote OMP sessions are observed through the Tern window connected to that host; nothing polls a remote host after all windows close.
- Startup and surface role changes: A pane counts while Tern reports its surface role as
omp.session(which includes wrapped commands such asenv … omp). The role is re-read every 5 s, so an OMP session still starting is picked up on the next 5 s pass, and a pane that exits OMP drops out within 5 s.
python3 -B -m unittest discover -s tests -t . -v # -B keeps bytecode out of a linked checkout
luau-lsp analyze --definitions=types/tern.d.luau window.luautypes/tern.d.luau is the tern plugin types output from Tern 0.9.12; regenerate it when targeting a newer Tern release. When the luau CLI is on PATH (or LUAU=/path/to/luau is set; TERN_SIDEPULSE_REQUIRE_LUAU=1 fails instead of skipping), tests/test_luau_harness.py runs window.luau headlessly against the test drives in tests/luau/. Set SIDEPULSE_SRC=<sidepulse checkout>/src (with TERN_SIDEPULSE_REQUIRE_CONTRACT=1 to fail instead of skipping) to run tests/test_sidepulse_contract.py against SidePulse's program_status implementation, and set TERN_SIDEPULSE_SLOW_TESTS=1 to include the 20 s default-limits timing test in tests/test_e2e.py.
Artwork and demo media are rendered by python3 scripts/render_assets.py (requires headless Chrome, ffmpeg with libx264, and network access for the webfonts; --check compares the committed PNGs on the same machine; render from a checkout that is not tern plugin linked, because Tern reloads the plugin on every file write). docs/BRAND.md is the brand spec, and tests/test_site.py keeps README.md, plugin.toml, window.luau, site/, and .github/workflows/pages.yml coherent.
tern-sidepulse shares its presentation with four sibling projects:
- OMP Session Gateway — every live OMP session on one private page
- OMP NInfer — qualified local inference on an RTX GPU you own
- OMP Oracle — send the hard question to ChatGPT or Grok and keep working
- OMP Strata — stock OMP on a stock, local Strata server
MIT, see LICENSE.