02. Everyday Conversation and the Screen
Screen and input modes
Change how the TUI draws and which keys it accepts. The conversation is the same session; the surface is not.
Screen mode is a relaunch of this session. Input and display toggles are settings on the current process (some persist, some do not). Commands that drive a surface the other mode does not have are hidden from / and Ctrl+P. If you type one anyway, Matcha CLI says why.
Fullscreen is the standard alt-screen TUI: interactive scrollback, overlays, themes, dashboard. Minimal (--minimal) is scrollback-native: the conversation is printed into the terminal’s own history. Inline (--no-alt-screen) still counts as fullscreen for every command gate here.
/minimal and /fullscreen (alias /full) reopen the current session in the other mode. They do not write [ui] screen_mode. The relaunch banner tells you how to switch back. --minimal / --fullscreen on the CLI are session-scoped the same way. To make plain matcha open in a given mode, use /settings → "Default screen mode" or set [ui] screen_mode.
A small pane, a multiplexer, or a preference for native scrollback is a reason to go minimal. Overlays (tutorial, theme picker, dashboard, find) need fullscreen. Switching does not create a second conversation or rewrite your config by accident.
Switch screen mode
/minimal
/fullscreenBoth require an active session. /minimal is offered only in fullscreen (including inline). /fullscreen is offered only in minimal. Typing the one you are already in prints You're already in … mode.
Fullscreen-only commands
Hidden in minimal. Typed anyway, they tell you to run /fullscreen (unless a substitute already exists in this mode):
| Command | Why it needs fullscreen |
|---|---|
/find | No scrollback pane to search. Use the terminal’s own search. |
/jump | Native scrollback has no turn picker. |
/timeline | The tick rail needs the interactive pane. |
/tutorial | The tutorial overlay needs fullscreen. Aliases: /tour, /onboarding. |
/theme | Minimal uses the terminal’s own palette. Alias: /t. |
/dashboard | Minimal is single-session. Aliases: /agents-dashboard, /sessions. |
Minimal-only commands
| Command | What to do in fullscreen instead |
|---|---|
/expand | Tab to focus the scrollback, then → on the block. No relaunch suggested. |
/edit-prompt | There is no external-editor path. Ctrl+G is the tasks pane. Run /minimal if you want the editor. |
Ctrl+E in minimal is the same re-print as /expand. In fullscreen, Ctrl+E toggles thinking blocks.
`/vim-mode`
/vim-modeToggle vim-style scrollback keys: j/k, h/l, g/G, y/Y, H/L, e/E, and i to focus the prompt. Off by default: a bare letter in the scrollback focuses the prompt and types the character. Arrow keys, Tab, Esc, Space, PageUp/PageDown, and every Ctrl+letter work in both modes.
Persists to [ui] vim_mode in ~/.matcha/config.toml. You can also set vim_mode = true under [ui] by hand.
`/multiline`
/multilineAlias: /ml. Toggle multiline input. Enter inserts a newline; Shift+Enter or Alt+Enter sends. Mid-turn, empty-composer Enter still sends now the top queued follow-up.
Also bound to Ctrl+M when the prompt is focused. From the scrollback, Ctrl+M opens the model picker.
`/compact-mode`
/compact-modeToggle compact display (less padding, denser output). Persists compact_mode. Short terminals can still auto-compact even after you turn the user setting off; the toast says so.
`/timestamps`
/timestampsToggle timestamps on messages. Persists. The menu may show an on/off hint; the command ignores arguments and always flips the current value.
`/toggle-mouse-reporting`
/toggle-mouse-reportingFlip terminal mouse capture so native click-drag copy/paste works. Opt-in: hidden and inert unless [ui] mouse_reporting_toggle = true in ~/.matcha/config.toml. When the flag is off, the command prints that path instead of toggling.
The matching key is Ctrl+R with the scrollback focused (not the prompt). The slash command runs from either place without defocusing input. Minimal does not register the key.