Terminal — capability, not brand

Terminal — capability, not brand

← index

What this is

A decision about which terminal capability Colibri's operator surfaces

depend on, and why the choice fell on Kitty. The decision is about

_capabilities_ (extended-key reporting); Kitty is the instance that provides

them. A terminal without the capability is not "wrong" — it just degrades

specific keybindings.

Decision

The dashboard client (colibri-tui) and the agents it supervises (zot, pi)

are keyboard-driven, and several of their bindings rely on distinguishing

previous attention pane), Enter (open detail). Terminals built on VTE

(xfce4-terminal, GNOME Terminal, Sakura) and Qt-based Konsole collapse

modifiers: Shift-Enter, Ctrl-Enter, and Alt-Enter all arrive as a plain

The recommended terminal is Kitty: GPU-accelerated, keyboard-driven, and it

reports modified keys via the Kitty keyboard protocol / extended-keys. It is the

shipped default on the operator USB, with xterm retained as the always-works

fallback (Kitty is GPU-only; it cannot start on a headless bhyve surface with

no GL, so the rescue path falls back to xterm).

→ crates/colibri-glasspane-tui/src/main.rs

(the bindings above)

Decisions

tmux must forward modifiers, not strip them

Inside tmux the same collapse happens by default: tmux strips modifier

information unless told otherwise. The live USB ships a ~/.config/tmux/tmux.conf

that enables passthrough:

set -g extended-keys on
set -g extended-keys-format csi-u

is 3.5a). Pre-3.5 tmux (e.g. an older Linux build host) omits the second line

and falls back to the xterm modifyOtherKeys format, which Colibri also

parses. Where this matters: colibri-tui launched raw (no tmux) gets

modified keys natively; the tmux config only matters for the run-inside-tmux

workflow.

→ crates/colibri-glasspane-tui/src/main.rs (the event loop's key handling)

Raw-kitty vs in-tmux is a real distinction

Two equally-valid ways to run the dashboard:

• Raw — kitty /usr/local/bin/colibri-tui. Kitty reports modifiers

does.

• In tmux — kitty then tmux then colibri-tui. Now the tmux

stop reaching the app.

The desktop launcher path is raw by design, so the dashboard works without any

operator tmux setup. The in-tmux path is for operators who want tabs/splits

around the dashboard.

The SSH terminfo gotcha

Kitty sets TERM=xterm-kitty. A remote host that has never seen Kitty does not

carry that terminfo entry, so tmux a fails with missing or unsuitable

terminal: xterm-kitty. The fix is Kitty's SSH kitten, which copies the terminfo

to the remote on connect — used as the ssh alias on operator machines. Lying

with TERM=xterm-256color works but discards the extended-key capability,

defeating the reason for the terminal choice.

Agent harness surfaces the same requirement

Agent harnesses (zot, pi) — spawnable Colibri backends — print a startup warning when

tmux extended-keys is off, because its own bindings (Enter to submit,

same one, stated for Colibri's surfaces: pick a terminal that reports

modifiers, and configure tmux to forward them.

Requirements, stated once

• A terminal that reports modified keys (Kitty, Ghostty, WezTerm). On the

• For the in-tmux workflow: tmux 3.5+ with extended-keys on +

• For SSH into a Kitty session: the Kitty SSH kitten, or a one-time terminfo

See also

• tui — the dashboard whose bindings drive this requirement
• operator-attention — the jump keys (n / N)

• deployment — the operator USB that ships Kitty + the tmux