preview

name: preview description: Display code, diffs, images, and other content in a tmux pane or popup, OR render markdown as a single-page interactive HTML and open in the default chromium-family browser. Auto-detects nvim/megaterm for floating popups. tools: Bash

Preview Skill

Use /preview --help for basic usage (types, flags, modes, examples). This document covers non-obvious features, HTML mode, and troubleshooting.

CRITICAL: Pane Safety Rules

Never kill or disrupt the pane running pi. Before killing, closing, or replacing ANY pane:

Identify your own pane first: tmux display-message -p '#{pane_id}' — this is pi's pane. Never kill it.
Before kill-pane -t X: Verify X is not pi's pane ID.

Before sending keys to any pane: Verify the expected app is actually running there:

tmux display-message -t "$TARGET" -p '#{pane_current_command}'
tmux capture-pane -p -t "$TARGET" -S -3

Never send keys blindly. If target pane doesn't have the expected process, STOP.
Never assume pane identity persists. User may close or rearrange panes between commands.

HTML Mode (`--html`)

Renders markdown as a single-page interactive HTML and opens in a chromium-family browser. Bypasses tmux entirely.

When to use

Plans, proposals, research docs, decision documents — anything the user should scroll, collapse sections, tick checkboxes, answer questions, or comment on.

Plan document detection

When previewing a _PLAN.md file, the extension auto-detects it and passes --meta type=plan --meta slug=<slug> to preview-html. This enables:

"Create Tickets from Plan" button at the bottom of the document
The button copies /tickets <slug> to clipboard for pasting into pi

Interactive features

Sticky TOC sidebar with active-section highlighting (IntersectionObserver)
Collapsible h2 sections — state persisted in localStorage
Interactive task checkboxes — checked state persisted
Decision cards — auto-generated from:
- Headings matching Q1:, Q:, ??, Decision:
- Any h3/h4 under ## Open questions
- List items under ## Open questions
- Each card: Yes/No/Maybe/Skip radios + free-text notes
Per-section user comments — every collapsible section has a textarea for feedback, persisted in localStorage
Conditional response buttons — hidden until user interacts (answers a question, writes a comment):
- Download Responses — saves <slug>-responses.md
- Copy Responses — copies token-efficient markdown to clipboard

Response format

Exported responses are compact markdown optimized for LLM consumption:

# Responses: <title>

slug: <slug>

## Comments

### <section heading>

<user's comment text>

## Decisions

- **<question>**: <choice> — <notes>

## Tasks

- [x] <completed item>
- [ ] <incomplete item>

Metadata embedding

Pass arbitrary metadata via --meta key=value (repeatable). Metadata is available in the HTML as DOC_META (JS object). The preview extension auto-injects type=plan and slug=<slug> for _PLAN.md files.

Browser detection (chromium family only)

PI_PREVIEW_BROWSER env var (bundle id), if set
macOS LaunchServices default http handler — used if chromium-family
Running-app priority: Brave Nightly → Helium → Brave → Chrome → Arc → Edge → Vivaldi
Any installed chromium app

Safari, Firefox: NOT supported.

Window targeting: opens in the window with the most tabs (heuristic for primary window). New tab at end, switches focus, brings window to front.

Output paths and garbage collection

Default: ~/.local/share/pi/preview/<ts>-<slug>.html (gc'd > 30 days)
--html-ephemeral: /tmp/preview-<slug>-<ts>.html (gc'd > 1 day)
Override: PI_PREVIEW_DIR, PI_PREVIEW_PERSIST_DAYS, PI_PREVIEW_TMP_DAYS

GC runs automatically on each preview-html invocation. Manual:

preview-html-gc --dry-run    # show what would be pruned
preview-html-gc --quiet      # silent prune

Direct invocation (bypass extension)

preview-html doc.md                              # render + open
preview-html --no-open doc.md                    # render only
preview-html --ephemeral notes.md                # /tmp output
preview-html --browser com.google.Chrome doc.md  # force browser
preview-html --meta type=plan --meta slug=foo plan.md  # with metadata

Troubleshooting

"Preview requires tmux" — run pi inside tmux, or use --html mode.

"preview-ai failed" — check which preview-ai and required tools: bat, glow, jq, delta, chafa.

"no chromium-family browser found" — install Brave/Chrome/Arc/Edge/Vivaldi, or set PI_PREVIEW_BROWSER.

Tab opens in wrong window — script picks window with most tabs. Close other windows or move tabs to influence targeting.

Preview pane not appearing — check tmux window, try preview-ai diff manually.

Image preview broken — check which chafa and terminal image capabilities.

~/.dotfiles/bin/preview-ai — tmux preview dispatcher
~/.dotfiles/bin/preview-html — HTML render + browser-open (Python)
~/.dotfiles/bin/preview-html-gc — garbage collection