Pi Rich Output

Rich Output adds terminal-friendly structured cards to the Pi timeline. It can show validation summaries, review findings, diagrams, charts, artifact links, progress, and small visual status blocks without turning the conversation into a wall of text.

This extension is working, but it is still WIP. I am publishing it while I evaluate whether rich timeline output is useful enough to keep and expand.

Why use it

Use Rich Output when a result is easier to understand as a compact card than as prose:

| Content | What readers get | | --- | --- | | Validation summaries | Commands, results, durations, and skipped checks in one compact entry | | Review findings | Severity, location, evidence, impact, and suggested fixes | | Benchmark notes | Tables, sparklines, and charts for comparisons or trends | | Diagrams | Small flow diagrams or rendered Mermaid architecture/sequence diagrams | | Artifact links | Visible file paths with terminal hyperlinks when supported | | Status snapshots | Badges, progress bars, key/value rows, and callouts |

For simple answers, normal text is still better.

Install

From npm:

pi install @badliveware/pi-rich-output

From this repository workspace:

pi install ./agent/extensions/public/rich-output

Try it

Run the demo command in Pi:

/rich-output-demo

The demo shows the main rendering surfaces in one timeline entry: terminal capabilities, badges, a formula, a simple flow diagram, a Mermaid diagram, a sparkline, an inline image preview, an artifact link, progress, and a callout.

Tool and command

/rich-output-demo

Shows a sample rich timeline entry so you can see how the extension renders in your terminal.

rich_output_present

Structured Pi tool used to add a rich card to the timeline. It accepts a card kind, title, optional summary/markdown/payload, and optional blocks such as tables, links, diagrams, charts, images, badges, progress bars, and callouts.

Most users do not need to call the tool directly; the point is to give Pi agents a better display surface when structured output helps.

Terminal behavior

Rich Output is designed to degrade safely across terminals:

• Text first: visual blocks keep readable text fallbacks.
• Images when available: Kitty-compatible terminals can show inline PNG previews.
• Links when available: OSC 8 hyperlinks are used when supported; the file path or URL is still printed visibly.
• Safe failures: missing files, invalid image data, oversized artifacts, and failed renders show a short fallback message instead of breaking the timeline.

Optional render tools

Mermaid diagrams and Vega-Lite charts are rendered before they reach the timeline. If the optional renderer is installed, the card shows an inline preview when possible and prints artifact paths for external viewing.

| Feature | Optional tool | If missing | | --- | --- | --- | | Mermaid diagrams | mmdc | Shows source text or a short render error | | Vega-Lite charts | vl-convert | Shows source/spec fallback or a short render error |

Artifact directories:

• Mermaid: .pi/rich-output/mermaid/
• Vega-Lite charts: .pi/rich-output/charts/
• If the project directory cannot be written, temporary fallback directories under /tmp are used.

Built-in limits

The renderer keeps entries bounded so large output does not freeze the UI.

| Limit | Value | | --- | ---: | | Mermaid diagrams rendered per entry | 4 | | Vega-Lite charts rendered per entry | 4 | | Mermaid source before text fallback | 12,000 characters | | Vega-Lite spec before text fallback | 80,000 characters | | Artifact image read limit | 5 MB |

Development

From agent/extensions:

npm run typecheck
npm test