10. Configuration, Themes, and Terminals

Settings

Change common preferences from inside a session. /settings opens a local modal that writes ~/.matcha/config.toml (and a few in-memory pager flags). Nothing is uploaded. There is no remote settings sync.

Open the modal

Any of these:

/settings
/config
/preferences
/prefs

Keyboard (in a session): F2, Ctrl+, or Cmd+, (macOS).

/settings works in fullscreen and in minimal. Theme, auto-dark, and auto-light rows are hidden in minimal because that mode has no Matcha palette — use /fullscreen first, or /theme (fullscreen-only). See Themes.

Arguments after /settings are ignored. The modal always opens at the top. Type / inside the modal to filter by label, description, or keyword.

Move around

Input	Effect
`j` / `k` or arrows	Move between rows
Space	Toggle a boolean
Enter	Open a chooser or inline editor
`/`	Filter; Esc leaves filter without closing Settings
Esc (browse)	Close the modal
F2 / Ctrl+, / Cmd+,	Close from any inner mode

Most changes apply immediately and are written to user config.toml. Rows marked restart-required (for example Default screen mode) wait until the next launch.

There is no /settings <id> jump. Filter, or open a focused row from another command (for example /privacy focuses Coding data (local)).

Categories

The modal uses this order:

Section	Typical rows
Appearance	Theme, auto dark/light, compact mode, default screen mode, timestamps, timeline, snap-on-send, thinking blocks, group tool calls, collapsed edits
Mouse	Scroll speed / input / lines, invert scroll, text selection
Editor & Input	Disable vim input mode (`simple_mode`), vim scrollback navigation, multiline
Agent & Approval	Permission mode, remember tool approvals, default selected permission, Ask-Question timeout, plan mode
Privacy	Coding data (local) — stays on this machine
Models	Default model
Session	Combine queued prompts, confirm before rewind, prompt suggestions
Advanced	Auto-update, hunk tracker, contextual hints (including SSH wrap)

Default screen mode writes [ui] screen_mode. /minimal and /fullscreen (and --minimal / --fullscreen) are session-only and do not write that key.

Voice shortcut / capture / language rows may appear. /voice and speech capture are unavailable. Do not rely on them.

Coding data (local) does not send prompts or traces off-device. Remote training opt-in is not offered.

What Settings will not do

Sync preferences to a MatchaCode account or org control plane.
Replace matcha login --provider or Provider env keys.
Edit pager.toml layout keys. Those stay in the file; see Files and environment variables.

Org or leftover requirements.toml / managed_config.toml on disk can still pin values matcha inspect will show. Settings writes your user config.toml only.

Check your work

/settings, filter screen, set Default screen mode, quit, and relaunch. Confirm plain matcha follows the choice.
Toggle Snap prompt to top on send and send a prompt: no restart.
In minimal, open /settings and confirm Theme is absent; /fullscreen then /theme still works.