Reasoning effort

What the menu can show

Some Provider models advertise reasoning effort. For those, Matcha CLI can attach a level to the next turn. These four are the fallback menu when the Provider sends no reasoningEfforts list:

The live menu is model-specific:

• A model can offer a subset, extra ids (max), or none / minimal.
• A model can remap a display id (the menu might insert deep while the wire value is xhigh). Type the id the menu shows.
• A model that does not support reasoning effort rejects /effort (does not support reasoning effort) and treats /model <name> <level> as an unknown model string.

/effort never reselects the model. /model <name> <level> selects the model and the level in one shot, and that form is session-scoped (it does not write [models].default the way bare /model <name> does).

You can also set a process-wide default with [models].default_reasoning_effort or the CLI --reasoning-effort / --effort flag. The CLI flag is accepted on matcha and matcha agent. The value is still gated against the model that actually runs.

Higher effort usually means more reasoning tokens, more latency, and a higher Provider bill for the same prompt. Lower effort is cheaper and snappier when you already know the shape of the answer. Keep a strong default for design work, then drop to low or medium for mechanical edits without switching models.

See whether the current model supports effort

Type /effort and start the argument. If the current model supports reasoning effort, the menu lists its levels (strongest first in the fallback set: xhigh, high, medium, low). The active level is tagged (active).

If the model does not support effort, the argument menu is empty. /session-info also shows the active model; use that when you are unsure what you are on.

Set effort on the current model

/effort high

Empty args print usage with this model's offered ids, plus the current level when one is set:

Usage: /effort <xhigh|high|medium|low> (current: medium)

Unknown tokens print unknown effort level '…'; use one of: … and list only ids the model actually offers. none and minimal are rejected unless that model lists them.

If there is no active model (for example on a screen that has not started a session): No active model.

Set model and effort together

/model Reasoning X high
/model Reasoning X xhigh

Autocomplete: pick a reasoning-supported model, then a trailing space re-opens the dropdown on that model's levels. Selecting a row completes both tokens (Reasoning X high).

Multi-word display names are resolved as a whole first. /model Grok 4.5 selects that catalog row; it does not treat 4.5 as an effort on a shorter name Grok.

Set effort for one process

matcha --effort high
matcha --reasoning-effort medium
matcha -p "Review this design" -m reasoning-x --effort xhigh
matcha agent --effort max

--effort is a visible alias of --reasoning-effort. If both names appear, the last one wins. The flag accepts the same tokens the model will later gate — including remapped ids such as deep and extra values such as max when that model offers them.

Persist a default effort in config

[models]
default = "reasoning-x"
default_reasoning_effort = "high"

The default effort is only stamped onto models that support reasoning effort. It is not applied to a plain chat model.

What Matcha CLI does not do

• Effort is not a MatchaCode account entitlement and not a cloud thinking-mode marketplace.
• There is no product guarantee that every Provider model offers the same four levels. Always read the live /effort menu.
• Do not assume none / minimal / max exist. They are valid only when the current model lists them.

Reasoning tokens appear on the local usage block when the Provider reports them. See Local usage.