---
title: Plan mode
description: Have the agent investigate read-only and write a plan before it changes anything, then approve the plan and let it execute.
section: cli
order: 50
audience: [user, agent]
sources: [packages/harness/src/extensions/plan.ts, packages/harness/src/permissions/modes.ts]
features: [cli.plan]
---

Plan mode is the read-only permission mode. The agent reads, searches and runs read-only commands, writes its plan to a file under `.venom/plans/`, and asks you to approve it. Nothing else in the workspace can change until you do.

```bash
venom --plan "add rate limiting to the public API"
```

In a session:

```text
/plan add rate limiting to the public API     enter plan mode and start planning
/plan accept                                  leave plan mode and execute the plan
/plan                                         toggle plan mode
```

`alt+m` (or `ctrl+g m`) also cycles into and out of `plan`, and `--permission-mode plan` starts there.

## How a plan is made {#flow}

1. In plan mode only reads, searches and allowlisted read-only bash commands run. The one place the agent can write is `.venom/plans/`; bash cannot write there.
2. The agent writes the plan to `.venom/plans/<date>-<time>.md` with the `write` tool and summarises it in its reply.
3. It calls `exit_plan_mode` with the plan, and you choose **Approve** (leave plan mode and implement it) or **Reject** (stay in plan mode). Anything you type instead of choosing is feedback, and the agent revises.
4. On approval venom goes back to the mode you were in before plan mode (`accept-edits` if that was `plan` too) and the agent executes the plan step by step, verifying as the plan says. `/plan accept` does the same from the keyboard.

The agent can also propose plan mode itself with `enter_plan_mode` when a task is large or unclear.

## The tools {#tools}

| Tool | What it does |
|---|---|
| `enter_plan_mode` | Switch to read-only plan mode. |
| `exit_plan_mode` | Ask you to approve the plan and leave plan mode. |
| `todo` | A checklist for multi-step work: the model sends the full list each call and keeps one item in progress. Not limited to plan mode; the TUI shows it as a widget. |

## Without a terminal {#headless}

In print and JSON modes there is nobody to approve: `exit_plan_mode` is rejected and the agent stays in plan mode, so `venom -p --plan "…"` is a way to get a written plan and nothing else. `venom serve` and ACP hosts pass the approval to their client.

## Related

- [Flags](/docs/cli/flags.md#permissions): every permission mode.
- `/plan-exec` runs an approved plan step by step on workers, with checks per step (the [automation section](/docs/automation.md) of these docs).
