# How to use plan mode

> A read-only turn that reads your code and answers before anything is written. One plan turn routinely saves three wrong builds.

Canonical: https://vibely.sh/guides/how-to-use-plan-mode
Last updated: 2026-09-19

Published 2026-09-19 · Build workflow · 5 min read

## Reference documentation

- [Prompting best practices](https://docs.vibely.sh/prompting/best-practices)
- [Iterate](https://docs.vibely.sh/features/web-apps/iterate)
- [Tools](https://docs.vibely.sh/reference/engine/tools)

[Plan mode](https://vibely.sh/features/agent#plan-mode) is **read-only**. The agent can read, search, browse and reason; it cannot write a file or run a command. The allowlist is exactly: `read`, `list_files`, `glob`, `grep`, `web_search`, `web_scrape`, `db_schema`, `read_runtime_errors`, `mcp_list`, `mcp_call`, `spawn_subagent`, `use_skill`, `ask_user` and `exit_plan_mode`. Nothing in that list touches your code.

## When to reach for it

Anything that touches more than a handful of files: multi-tenancy, a payment flow, swapping a data layer, a schema change, an auth migration. The default mode is build, which is right for feature work and wrong for a decision you have not made yet.

> "We're about to add multi-tenancy. Read the auth and DB code and tell me what would have to change. Don't write anything yet."

You get back a structured plan — overview, key decisions, architecture, user journeys, data models, files, steps, dependencies. Read it, argue with it, then approve:

> "Good, but keep the existing `profiles` table. Go ahead and implement that."

The agent calls `exit_plan_mode` and the full toolset unlocks.

## The other use: breaking a loop

When the agent keeps making the same wrong edit, more build turns will not help — it is working from a wrong model of your code and each turn reinforces it. Switch to plan mode and ask for the cause instead of the fix. A read-only turn cannot make the situation worse, which is precisely why it is the escape hatch.

## Audits are plan-mode questions

Scope them, or you get a list too long to act on:

```
Switch to plan mode. Audit the database policies: list every table, whether RLS
is on, and whether the policies actually restrict rows to their owner. Flag
anything a logged-in user could read that isn't theirs. Don't change anything.
```

```
Switch to plan mode. Audit accessibility on the checkout flow only: labels,
focus order, contrast, and whether errors are announced. Give me a ranked list
with the file and line for each.
```

Then pick from the list one turn at a time. "Fix everything you found" produces a diff you cannot review.

## What it costs

Plan turns are billed like any other turn — a long plan over a large codebase is not free. It is still cheaper than three wrong builds, and much cheaper than shipping the second-best architecture. See [how credits are charged](https://vibely.sh/guides/how-credits-are-charged).

## Plans are not memory

Chat context compacts once a conversation crosses 90% of the model's context window, and a new chat starts empty. A decision that must survive that goes in **Knowledge** (Settings → Knowledge, project-scoped or workspace-scoped, 10,000 characters each), not in a message you hope the agent still remembers.

## Related

- [How to scan your app for security issues](https://vibely.sh/guides/how-to-scan-your-app-for-security-issues) - previous guide
- [How to sync your project to GitHub](https://vibely.sh/guides/how-to-sync-your-project-to-github) - next guide
- [Build workflow guides](https://vibely.sh/guides/category/workflow)
