pix

A terminal image browser for terminals that speak the kitty graphics protocol (kitty, Ghostty). Three views: a scrollable thumbnail grid, a list with a large preview of the selection, and full — one image centered in the window.

Works under tmux: images are placed as Unicode placeholder cells rather than as overlays, so tmux can scroll, redraw and switch away from them like any other text. See tmux for the one setting it needs.

Build

make
make install          # -> ~/.local/bin/pix

No dependencies beyond libc and pthreads; stb_image is vendored.

Usage

pix [-r] [-l] [-s name|size|time] [path ...]

  -r            recurse into subdirectories
  -l            start in list view
  -s MODE       initial sort: name (default), size, time

Paths may be files or directories; with none, the current directory is browsed.

pix ~/Pictures          # grid view
pix -l ~/Pictures       # start in list view
pix -r .                # recurse

Keys

key	action
enter	show the selection full size; esc goes back
tab v	switch grid ↔ list
h j k l, arrows	move — in full view they page through images
g / G	first / last
pgup pgdn	page
+ / -	thumbnail size (grid)
s	cycle sort: name, size, time
x	delete the selected file (asks y/n first)
o	open in the system viewer
ctrl-l	redraw everything from scratch
?	help
q esc	quit

x unlinks the file — it does not go to the Trash.

Mouse works too: click to select, wheel to scroll.

tmux

tmux refuses to forward graphics escapes unless told to. pix sets the option for its own pane at startup, but making it permanent is better:

set -gq allow-passthrough all

all rather than on, so images in panes of inactive windows survive too.

Notes

• Decoding runs on a worker pool, so the UI never blocks: tiles show a placeholder and fill in as they finish.
• Formats stb_image can't read (HEIC, WebP, AVIF) fall back to converting through sips on macOS.
• EXIF orientation is applied.
• Cell pixel size comes from TIOCGWINSZ; override with PIX_CELL=10x20 if your terminal doesn't report it.

License

MIT — see LICENSE. The bundled stb_image is public domain.