Skip to content
Docs menu

Plan mode

Have the agent investigate read-only and write a plan before it changes anything, then approve the plan and let it execute.

View .md

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

  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

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.

  • Flags: every permission mode.
  • /plan-exec runs an approved plan step by step on workers, with checks per step (the automation section of these docs).