This library can display PNG images in supported terminals (e.g. Kitty, WezTerm, Konsole, Ghostty) with varying levels of support depending on the terminal. Most core features work but some advanced things like animations might be only partially supported outside of Kitty.

Other features include:

Image transmission with automatic chunking and base64 encoding
Multiple placements of the same image
Animation support with frame deltas
Unicode placeholder mode for proper scrolling
tmux passthrough support (requires tmux 3.3+)
Terminal capability detection

The library provides a Cmdliner term via the kgp.cli package to make integration into other CLI tools easier.

Installation#

opam install kgp

Usage#

Library#

(* Display a PNG image *)
let png_data = read_file "image.png" in
let cmd = Kgp.transmit_and_display ~format:`Png () in
let buf = Buffer.create 1024 in
Kgp.write buf cmd ~data:png_data;
print_string (Buffer.contents buf)

(* Transmit once, display multiple times *)
let cmd = Kgp.transmit ~image_id:1 ~format:`Png () in
Kgp.write buf cmd ~data:png_data;

let cmd = Kgp.display ~image_id:1 () in
Kgp.write buf cmd ~data:""

CLI#

# Display an image
kgpcat image.png

# Display at specific size and position
kgpcat --place 40x20@10,5 image.png

# Display from stdin
curl -s https://example.com/image.png | kgpcat

# Detect terminal support
kgpcat --detect-support

# Clear displayed images
kgpcat --clear

License#

ISC

Clone this repository