@zichuanlan/pi-image-placeholder

Pi extension for Windows Terminal + WSL + pi-zentui:

• Alt+V clipboard image (pi-clipboard-*) → short [image n]
• Ctrl+V / Alt+V clipboard image → short [image n] with draft path + thumbnail
• Never leave a bare [image n] without mapping/preview
• Submit as real multimodal image attachments
• Short editor token stays [image n]; path/data live in hidden session state
• Submitted aliases survive editor clearing and session resume
• SIXEL thumbnails on Windows Terminal (readable bitmaps)
• Half-block only as last-resort fallback
• Does not replace the editor (setEditorComponent) — keeps zentui intact
• Tool screenshots: Playwright MCP, agent-browser CLI, and agent_browser (pi-agent-browser-native)

Install

pi install npm:@zichuanlan/pi-image-placeholder

Restart Pi after install (or /reload).

Local / git

pi install /path/to/pi-image-placeholder
# or
pi install git:github.com/ZiChuanLan/pi-image-placeholder

Tool / browser screenshots

Official Pi skips tool images when caps.images is null (WT_SESSION). This package patches ToolExecutionComponent.updateDisplay to inject SIXEL previews afterward.

Supported sources:

| Source | How previews are found | | --- | --- | | Inline tool images | content: [{ type: "image", data, mimeType }] | | Playwright MCP | markdown links / path: '...' | | agent-browser CLI | JSON data.path / path-like text | | agent_browser (pi-agent-browser-native) | tool name match, prose (Saved image:, Absolute path:), and structured details.imagePath / details.artifacts[] |

Notes:

• snapshot -i is a text accessibility tree — not an image. Use screenshot for bitmaps.
• Path mode is strict: plain ls/find hits on *.png are not turned into galleries.

Usage

1. Windows Terminal ≥ 1.22 (for SIXEL)
2. Restart Pi
3. Win+Shift+S → Ctrl+V / Alt+V
4. Editor shows [image 1]; draft area shows thumbnail + path
5. Delete an unsubmitted placeholder → draft clears
6. Submit → model receives real image data; [image n] keeps its hidden mapping
7. Later in the same/resumed session, read [image n] resolves without renumbering

Commands:

• /image-placeholder status — show wrap/thumbs switches + config path
• /image-placeholder wrap on|off — enable/disable [image N] conversion
• /image-placeholder thumbs on|off — enable/disable draft/tool thumbnails
• /image-placeholder on|off — both switches together
• /image-placeholder-status — drafts + runtime diagnostics (toolPatch, lastSkipReason, paths)
• /image-placeholder-demo — local 1×1 PNG thumbnail self-test (no browser)

Config file (persistent):

// ~/.pi/agent/image-placeholder.json
{
  "wrapPlaceholders": true,
  "showThumbnails": true
}

Force / disable SIXEL

export PI_FORCE_IMAGE_PROTOCOL=sixel   # force
export PI_FORCE_IMAGE_PROTOCOL=off     # disable

Why SIXEL?

Official @earendil-works/pi-tui sets images: null when WT_SESSION is set (only Kitty / iTerm2). That produces text like:

[Image: [image 2] [image/png] 244x134]

oh-my-pi enables readable previews on WT via SIXEL. This package emits SIXEL itself for previews, and prefixes a no-op Kitty marker so Pi's TUI width checks treat the line as an image row (ESM isImageLine is read-only).

Design notes

| Concern | Approach | | --- | --- | | zentui compatibility | Never setEditorComponent; patch Editor.insertTextAtCursor | | Instant placeholders | Rewrite clipboard temp paths on insert | | Short token | Editor shows only [image n]; no full path in prompt text | | Hidden mapping | TUI-only pi.appendEntry() stores number/path/mime only (no base64) | | Draft cleanup | Poll editor text + prune only unsubmitted orphans | | Submitted aliases | Retained in memory and restored on session resume | | Same file twice | Reuse attachment by resolved path | | Path forms | file://, C:\..., \\wsl.localhost\... | | Preview fidelity | SIXEL → native Kitty/iTerm → half-block | | Tool screenshots on WT | Patch ToolExecutionComponent.updateDisplay; path mode only for screenshot-like tools |

Scope / non-goals

This package is intentionally focused:

• Yes: short placeholders, draft/tool SIXEL previews, WT workaround
• No: full browser automation, image editing, replacing zentui, replacing pi-multimodal-proxy

Keep it small. Prefer adapting new tool result shapes over adding new product surfaces.

Uninstall

pi remove npm:@zichuanlan/pi-image-placeholder

License

MIT