Plan mode before the first edit

Why this matters

Some tasks have more than one honest design. If Grok starts writing before you have picked an approach, you will spend the next hour deleting the wrong one. Plan mode is the product’s answer to that: a gated planning phase. The agent explores, writes a plan, and waits. Code does not change until you approve.

You do not use plan mode to add a delete button or fix a typo. You use it when the approach is the actual decision — auth style, cache, pipeline shape, “should this even be a new package.” This module is how you enter, read, mark up, and leave that phase without accidentally building.

Teach

What plan mode is

When plan mode is active, Grok:

1. Reads and searches the codebase
2. Writes an implementation approach to the plan file
3. May ask you structured questions (ask_user_question)
4. Calls exit_plan_mode, which opens the approval preview

Plan mode is read-only except for the plan file. Edits to plan.md in the session directory are auto-approved. Edits to any other file are rejected outright — the tool fails and names the plan file as the only editable path. That hold applies in every permission mode, including always-approve. Always-approve stays armed underneath; non-edit tools (reads, many shell commands, MCP) can still auto-run, but file edits stay blocked until you approve the plan. Then always-approve comes back for implementation. You should still be in ask mode from C2.

The status flag shows plan while this is on.

How you get there

You start it:

• /plan — plan mode turns on when you send the next prompt
• /plan add session auth to this app — enter and start that turn in one step
• Shift+Tab — cycle Normal → Plan → Always-approve → Normal. One press from Normal is Plan. Do not overshoot.

The agent starts it when the task looks genuinely ambiguous. enter_plan_mode itself needs your approval. If you decline, Grok stays in normal mode and will try to build. Decline when you already know the approach. Approve when you do not.

Good triggers from the docs: “add user authentication,” “redesign the data pipeline,” “add caching,” “add real-time updates.” Bad triggers: a delete button, a typo, “update error handling,” “can we work on search” when you meant start coding.

After a plan exists, /view-plan (aliases /show-plan, /plan-view) reopens the saved preview.

Where the plan lives

The file is plan.md inside the session directory:

~/.grok/sessions/<encoded-cwd>/<session-id>/plan.md

The <encoded-cwd> piece is an encoded directory name, not your literal path. On Windows you will see something under %USERPROFILE%\.grok\sessions\. You do not have to hunt it during the lesson — the TUI preview is the review surface. Know the path so you understand what is being edited while everything else is locked.

A real plan, per the docs, has:

• Context — why the change exists
• The recommended approach, not a catalog of every alternative
• Paths of critical files
• Existing functions and utilities to reuse, with paths
• Verification — how you will test end to end

If those sections are missing or vague (“update the relevant files,” “add tests as needed”), that is not a plan. Send it back.

The approval bar

When Grok exits plan mode, the TUI opens a scrollable preview with a bar at the bottom. Arrow keys or j/k scroll. Tab moves between preview and prompt. Ctrl+P still switches model before you approve.

Three focus states: preview (scroll and select), commenting (after c or Enter on a line), prompt (freeform notes). Feedback — inline, freeform, or both — goes back to the agent. It revises. You can loop.

Esc from the prompt returns to the preview. Esc does not approve. To leave without building, press q.

If Grok exits without writing a plan (empty or missing plan.md), the same surface still opens with an empty-state message. You can approve and wing it, request changes, or quit. Do not approve an empty plan.

State machine, short

Inactive → Pending (you toggled /plan or Shift+Tab, no prompt yet) → Active (first prompt). Agent-initiated enter_plan_mode skips Pending and goes Active after you approve the tool. Active → Inactive when you approve exit_plan_mode or toggle plan off while idle. If you toggle off mid-turn, you pass through ExitPending until the turn ends.

Plan mode persists across process restarts. Pending and ExitPending collapse to Inactive on restart because they depend on in-flight UI.

/compact during an active plan keeps plan mode on and reminds the agent it is still planning.

Limits you should not ignore

• Plan mode blocks edit tools, not the shell. run_terminal_command is not inspected for redirects. A > in bash can still write a file. Stay in ask mode. Reject surprise writes.
• Subagents do not inherit the parent’s plan-mode edit gate. A write-capable subagent can edit while the parent is still planning. Do not spawn implementers from a plan session. C8 covers subagents. Today: one session, no “go build that in a child.”

Worked example

Scratch repo. Add a tiny notes.txt with three lines of fake feature ideas, or just use the README. You need a small tree, not a real product.

Shift+Tab once so the flag says plan, or type /plan. Then send:

I want a way to record practice sessions for this repo: date, what I tried, what I refused. There are several reasonable shapes (a markdown log, a JSONL file, a /log slash-style convention in the README). Explore this directory, pick one approach that fits a one-person scratch repo, and write a plan. Do not implement.

That prompt is ambiguous on purpose. If Grok asks a question card, answer it — pick one option or type a free-text row. When the plan preview opens:

1. Scroll the whole thing. Confirm Context, approach, file paths, reuse, verification.
2. If it proposes a database, an npm app, or five new packages, press s and write: “One markdown file in this repo. No new runtime. No dependencies.”
3. When the revision lands, use c on any line that still says “etc.” or “as appropriate” and write what “done” means (for example: PRACTICE-LOG.md with a heading template; verification is git diff showing only that file).
4. Press y and keep a copy for the exercise artifact.
5. Press q or a — for this worked example, press q. You are learning the gate, not filling the repo. The next module is where a plan becomes a diff.

If you already pressed a, /quit, reset the files with git, and do not treat the extra files as required.

If you do not write software. Plan mode is not only for “auth style” and new packages. Use it when a folder of letters or a price list could be organized more than one honest way — one file vs three, a date heading vs a table, a log vs a rewrite. The plan must still name paths and how you will know it is done. Press q after you have a plan you would accept. You do not need application code to practice the gate.

Your turn

Do c3-l01-e1 in Grok Build. You will enter plan mode yourself, get a plan for an ambiguous task, mark it up or send it back at least once, and either quit or approve only after the plan names files and a verification step. Reading the preview is the work. Approving a foggy plan is a fail.

Common failure

You Shift+Tab’d twice and landed on Always-approve. Look at the status flag. Cycle back to Plan, or to Normal and /plan.

You typed the task before /plan. /plan with no argument waits for the next prompt. If you already sent the task in Normal, Grok may start editing. /plan the follow-up (“stop implementing; write a plan only”) or reject edits until you are in plan mode.

You approved from the first screen. A plan that does not name files is a blog post. s exists.

You thought yolo was off because plan mode blocked edits — then approved and watched it run everything. Always-approve underneath comes back after a. Stay in ask mode before you approve.

You used a shell write during planning (echo ... > file). Plan mode did not save you. Reject the command.

What’s next

C4 is the other half: a real repo, a real diff, and you on the hook for what landed. If you approved a plan, implementation is just C2’s permission cards with more files. Read every one.

I need a practice log for this repo. Reasonable options include a markdown log, a JSONL file, or a short convention in the README. Explore the tree, pick one approach that fits a one-person scratch repo with no new dependencies, and write a plan. Do not implement.