The modern TUI uses alternate-screen mode, mouse reporting, bracketed paste, and optional synchronized output. Most issues come from multiplexers (tmux/zellij), SSH, or missing truecolor.

Live diagnostics

/terminal-setup

Reports detected capabilities (truecolor, sync-output, kitty keyboard, tmux) and remediation lines. Also available as part of first-run hygiene.

Well-tested for fullscreen TUIs: Kitty, WezTerm, Ghostty, iTerm2, Alacritty, Windows Terminal, modern VS Code / Cursor integrated terminals.

Truecolor

# ~/.bashrc or ~/.zshrc
export COLORTERM=truecolor

Inside tmux:

set -g default-terminal "tmux-256color"
set -as terminal-features ",*:RGB"

tmux clipboard & passthrough

set -g set-clipboard on
set -g allow-passthrough on
set -g focus-events on

Reload: tmux source-file ~/.tmux.conf.

Without passthrough, OSC 52 clipboard writes and some capability queries may not reach the outer terminal.

Clipboard routes

Agent Code prefers native tools when available:

PlatformTools
macOSpbcopy
Linux Waylandwl-copy, then xclip / xsel
Linux X11xclip / xsel
Windowsclip

Slash: /copy copies the last assistant message. Modern TUI will grow block-level copy + OSC 52 fallback as part of the world-class TUI track.

Keyboard protocol

Shift+Enter / disambiguated chords need the Kitty keyboard protocol (or equivalent). If your terminal lacks it, /terminal-setup suggests alts (e.g. Alt+Enter for newline).

ProblemFix
Ctrl+C does nothingSome hosts steal it; try Ctrl+Shift+C / Cmd+C
Esc seems to cancelIt should not in modern TUI — update to latest; use Ctrl+C to cancel
Flicker under heavy streamPrefer terminals with sync-output; avoid nested tmux without RGB
Focus junk after exit (^[[I)Upgrade; restore path disables focus reporting

SSH

Remote sessions often lose TERM_PROGRAM and clipboard. Prefer:

  • Truecolor-capable TERM forwarded
  • Copy via terminal-native selection (Shift+Insert) when OSC 52 is blocked
  • Run Agent Code locally against a remote checkout when possible