// 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.
| 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 |
Use /preview --help for basic usage (types, flags, modes, examples). This
document covers non-obvious features, HTML mode, and troubleshooting.
Never kill or disrupt the pane running pi. Before killing, closing, or replacing ANY pane:
tmux display-message -p '#{pane_id}' — this is pi's pane. Never kill it.kill-pane -t X: Verify X is not pi's pane ID.tmux display-message -t "$TARGET" -p '#{pane_current_command}'
tmux capture-pane -p -t "$TARGET" -S -3
--html)Renders markdown as a single-page interactive HTML and opens in a chromium-family browser. Bypasses tmux entirely.
Plans, proposals, research docs, decision documents — anything the user should scroll, collapse sections, tick checkboxes, answer questions, or comment on.
When previewing a _PLAN.md file, the extension auto-detects it and passes
--meta type=plan --meta slug=<slug> to preview-html. This enables:
/tickets <slug> to clipboard for pasting into piQ1:, Q:, ??, Decision:## Open questions## Open questions<slug>-responses.mdExported 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>
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.
PI_PREVIEW_BROWSER env var (bundle id), if sethttp handler — used if chromium-familySafari, 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.
~/.local/share/pi/preview/<ts>-<slug>.html (gc'd > 30 days)--html-ephemeral: /tmp/preview-<slug>-<ts>.html (gc'd > 1 day)PI_PREVIEW_DIR, PI_PREVIEW_PERSIST_DAYS, PI_PREVIEW_TMP_DAYSGC runs automatically on each preview-html invocation. Manual:
preview-html-gc --dry-run # show what would be pruned
preview-html-gc --quiet # silent prune
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
"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 collectionStructured workflow for research → plan → tickets → work. Use when starting or continuing a task with /task, /plan, or /tickets commands.
Create and refine tickets for the tk ticket system. Use when the user says 'create tickets for X', 'refine ticket X', 'break this into tickets', 'seed tickets from plan', or anything about creating or refining tk tickets.
Work on a single tk ticket end-to-end. Use when the user says 'work on ticket X' or when spawned by work-tickets.sh.
REQUIRED when user says 'pickup', '/pickup', 'handoff', '/handoff' — MUST load this skill BEFORE any other work. Compacts conversations into handoff docs or resumes work from a prior handoff document.
Interact with web pages using Chrome DevTools Protocol. Launches a managed browser instance (Helium / Brave Nightly / Chrome) with an isolated profile and exposes nav, eval, screenshot, pick, and emulation helpers. Run scripts/start.js first.
Delegate tasks to other agents - pi sessions or external agents (claude, opencode, aider). Non-blocking with task tracking and completion notifications.