Kitty Image Quality in the Terminal... Without Giving Up Tmux
Tags: tmux, kitty, terminal
Published: 2023-03-23 03:04:55

---
title: Kitty Image Quality in the Terminal... Without Giving Up Tmux
published: true
description: Kitty's image protocol brings high-quality image rendering to the terminal. Tmux doesn't support showing images. For folks who are reluctant to abandon tmux but _also_ want to view high-res images in the terminal, it's time for an awkward workaround. Here's mine.
tags: tmux, kitty, terminal
---

- [Motivation](#motivation)
- [Is this actually a problem?](#is-this-actually-a-problem)
- [Time for a workaround](#time-for-a-workaround)
	- [Kitty remote control](#kitty-remote-control)
	- [Kitty tabs](#kitty-tabs)
	- [Timg](#timg)
	- [Duct taping it together](#duct-taping-it-together)
	- [Video demo](#video-demo)
- [Better options](#better-options)

## Motivation

This is a bit cheeky and simplistic, but also reasonably accurate:

- Kitty has a [graphics protocol](https://sw.kovidgoyal.net/kitty/graphics-protocol/) that allows a terminal to render high-resolution images
- A number of tools support kitty's graphics protocol
- Tmux [does not](https://github.com/tmux/tmux/issues/3395#issuecomment-1327312472)
- ...but I like tmux

## Is this actually a problem?

One obvious solution here would be to... _not_ use tmux. Kitty has its own support for windows/tabs/panes, and by all accounts it's quite full-featured. There are other terminals out there too. And hey, I'm all for trying out new tools. But some tools are ingrained enough in my fingers that I'm hesitant to discard them.

## Time for a workaround

Since at least for the moment I'm not ready to give up tmux, what's the lowest friction way to still get kitty-quality images? The flow doesn't have to be pretty, just the image 😎. So far the way that feels smoothest to me combines:

- [kitty remote control](https://sw.kovidgoyal.net/kitty/remote-control/#remote-control-via-a-socket)
- [kitty tabs](https://sw.kovidgoyal.net/kitty/launch/)
- [timg](https://github.com/hzeller/timg/)

### Kitty remote control

I start a kitty session at login and keep it always a keyboard shortcut away. I've updated my startup command to [listen on a unix socket](https://sw.kovidgoyal.net/kitty/remote-control/#remote-control-via-a-socket):

```console
kitty -o allow_remote_control=yes --listen-on unix:/tmp/kitty_remote_control
```

### Kitty tabs

With my kitty session listening on a socket, I can run commands _inside tmux_ that run in new kitty tabs _outside of tmux_:

```console
kitty @ --to unix:/tmp/kitty_remote_control launch --type=tab --title='my new tab'
```

### Timg

Kitty's [graphics protocol page](https://sw.kovidgoyal.net/kitty/graphics-protocol/) lists a number of tools that use it. While I haven't tried them all, I've become particularly fond of [timg](https://github.com/hzeller/timg/). It has some friendly options for things like upscaling and handling transparency/alpha channels. It also has the option to gracefully fall back from kitty-quality to half or quarter pixels in cases where a blocky image is OK.

### Duct taping it together

With a `kimg` script like this:

```bash
#!/bin/bash
set -euxo pipefail

FILE="$1"
shift

kitty @ --to unix:/tmp/kitty_remote_control launch --type=tab --title="$FILE" --no-response \
	/bin/bash -c "timg -pk -B gray --title='%f (%wx%h)' $* '$(realpath $FILE)' && read -sn1"
```

I can use `kimg <image file>` to:

- Open a new kitty tab outside tmux
- Run timg to display the image
- Wait for a keypress to close the kitty tab and return to my tmux home

### Video demo

This short video shows the difference between opening an image in tmux directly vs. in a dedicated kitty tab:

{% embed https://youtu.be/-ERPQVY4wkk %}

## Better options

If you've read this post and thought "wow that's pretty gross, why doesn't he just..." then _great_! First of all, thanks for reading. And second, please share your own suggestions.

_Just keep in mind that if the suggestion is "abandon tmux" I'll be listening with my hands over my ears for now._