02. Everyday Conversation and the Screen
Read one screen
The TUI is one conversation you can scroll, fold, and focus. Learn the three parts of the screen before you memorize more keys.
Focus decides what the keys do. The bottom shortcuts bar always names the keys for the pane or card that currently owns the keyboard. When in doubt, look down.
Three parts of the screen
- Scrollback — the conversation: your prompts, the assistant’s replies, tool output, and thinking.
- Prompt — the composer under the scrollback.
- Shortcuts bar — a one-line hint strip that changes with focus, a running turn, or the selected entry.
Panes for todos and background tasks slide in when you need them. They are not a fourth permanent column.
Minimal mode (/minimal or matcha --minimal) is different: the conversation is printed into the terminal’s own scrollback. There is no interactive scrollback pane, so fold, find, and jump work another way.
A useful turn is often long: a plan, several tool calls, a patch. Fold the noise, page through the rest, and keep the composer ready.
Focus
| Key | Context | Effect |
|---|---|---|
Tab | Prompt focused | Focus the scrollback. |
Tab or Space | Scrollback focused | Focus the prompt. In vim mode, i also does this. |
| Any letter | Scrollback, simple mode (default) | Focus the prompt and type that letter. |
Tab / Shift+Tab | A blocking card is focused | Walk that card’s rows. Focus stays in the card. |
Three blocking cards take the keyboard while they wait for you: the question card, the permission prompt, and the cancel-turn panel. The shortcuts bar shows whichever one is live. Esc parks the question or permission card so you can scroll the context behind it; Tab returns. The cancel-turn panel’s Esc means “keep everything running.”
Move through the conversation
These keys apply when the scrollback is focused, unless noted.
| Simple (default) | Vim mode (/vim-mode) | Effect |
|---|---|---|
↑ / ↓ | k / j | Select the previous / next entry. |
Shift+← / Shift+→ | H / L | Jump to the previous / next turn (your prompts). |
K / J | Jump to the previous / next assistant response. | |
g / G | Go to the top / bottom of the scrollback. | |
PageUp / PageDown | same | Scroll by page. Also works from the prompt without moving focus or changing the draft. |
Ctrl+U / Ctrl+D | same | Half page (Shift+D instead of Ctrl+D in VS Code family). |
Ctrl+K / Ctrl+J | same | Scroll one line without changing the selection. |
Fold and expand
Long tool output and thinking stay out of the way until you want them.
| Simple | Vim | Effect |
|---|---|---|
← | h | Collapse the selected entry. |
→ | l | Expand the selected entry. |
e | Toggle fold on the selected entry. | |
E | Expand all / collapse all. | |
Ctrl+E | same | Expand / collapse all thinking blocks. |
Enter or Ctrl+F | same | Open the selected block in a fullscreen viewer. |
In minimal mode, committed text cannot be rewritten. /expand (or Ctrl+E) re-prints the last collapsed or truncated block in full below the conversation. That command is hidden in fullscreen; the refusal says to press Tab, then → on the block.
/expandPanes
| Key | Fullscreen | Minimal |
|---|---|---|
Ctrl+T | Toggle the todos pane (the assistant’s live plan). | Pin / show the todo panel (same chord). |
Ctrl+G | Toggle the tasks pane (background work). | Edit the current draft in $VISUAL / $EDITOR / vi. Does not send it. |
Mouse
In the full TUI, with mouse reporting on (the default):
- Click a scrollback entry to select it.
- Use the scroll wheel to move the scrollback.
- Click the prompt area to focus it.
Disable capture with /toggle-mouse-reporting when that setting is enabled, if you want the terminal’s own drag-select instead.