Terminal support

Diagnose

Inside a session:

/doctor

Aliases: /terminal-setup, /terminal-check, /terminal-info.

If Matcha will not start, from a shell:

matcha doctor
matcha doctor --json

A report can list issues and still exit 0. Piped matcha doctor --json still reports the same color capability.

/doctor sees live session details the standalone command cannot: whether fullscreen is actually on, notification/focus tracking, and sandbox profile conflicts.

/doctor fix lists automatic fixes available here. Then apply one:

/doctor fix tmux-clipboard
matcha doctor fix dcs-passthrough --yes

Named ids and short handles both work (tmux-clipboard or terminal.tmux-clipboard).

Automatic tmux and SSH fixes

Doctor can persist these when the finding is present:

A tmux fix edits only the persistent config on the machine that hosts the tmux server (including a remote session). Plain tmux uses $HOME/.tmux.conf. Byobu-tmux uses BYOBU_CONFIG_DIR and refuses to guess if that path is missing or unsafe. Matcha keeps the file’s line endings and mode, backs up an existing file, and refuses conflicting assignments.

The scan looks at direct global assignments. Review sourced files, conditionals, and plugins yourself.

Color

A healthy fullscreen setup shows color truecolor and themes all.

Inside tmux there are two questions:

1. What Matcha emits (color in Doctor).
2. What tmux lets through. If the attached client is not marked RGB, tmux can rewrite 24-bit color down to as few as eight. Themes look washed out even when color says truecolor. That finding is terminal.tmux-truecolor.

After the truecolor fix: reload tmux and detach/reattach. Reload alone does not fix the client; reattach alone does not pick up a new server option.

NO_COLOR disables color. Matcha Night / Matcha Day still work on 256-color terminals; Tokyo Night and the other tinted palettes need truecolor. See Themes.

Clipboard and OSC 52

/doctor Clipboard lists up to three routes:

Set MATCHA_CLIPBOARD_NO_OSC52=1 before launch to disable OSC 52 (a terminal that does not implement it may dump the payload as text). Native and tmux routes stay as they are. /doctor then shows osc 52 off.

Every copy is also written to ~/.matcha/last-copy.txt (or MATCHA_COPY_FILE). When delivery is unverified, the toast names that file. /copy <file> writes there on purpose.

Wayland: older compositors may need the terminal focused until the copy toast appears. MATCHA_CLIPBOARD_NO_DATA_CONTROL=1 forces command-line clipboard tools.

Fullscreen, multiplexers, and keys

Zellij and tmux control mode often keep Matcha inline. Set [terminal] alt_screen in ~/.matcha/pager.toml (auto / always / never), or pass matcha --no-alt-screen to confirm inline works. --no-alt-screen still counts as fullscreen for commands like /theme.

Zellij 0.41+: use the Unlock-First (non-colliding) preset (Ctrl+o, c, Change Mode Behavior). Ctrl+g returns Zellij’s own controls.

WezTerm: enable the Kitty keyboard protocol if Ctrl+Enter does not interject (terminal.wezterm-kitty in Doctor). Apple Terminal uses Ctrl+O for that chord.

VS Code / Cursor / Windsurf / Zed: Shift+Enter may arrive as Enter. Use Alt+Enter for a newline (terminal.newline-fallback).

Mouse reporting: Apple Terminal View → Allow Mouse Reporting; iTerm2 profile Enable mouse reporting.

Byobu on GNU screen is limited (terminal.byobu-screen); switch Byobu to its tmux backend.

Check your work

1. matcha doctor outside Matcha, then /doctor inside. Compare color and clipboard lines.
2. In tmux, if themes look dull, apply tmux-truecolor, reload, detach, reattach, /doctor again.
3. Over SSH without wrap, copy a reply and open ~/.matcha/last-copy.txt.