# How an agent run works

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

Source: https://maincode.com/docs/agent-runs
Section: Matilda Code · Matilda documentation

---

## 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

**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.

**Plan**

The model turns your request into a concrete plan: the files it intends to
change, the commands it intends to run, and why.

**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.

**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.

**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:

```bash
matilda --approval-mode auto-edit
```

```json title=".matilda/settings.json"
{
  "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](https://maincode.com/docs/retention) 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.