> ## Documentation Index
> Fetch the complete documentation index at: https://docs.open4rena.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Plan mode

> Let the model research and plan before it changes any files.

Plan mode is a read-only mode for research. While it's on, the model can read,
search, and fetch, but it can't edit files, write files, or run shell commands.
Use it when you want the model to study the code and propose an approach before
anything changes.

## Turn plan mode on and off

There are three ways in and out:

* Press `Shift+Tab` in the prompt to toggle plan mode.
* Type `/plan` to turn it on. The model can call `exit_plan_mode` to turn it
  off when it's ready to implement.
* The model can turn it on itself by calling the `enter_plan_mode` tool.

`/plan` isn't listed in `/help`, but it works. To move the toggle to another
key, bind the `toggle_plan_mode` action in
[`[keybindings]`](/reference/keyboard-shortcuts#remappable-actions).

While plan mode is on, `PLAN` appears on the left of the second row below the
prompt box. Each time the mode changes, o4 tells the model which tools it gained or
lost.

A typical flow:

1. Press `Shift+Tab`.

2. Ask for a plan, for example:

   ```text theme={null}
   Read the auth module and plan how to add refresh tokens. Don't change anything yet.
   ```

3. Read the plan, ask questions, and ask for changes.

4. Press `Shift+Tab` again, or tell the model to go ahead. The model calls
   `exit_plan_mode` and gets its full tool set back.

## What the model can use in plan mode

Plan mode limits the model to this fixed list of tools:

| Tool | Purpose |
| - | - |
| `read`, `glob`, `grep`, `ls` | Read and search files |
| `fetch` | Fetch a URL |
| `task_create`, `task_update`, `task_list` | Background task bookkeeping |
| `enter_plan_mode`, `exit_plan_mode` | Switch modes |

Every other tool is hidden from the model, and a call to one fails with
"Tool '...' is blocked in plan mode". That covers `write`, `edit`, `bash`, the
`agent` and `campaign` tools, MCP tools, and the `plan_*` tools described
below.

<Note>
  Plan mode is separate from your approval mode. Approvals still apply to the
  tools that plan mode allows, and switching plan mode on or off doesn't change
  your approval mode.
</Note>

## The Plan approval mode

o4 also has an approval mode named Plan. It's one of the options for
`--permission-mode` (`ask`, `accept-edits`, `plan`, `review`, `auto`,
`bypass`), and `Alt+A` cycles through the approval modes in a session.

In the Plan approval mode, o4 denies every tool call that would normally need
your approval: edits, writes, shell commands, web fetches, and so on. Tools
that never ask, such as `read`, `grep`, and `glob`, still run. Unlike plan
mode, the model still sees its full tool list. It finds out a tool is off
limits only when a call is denied.

Start a read-only session from the command line:

```bash theme={null}
o4 --permission-mode plan
```

For the full list of approval modes, see [permissions](/safety/permissions).

## Structured plans

Outside plan mode, the model has tools for keeping a multi-step plan on disk:

| Tool | What it does |
| - | - |
| `plan_create` | Save a new plan with a title and an ordered list of steps. The plan starts as a draft. |
| `plan_status` | Show a plan's steps, each step's status, and the overall percentage done. |
| `plan_modify` | Rewrite the description of a step that is still `pending`. Steps with any other status can't be changed. |
| `checkpoint_create` | Tag the current git `HEAD` as `o4/checkpoint/<plan_id>/<timestamp>` before a risky change. Without a `plan_id`, the tag uses `manual`. |
| `checkpoint_restore` | Check out the tracked files from a tag or other git ref. |

Plans are JSON files in `.o4/plans/` in your project. A plan's status is one
of `draft`, `approved`, `executing`, `completed`, or `failed`. A step's
status is one of `pending`, `in_progress`, `completed`, `failed`, or
`skipped`.

`plan_create` and `plan_modify` ask for approval once per session in the
default approval mode. `plan_status` never asks. `checkpoint_create` asks once,
and `checkpoint_restore` asks every time.

The checkpoint tools need a git repository. `checkpoint_restore` overwrites
tracked files with their content at the tag. It refuses to run while you have
uncommitted changes, including untracked files, unless the model passes
`force`, which discards those changes.

<Warning>
  Read the approval prompt before you allow `checkpoint_restore`, and check
  whether it uses `force`. To undo the model's file edits, you can also use
  [undo and rewind](/guides/checkpoints).
</Warning>

### Approving a plan

When the model creates a plan, the tool result ends with "Plan saved. Awaiting
user approval." and the model waits for your answer. There's no approval
dialog: you approve by replying, for example `Looks good, go ahead` or
`Do step 2 before step 1`.

Replying doesn't change the plan's status on disk. The plan stays a draft,
and its steps stay `pending`: in o4 0.2.74, none of the model's tools or your
commands mark a plan `approved`, `executing`, or `completed`, or mark a step
done. `plan_status` shows the steps, but its progress doesn't move. Track the
model's progress with its [todo list](/guides/tasks-and-todos) instead.

### The plan status row

o4 can show a plan's progress in the status row while the model is idle, for
example `Plan 2/5 · Add the refresh endpoint`: the number of steps done, the
total, and the current step. After each turn, o4 reloads the row from
`.o4/plans/` and shows only the newest plan marked `approved` or `executing`,
so a draft plan leaves the row after the next turn. To hide the row, run:

```text theme={null}
/plan clear
```

`/plan dismiss` and `/plan close` do the same. They only hide the row; the
plan file stays as it is.

### Plans across sessions

Each plan is linked to the session that created it. When you resume that
session with `o4 resume`, o4 restores its linked plan, shows it in the status
row, and asks **Continue** or **Abandon**. Abandon marks the plan as failed and
clears the row. While the plan isn't `completed`, o4 also gives the model a
short summary of the plan and its steps on every turn of the resumed session.

When you start a new session, o4 asks the same question only for a plan marked
`approved` or `executing`. Because plans the model creates stay drafts, this
doesn't happen for them in 0.2.74.

To keep a restored plan without being asked, set `auto_approve_plans` in
`.o4/config.toml` or `~/.o4/config.toml`:

```toml theme={null}
auto_approve_plans = true
```

## Related pages

* [Subagents](/guides/subagents): the built-in `Plan` subagent designs a plan
  in its own context.
* [Todos and background tasks](/guides/tasks-and-todos): a lighter checklist
  the model keeps while it works.
* [Goals](/guides/goals): keep the model working toward one objective.