---
slug: "zichuanlan-pi-image-placeholder"
source_type: "readme"
source_url: "https://cdn.jsdelivr.net/gh/ZiChuanLan/pi-image-placeholder@main/README.md"
repo: "https://github.com/ZiChuanLan/pi-image-placeholder"
source_file: "README.md"
branch: "main"
---
# @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

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

Restart Pi after install (or `/reload`).

### Local / git

```bash
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):

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

### Force / disable SIXEL

```bash
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:

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

[oh-my-pi](https://github.com/can1357/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

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

## License

MIT