Guides

How an agent run works.

Read, plan, act, verify, and the five approval modes.

What a run is

When you give Matilda Code a task, it does not answer in one shot. It runs a loop, read, plan, act, verify, and pauses for you at the points that matter. In the default mode nothing is written to your files or run in your shell without you seeing it first.

Note

The loop is not there to look busy. It is there so a wrong step gets caught by the next one, a failing test or a bad diff, instead of shipping.

The loop

01
/05
Read
The agent pulls the files it needs into context from your working tree. It reads what is relevant to the task, and you can see every file it opens.
02
/05
Plan
The model turns your request into a concrete plan: the files it intends to change, the commands it intends to run, and why.
03
/05
Approve
Your gate. Edits are shown as diffs and commands as the exact line to run. How often you are asked depends on the approval mode.
04
/05
Act
On approval the change goes through the action layer: the edit is written, or the command runs in your shell. One step at a time, so a bad step stops the run instead of compounding.
05
/05
Verify
The agent runs your tests or build, reads the output, and decides whether the step worked. If it did not, it loops back to plan with the failure in context.

The five approval modes

Approval is a mode, not a single setting. Cycle through them mid-session with Shift+Tab, or Tab on Windows. The status bar always shows where you are.

Field	type	description
plan	read-only	Analysis only. No edits, no commands. Best for exploring a codebase or planning a change.
default	ask permissions	Edits and commands both need approval. The balanced choice, and the one to use on unfamiliar code.
auto-edit	edits auto	Edits are auto-approved; shell commands still ask. Good for a run of safe refactors.
auto	classifier	A classifier evaluates each edit and command. Fewer interruptions than auto-edit, more caution than yolo.
yolo	everything auto	Edits and commands both auto-approved. Trusted personal projects and controlled automation only.

The cycle order is plan → default → auto-edit → auto → yolo and back to plan.

Caution

yolo approves shell commands as well as edits. Pair it with --sandbox when the prompt is not entirely under your control.

Set a mode for one run from the command line, or make it the default for a project in settings:

Shell

matilda --approval-mode auto-edit

Data

{
  "tools": {
    "approvalMode": "default"
  }
}

Note

The mode once called Default is now Ask Permissions in the UI. The configuration value stayed default for backward compatibility, which is why the setting and the label do not match.

Steering a run

You steer while the run is happening, not just at the start. Interrupt at any time and redirect; the agent folds your correction into the plan and keeps its place.

To make guidance stick across runs, tell the agent to remember it and it goes into project memory:

remember: always use pnpm in this repo, never npm

See Context and memory for where that gets written and who else can see it.

Guarantees

In plan and default, nothing is written or run without approval. The diff or the command is shown first, every time.
The agent has no life outside your session. It acts only while you are there and stops when you close it.
Loosening approval is always an explicit act, a flag or a mode change, never a default that drifts.