Fullscreen vs minimal

This is a screen choice, not a different product. Headless (matcha -p) and matcha agent stdio have no TUI, so they ignore these flags.

The two modes

Fullscreen is the default: Matcha CLI takes over the terminal (the alternate screen), draws scrollback and the prompt, and hosts overlays such as the tutorial, the theme picker, and the dashboard.

--no-alt-screen keeps that same fullscreen command set, but draws inline in your existing terminal instead of switching screens. For /theme, /tutorial, and the other gated commands, inline still counts as fullscreen. It is not minimal.

Minimal (--minimal / /minimal) is experimental scrollback-native mode. Finished blocks go into the terminal's own scrollback. A small pinned region holds the prompt and the running turn. Minimal uses your terminal's palette, so /theme has nothing to drive.

Mode-gated commands are hidden from / and from Ctrl+P in the mode that cannot run them. If you type one anyway, Matcha CLI says why and names the switch (/fullscreen or /minimal) or the in-mode substitute.

Open in a given mode

matcha                 # default: fullscreen (unless you persisted minimal)
matcha --fullscreen    # this session: standard TUI
matcha --minimal       # this session: scrollback-native
matcha --no-alt-screen # this session: inline, still the fullscreen command set

These two flags are session-scoped. They do not write config.toml. The next plain matcha follows [ui] screen_mode (or the built-in default, fullscreen).

Switch without quitting

Inside an active session, type:

/minimal

Offered only while you are in fullscreen (including --no-alt-screen). Matcha CLI relaunches the pager on the same conversation. It does not touch config.toml. A banner reminds you how to switch back.

/fullscreen

Alias: /full. Offered only while you are in minimal. Same session-only relaunch.

If you type the command for the mode you are already in, Matcha CLI says You're already in minimal mode. (or fullscreen).

Make the default stick

For every new matcha with no flag:

1. Type /settings (aliases /config, /preferences, /prefs).
2. Set Default screen mode to Fullscreen or Minimal.

Or edit ~/.matcha/config.toml:

[ui]
screen_mode = "minimal"    # or "fullscreen"

/minimal and /fullscreen still do not write this key. Only /settings or the file does.

What exists in only one mode

Fullscreen only (hidden in minimal; /fullscreen to get them):

/dashboard is also off when MATCHA_AGENT_DASHBOARD=0 or [dashboard].enabled = false.

Minimal only (hidden in fullscreen):

To edit an existing draft when the terminal steals Ctrl+G, open the command palette and choose Edit Prompt in External Editor. Typing /edit-prompt replaces the composer, so it always starts empty.

Both modes: /, /help, Ctrl+P, /docs, /new, /model, /compact, /quit, and the rest of the ungated catalog. /help is especially useful in minimal, where there is no always-visible shortcut footer.

What a refusal looks like

Typed in minimal:

/theme isn't available in minimal mode (minimal renders with your
terminal's own palette). Run /fullscreen to switch this session.

Typed in fullscreen:

/expand isn't available in fullscreen mode — press Tab to focus the
scrollback, then → on the block.

Try this

1. matcha → send a short prompt so you have a session → /minimal.
2. Confirm /theme and /tutorial are gone from /. Type /theme anyway and read the refusal.
3. /fullscreen → /tutorial (or /tour) for the first-hour overlay.
4. Leave default mode on fullscreen unless you live in terminal scrollback and want /settings → Default screen mode → Minimal.