I released kitcat a while back: a matplotlib backend that draws plots directly into your terminal instead of opening a GUI window. The original release was barely a hundred lines and dead simple, and I’ve ended up reaching for it almost every day since.

The 2.0 release addresses the two things people asked for most:

• Plots that behave inside tmux
• Better default sizing

Both rely on features only kitty and Ghostty support, and better sizing needs kitty specifically. Everywhere else gets the old behaviour.

Plots that behave inside tmux

Previous versions drew plots at the cursor. They scrolled fine on their own, but the moment something other than the terminal itself started shuffling text around, things fell apart. tmux, for example, redraws its panes constantly with no idea there’s an image there — so the plot would sit at a fixed position while the text scrolled out from under it, fail to clip at a pane boundary, or linger after the pane was hidden.

This release switches to Unicode placeholders, a newer feature of the kitty graphics protocol that AFAIK only kitty and Ghostty implement. What’s different is that the image is no longer painted at a screen position. Instead we use a Unicode character as a placeholder to tell the terminal to display an image at that cell. The picture you see is really just text. And because it’s text, anything that moves text, e.g. tmux, moves the image for free — it scrolls with the buffer, clips at pane edges, and reflows when you resize the window:

Better default sizing

The other complaint was size. Previous versions always rendered at matplotlib’s default DPI, so on a HiDPI display the plot and its labels came out noticeably smaller than the surrounding terminal text. In 2.0 kitcat queries the display’s real DPI — something only kitty reports — and applies a scaling factor so the figure matches. Ghostty and everything else don’t expose a DPI, so we fall back to the old behaviour.

Detecting the terminal program

Surprisingly, most of my time went into figuring out which terminal program was in use. You can’t trust environment variables like $TERM or $TERM_PROGRAM for this: even when they start out correct, SSH or a multiplexer like tmux may overwrite them — and those are exactly the cases kitcat needs to work in.

The most reliable way I found was to ask the terminal directly — send it a query escape sequence and read its reply. kitcat’s first choice is XTGETTCAP, which queries a terminfo capability in real time; asking for the terminal-name capability (TN) gets the terminal’s own answer with no environment variable in the loop:

printf '\033P+q544e\033\\'

The reply comes back hex-encoded — on kitty it’s 787465726d2d6b69747479, which is just xterm-kitty spelled out in hex.

XTVERSION is the next option. It just asks the terminal to identify itself:

Not every terminal answers these — they vary wildly in what they support and how they identify themselves (there’s a running survey of terminal capabilities that shows just how uneven it gets) — so environment variables stay as a last resort. In practice we mostly care about detecting kitty and Ghostty, which both support replying to these queries.

Update

pip install --upgrade kitcat