kitty

Documentation

Index

• func ClearImages() string
• func DisplayImage(path string, cols, rows int) string
• func FitSize(imgW, imgH, maxCols, maxRows int) (cols, rows int)
• func ImageSize(path string) (width, height int)
• func InvalidatePaneOffset()
• func PaneOffset() (top, left int)
• func PaneVisible() bool
• func PlaceImage(path string, row, col, cols, rows int) string
• func Supported() bool

Functions

func ClearImages

func ClearImages() string

ClearImages returns Kitty graphics protocol escape sequence to clear all images from the screen. Should be called when leaving image display context.

func DisplayImage

func DisplayImage(path string, cols, rows int) string

DisplayImage returns Kitty graphics protocol escape sequences to display an image from a file path at the given terminal cell position and size. Uses file path transfer mode (t=f) so the terminal reads directly from disk. Returns empty string if the file doesn't exist.

func FitSize

func FitSize(imgW, imgH, maxCols, maxRows int) (cols, rows int)

FitSize computes cell dimensions that fit within maxCols x maxRows while preserving the image's aspect ratio. Assumes ~2:1 cell aspect ratio (cells are roughly twice as tall as wide).

func ImageSize

func ImageSize(path string) (width, height int)

ImageSize returns the pixel dimensions of an image file. Returns (0, 0) if the file can't be read or decoded.

func InvalidatePaneOffset

func InvalidatePaneOffset()

InvalidatePaneOffset forces re-query of tmux pane position on next call.

func PaneOffset

func PaneOffset() (top, left int)

PaneOffset returns the tmux pane's top-left position in the terminal. Returns (0, 0) if not inside tmux or if the query fails. Cached after first call; call InvalidatePaneOffset() on resize.

func PaneVisible

func PaneVisible() bool

PaneVisible reports whether our tmux pane is currently on-screen. This is true when the pane belongs to the active window; moving focus between panes within the same window keeps the pane visible, so Kitty graphics should NOT be cleared in that case. When not running inside tmux we optimistically assume the pane is visible.

The check is a `tmux display-message -t $TMUX_PANE` query. It MUST target our own pane by id, otherwise tmux resolves the default target against the client's current pane — which, right after a window switch, lives in the new window and reports `window_active=1` even though WE are now hidden.

func PlaceImage

func PlaceImage(path string, row, col, cols, rows int) string

PlaceImage returns escape sequences to move the cursor to (row, col) and then display an image there. Row and col are 1-based coordinates relative to the application pane. Inside tmux, the cursor move and image draw are both sent through DCS passthrough with absolute terminal coordinates.

func Supported

func Supported() bool

Supported returns true if the terminal supports Kitty graphics protocol. Checks environment variables and tmux outer terminal hints. Cached for the session lifetime.

When running inside tmux with Kitty support, this function also promotes the tmux `allow-passthrough` option to `all` if it is currently `on`. Without `all`, tmux drops any passthrough sequences emitted from an inactive (hidden) pane, which means a Kitty image placed while the pane is visible stays stuck on screen after the user switches tmux windows: our clear sequence can never reach the terminal from the hidden pane.