Plan mode
Have the agent investigate read-only and write a plan before it changes anything, then approve the plan and let it execute.
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.
venom --plan "add rate limiting to the public API"In a session:
/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 modealt+m (or ctrl+g m) also cycles into and out of plan, and --permission-mode plan starts there.
How a plan is made
- 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. - The agent writes the plan to
.venom/plans/<date>-<time>.mdwith thewritetool and summarises it in its reply. - It calls
exit_plan_modewith 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. - On approval venom goes back to the mode you were in before plan mode (
accept-editsif that wasplantoo) and the agent executes the plan step by step, verifying as the plan says./plan acceptdoes 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
| 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
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: every permission mode.
/plan-execruns an approved plan step by step on workers, with checks per step (the automation section of these docs).