pi-streaming-guard0.1.17
Keep Pi's TUI responsive during long streamed responses with incremental Markdown rendering
Untested on omp
This is a pi package. No one has reported whether it works on omp yet. If you try it, add your result below.
Reports 0
No reports yet.
Readme
🛡️ pi-streaming-guard
Keep Pi fast while long responses are still arriving.
Long thinking traces should not make your terminal feel slower.
You keep using Pi exactly the way you always do. Streaming Guard quietly keeps completed Markdown blocks around instead of asking Pi to parse, style, wrap, and pad the entire accumulated response again for every incoming delta. Long reasoning traces stay responsive, the rendered output stays the same, and there is nothing new to invoke while you work.
This is a focused compatibility bridge for Pi 0.82.x–0.87.x, 0.99.x and 1.0.x–1.3.x. It is meant to disappear once the equivalent rendering fix ships upstream.
Why Streaming Guard?
| Behavior | What you get | |
|---|---|---|
| ⚡ | Incremental rendering | Completed Markdown blocks are reused while only changed blocks are rendered again. |
| 🧠 | Same transcript | Headings, lists, links, code, thinking styles, spacing, and terminal wrapping stay intact. |
| 🫥 | Invisible by default | No workflow changes, prompts, tools, or model instructions. Install it and keep using Pi. |
| 🔁 | Reload safe | Reference-counted patches are restored cleanly on /reload, session replacement, and shutdown. |
| 🧯 | Fails closed | Unknown Pi versions are never patched; the extension reports that it is unavailable instead. |
How it works
- Pi streams normally. Assistant and thinking content arrive through the existing message path.
- The guard retains stable work. Compatible
Markdowncomponents survive updates, and unchanged top-level tokens keep their rendered terminal lines. - Pi-owned transforms stay Pi-owned. Rendered Mermaid diagrams use Pi's native path so streaming modes, width fallback, warnings, and themes remain intact.
- Pi draws the same output with less work. Reference-link changes, width changes, and theme invalidation still trigger the required rerenders.
The patch is intentionally narrow: it touches the exported AssistantMessageComponent and Markdown prototypes only in interactive TUI sessions, and restores both when the session runtime shuts down.
Install
Requires Node.js 22.19+ and Pi 0.82.x–0.87.x, 0.99.x and 1.0.x–1.3.x.
pi install npm:pi-streaming-guard
Then start Pi normally. The guard enables itself for interactive sessions.
Other install methods
From GitHub:
pi install git:github.com/monotykamary/pi-streaming-guard
From a local checkout:
bun install
pi install /absolute/path/to/pi-streaming-guard
For one development run:
pi -e /absolute/path/to/pi-streaming-guard
Commands
| Command | Action |
|---|---|
/streaming-guard |
Show status and the detected Pi version. |
/streaming-guard on |
Enable the guard for the current session. |
/streaming-guard off |
Restore Pi's original renderers for the current session. |
Performance
Representative assistant-component benchmark on a 120-column terminal:
| Accumulated Markdown | Pi 0.82.x | Guarded | Speedup |
|---|---|---|---|
| 5,000 characters | 0.64 ms | 0.21 ms | 3.0× |
| 20,000 characters | 2.33 ms | 0.72 ms | 3.2× |
| 50,000 characters | 5.23 ms | 1.75 ms | 3.0× |
| 100,000 characters | 10.63 ms | 3.53 ms | 3.0× |
Run bun run benchmark on your machine for local numbers. Actual frame time varies with terminal width, Markdown shape, syntax highlighting, and color support.
Scope and limitations
Marked resolves reference-style links through document-wide state, so changing a reference definition invalidates the token cache. Theme changes and width changes also invalidate the relevant output.
One enormous paragraph, list, or fenced code block is still a single top-level Markdown token and must be rerendered in full. Rendered Mermaid diagrams intentionally bypass the incremental token cache and remain on Pi's native rendering path. The durable upstream solution may additionally use lightweight rendering while thinking is live.
When a Pi release includes the upstream fix, this extension will refuse that new release until its compatibility range is deliberately reviewed. At that point, uninstall it with:
pi remove npm:pi-streaming-guard
Development
bun install
bun run validate
bun run benchmark
The test suite covers prototype restoration, component reuse, native Mermaid passthrough, outer-wrapper composition, document-wide link invalidation, theme invalidation, and thousands of deterministic streaming-prefix transitions. Release checks also smoke-test loading through Pi's real extension loader.
License
MIT
Pi 1.3 compatibility
Development and offline host probes use exact Pi 1.3.0. Pi 1.3.0 ships pi-tui unchanged from 1.2.0, and the assistant message component and the bundled marked are unchanged too, so the guard's renderer reuse and parity checks carry over. Pi 1.4 and newer remain unsupported until explicitly audited.
Pi 1.2 compatibility
Development and offline host probes used exact Pi 1.2.0. The patched Markdown and assistant message components and the bundled marked are unchanged from Pi 1.1.0, so the guard's renderer reuse and parity checks carry over.
Pi 1.1 compatibility
Development and offline host probes use exact Pi 1.1.0. Both modular and bundled CLI renderers are verified, including component reuse when outputPad changes. Pi 1.2 and newer remain unsupported until explicitly audited.
Pi 1.0 compatibility (0.1.14)
Explicitly supports Pi 1.0.x after native Markdown/assistant rendering and lifecycle verification; unknown release families still fail closed. Native LaTeX tokenization remains enabled after the major-version rollover. Shutdown preserves later renderer owners and makes retained guard delegates inert. Regression tests cover resize, themes, Mermaid and shutdown. Native token parsing caches do not replace this guard's component/token-render reuse; benchmark gains remain workload-dependent, so compare locally with /streaming-guard off.
Tested with Pi 1.0.0. Host-provided Pi packages are wildcard peers, not bundled dependencies; development uses exact 1.0.0 versions. bun run test:pi verifies both the modular and bundled Pi CLI classes through offscreen rendering and repeated startup/shutdown, without credentials or a terminal UI.