@zichuanlan/pi-image-placeholder

@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