Ask, auto, and always-approve

Three modes

Always-approve and auto are mutually exclusive. Always-approve wins when both are requested. Plan mode is a separate session mode — it can sit on top of always-approve and still block file edits. See Plan before it acts.

The product name is always-approve. Config and Claude-compatible settings may say bypassPermissions for the same mode.

What each mode does

Ask

Default for the TUI. Risky edits, shell, and external tools pause on a card. Reads and the built-in read-only command list do not, unless a rule or hook says otherwise.

Auto

A classifier (plus fast paths) approves routine local work. Dangerous or unclear calls still prompt, or fail in non-interactive sessions (Auto mode blocked this action …). /auto is offered only when the auto-mode feature is on (the usual default). When that gate is off, /auto is neither listed nor executable.

Always-approve

Skips ordinary cards so tools run without a click. deny rules, PreToolUse hooks, and some shell ask rules that match command segments still apply. Remembered grants (including “never allow”) are not consulted. ask rules on non-shell tools do not prompt.

Native [ui] permission_mode accepts ask, default (same as ask), auto, and always-approve. Unknown values fall back to ask.

Claude-compatible permissions.defaultMode also understands acceptEdits, dontAsk, bypassPermissions, and plan. Those names are compatibility, not extra MatchaCode products. --permission-mode accepts that Claude-style list (default, acceptEdits, auto, dontAsk, bypassPermissions, plan).

In the TUI

/always-approve is a toggle: off → on, on → ask. It ignores extra arguments. The toast on enable is ⚠ Always-approve ON: all tool actions auto-run (under plan mode it warns that file edits stay blocked).

/auto turns auto on from ask or from always-approve. Running it again while already in auto returns to ask.

In the matcha agent / shell builtin list, /always-approve is aliased as /yolo (and accepts on / off there). The interactive TUI command does not register that alias — type /always-approve. The CLI flag alias --yolo does work.

Shift+Tab cycles Normal → Plan → Auto → Always-Approve → Normal when auto mode is available (the default). If auto is gated off, the ring skips Auto (Normal → Plan → Always-Approve). From Normal, one press lands on Plan. A plan-mode nudge on screen collapses Auto or always-approve to ask first so that press still reaches Plan.

From the command line

matcha --always-approve -p "Run the test suite"
matcha --yolo -p "Run the test suite"          # same flag
matcha --permission-mode auto
matcha --permission-mode bypassPermissions
matcha agent --always-approve stdio

--always-approve also accepts the older alias --dangerously-skip-permissions. CLI overrides [ui] permission_mode for that process. Always-approve takes precedence if you pass both always-approve and auto.

ACP clients can set "_meta": { "yoloMode": true } on session/new.

Config

# ~/.matcha/config.toml
[ui]
permission_mode = "always-approve"   # or "auto", "ask"

Toggling in the TUI persists the same key.

Remember this command

Per-command Always allow: cargo test / “never allow” rows are off until you enable them:

[ui]
remember_tool_approvals = true

Those grants are personal, per project, stored outside the repo. Commands on the built-in dangerous list (rm, chmod, git push, and others) prompt again instead of using a remembered prefix. An explicit allow rule or always-approve still covers them.

Lock always-approve off

Administrators can pin always-approve off:

# ~/.matcha/requirements.toml  or  /etc/matcha/requirements.toml
[ui]
disable_bypass_permissions_mode = true

Do not use permission_mode for this lock; that key is a switchable default. Legacy [ui] yolo = false in requirements.toml also pins always-approve off.