123kupola d267a4bcb2 docs(wiki): polish terminal + operator-attention pages

- terminal.md: pi→zot,pi order (zot is default agent), 'pi harness'→'agent harness (zot, pi)',
  add pkg install kitty (x11/kitty 0.47.4)
- operator-attention.md: document NO_COLOR pitfall (Hermes leak→force_color_output fix),
  note dual-view (header+bar) as future enhancement
- glasspane.md: link terminal capture + signature triage from see-also

(Sam & Claude)

2026-06-25 23:40:23 +02:00

4.4 KiB

Raw Permalink Blame History

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 modified keys: Tab vs Shift-Tab (cycle sessions), n vs N (next vs 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 Enter, so two distinct bindings become indistinguishable.

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).

Install: pkg install kitty (FreeBSD port x11/kitty, currently 0.47.4).

→ 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

csi-u is the most reliable format and needs tmux 3.5+ (the live USB's port 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 directly; no tmux config needed. This is what the live-USB desktop launcher does.
In tmux — kitty then tmux then colibri-tui. Now the tmux extended-keys config above is load-bearing; without it, Shift-Tab and N 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, Shift-Enter for newline) hit the identical collapse. The decision here is the 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 operator USB that terminal is Kitty.
For the in-tmux workflow: tmux 3.5+ with extended-keys on + extended-keys-format csi-u (pre-3.5: extended-keys on only).
For SSH into a Kitty session: the Kitty SSH kitten, or a one-time terminfo install, so TERM=xterm-kitty resolves on the remote.

4.4 KiB Raw Permalink Blame History