pi-lens

The file previewer for pi — read, browse, and peek at files without leaving your terminal session.

pi-lens adds a tabbed side drawer to pi that previews markdown, source code, PDFs, and images — plus a one-key peek that opens the OS-native previewer (Quick Look on macOS) for pixel-perfect viewing. The drawer stays open while you keep chatting with pi.

Features

• Markdown — headings, tables, and fenced code rendered with pi's own theme
• Code — syntax highlighting + line numbers for .ts .js .py .html .css .go .rs and dozens more (via pi's highlighter — matches your theme)
• PDF · text view — full text extraction via Mozilla pdf.js (handles real-world encodings, CMaps, embedded fonts), with per-page markers
• PDF · visual view (v) — all pages rendered as one continuous scrollable strip of in-terminal pixels; n/p jump between pages
• Images — in-drawer thumbnail (ANSI quadrant blocks, any truecolor terminal)
• Peek (enter) — the active file opens in the OS previewer: pixel-perfect images and fully rendered PDFs in a floating panel, esc to come back
• Tabs — open many files, switch with ←/→ or 1..9
• Three widths — Regular 50% · Focus 70% · Sideshow 30% (/lens-mode)
• Chat-friendly — ctrl+shift+l toggles focus between drawer and chat; the drawer stays visible either way
• npm-only install — pdfjs-dist (pure JS) + optional @napi-rs/canvas (prebuilt binaries). No brew/apt. Everything degrades gracefully if absent.

Install

pi install npm:@iamps6/pi-lens        # from npm
# or
pi install git:github.com/iamps6/pi-lens   # from source

Or clone for development:

git clone https://github.com/iamps6/pi-lens
cd pi-lens && npm install
# then symlink into pi's extension dir:
ln -s "$(pwd)" ~/.pi/agent/extensions/pi-lens

Usage

Command	Description
/lens	Open the drawer with a welcome screen
/lens <path>	Preview a file (adds a tab). Absolute, ~, and relative paths all work
/lens-mode [regular|focus|sideshow]	Drawer width — 50% / 70% / 30% (picker if no arg)
/lens-close	Close the drawer

Global shortcut: ctrl+shift+l — focus in/out of the drawer from anywhere.

Keys inside the drawer

Key	Action	Key	Action
↑/↓ j/k	scroll	←/→ Tab [/]	switch tabs
space/pgdn pgup	page	1..9	jump to tab
g / G	top / bottom	w	close current tab
enter / o	peek in OS previewer	q	close drawer
v	PDF: text ⇄ visual pages	n / p	PDF visual: next/prev page
ctrl+shift+l	back to chat

Quick tour

/lens README.md              ← rendered markdown, scroll with ↑↓
/lens src/index.ts           ← highlighted code with line numbers
/lens ~/Documents/report.pdf ← extracted text · press v for pages · enter to peek
/lens ~/Pictures/photo.png   ← thumbnail · enter for pixel-perfect Quick Look
/lens-mode focus             ← widen the drawer to 70%

Supported formats

Type	Extensions	In-drawer rendering	Peek (enter)
Markdown	.md .markdown .mdx	full markdown renderer	Quick Look
Code	.ts .js .py .html .css + many more	syntax highlight + line numbers	Quick Look
PDF	.pdf	pdf.js text extraction · visual page strip (v)	full PDF, scrollable
Image	.png .jpg .jpeg .gif .webp .bmp	quadrant-block thumbnail	pixel-perfect
Everything else	any	plain text, soft-wrapped	Quick Look

How visuals work

Images and PDF pages are converted to pixels and rendered as ANSI quadrant-block characters (▘▝▞▛ with truecolor fg/bg = 2×2 pixels per cell, chafa-style). Because that's plain styled text, it works inside the drawer with scrolling, tabs, and borders in any truecolor terminal. For full detail, enter opens the file in the OS-native previewer.

Limitations

Why aren't drawer visuals full-detail?

pi itself can show crisp inline images in the chat transcript — so why are pi-lens visuals blocky? Two different rendering worlds:

1. The drawer is made of text. The drawer is a floating overlay that pi's TUI composites by rewriting styled text lines every frame. A text cell shows at most 2 colors; quadrant glyphs squeeze 2×2 "pixels" per cell out of that — the best known encoding. A 70-cell drawer is ~140 px of horizontal resolution. That's the information-density ceiling of character-cell graphics, not an implementation choice.

2. The crisp path is closed to extensions. Raster protocols (iTerm2 OSC 1337, Kitty graphics) draw at the cursor inside a linear, append-only flow — pi's transcript is such a flow, which is why pi's own inline images are sharp. Extension surfaces (overlays, widgets) are composited: lines are partially rewritten at arbitrary positions each frame, and a raster protocol inside a compositor corrupts (we verified this on all three extension surfaces). There is currently no pi extension API for appending rich content to the transcript — the only crisp surface.

Hence the design: drawer = navigate (text is perfect, visuals are thumbnails) · enter = look (OS previewer, pixel-perfect).

Other limitations

• Scanned/image-only PDFs have no text layer — use visual mode (v) or peek (OCR is out of scope).
• Without optional @napi-rs/canvas: images show an info card, PDFs are text-only. Without pdfjs-dist: PDF falls back to a basic built-in extractor.
• The drawer overlays the right side of the transcript (pi has no split-pane API for extensions). /lens-mode sideshow minimizes coverage.
• Peek uses Quick Look on macOS; Linux/Windows open the default app (xdg-open / start).

Roadmap

• Opt-in /lens-send — push the current visual into the chat as a tool-result image (crisp in-transcript rendering; enters LLM context)
• Truecolor capability detection with 256-color fallback
• CSV/TSV table rendering
• Zoom + pan for visual mode
• Upstream pi proposals: split/dock API for the drawer; extension API for rich transcript content

License

MIT © iamps6