05. Permissions, Plan Mode, and Safety

Plan before it acts

Plan mode is a read-mostly phase: the assistant explores, writes a plan, and waits for you before it edits the project.

Separate approach from implementation

While plan mode is active, the only file the assistant may edit is the session plan file. Approving the plan starts the build. Quitting the plan turns plan mode off without implementing.

How plan mode works

The assistant (or you) enters plan mode. It reads and searches, writes plan.md, may ask clarifying questions, then calls exit_plan_mode. The TUI opens a scrollable preview with an action bar.

The plan file lives under the session directory:

~/.matcha/sessions/<encoded-cwd>/<session-id>/plan.md

<encoded-cwd> is a URL-encoded working-directory name, not the literal path. Set MATCHA_HOME to move the home tree.

A typical plan has context, one recommended approach, critical paths, reuse targets, and how to verify end to end.

Lifecycle

State	Meaning
`Inactive`	Normal mode. No plan-file gate.
`Pending`	You toggled plan on; the next prompt activates it.
`Active`	Plan-file edits auto-approve; other file edits are rejected.
`ExitPending`	You toggled plan off while a turn is still running.

/plan or Shift+Tab from Normal goes Inactive → Pending, then Active on your next prompt. The assistant’s enter_plan_mode tool, if you approve it, jumps Inactive → Active. Plan state is saved; Pending and ExitPending collapse to Inactive on restart.

Edits to any file other than the plan fail with a short message naming the plan file as the only editable path. That gate holds in every permission mode, including always-approve.

The status chip shows plan while active. If always-approve is on underneath, its chip returns when plan mode exits. /compact keeps the plan-mode reminder in the compacted context.

When to use it

Use plan mode when the approach is the expensive part: authentication shape, a pipeline redesign, several plausible cache designs. Skip it for a typo, a delete button that follows existing UI, or a bug whose fix is obvious once you have seen the code.

A good habit: plan mode for “how should we even do this?”, ask mode for “just do it”.

Enter plan mode

/plan
/plan Redesign the auth middleware

/plan — Pending. Plan mode activates when you send the next prompt.
/plan <description> — enter and start a turn with that text.

Shift+Tab (prompt focused) also lands on Plan from Normal. The assistant can propose enter_plan_mode; declining leaves you in normal mode.

Review a saved plan

/view-plan

Aliases: /show-plan, /plan-view. Reopens the saved preview after a plan exists. If nothing is on disk, the TUI toasts No plan written yet.

If the assistant exits plan mode with an empty or missing plan.md, the same approval surface still opens. The preview body is a placeholder starting # No plan written yet, and the status line reads No plan written — approve or request changes so you can approve, request changes, or quit. /view-plan with nothing saved toasts No plan written yet.

Approval keys

Scroll with the arrows or j / k. Tab moves focus between the preview and the prompt. Ctrl+P can still change model before you approve.

Key	Action
`a`	Approve and start building. With pending inline comments this reads approve w/ comments and sends them with the approval.
`s`	Request changes. Focus moves to the prompt; `Enter` sends the notes. Plan mode stays on.
`c`	Comment on the selected line or range (`Enter` on a line also starts a comment).
`y`	Copy the full plan to the clipboard.
`q`	Quit plan — abandon it and turn plan mode off.
`Esc`	From the prompt, return focus to the preview. Does not quit.

Leave without implementing

Press q on the approval view. That abandons the proposed plan and turns plan mode off. Toggling plan off while idle (another Shift+Tab cycle, or the mode control) also exits when no turn is in flight.