Plan Mode

Plan mode is where the agent thinks before it touches anything. It explores read-only, writes a plan, and hands it to you in a review surface. You comment, it revises, you approve — then implementation starts.

Start here

Or press shift+tab until the banner reads plan, or launch with cmd --plan.

In plan mode the agent can read files, search, and reason. It cannot edit files, run shell commands, or apply patches. When it's done it writes the plan to ~/.commandcode/plans/<name>.md and opens plan review — a GitHub-style reader where one line is always selected, you leave inline comments, and you resolve with a verb:

The permission modes

Plan mode is one rung on the permission-mode cycle. shift+tab moves between them: default → auto-accept → plan → back to default.

Two modes sit off the cycle. dont-ask is selected from settings or --permission-mode dont-ask, and shift+tab from it moves to auto-accept and rejoins the normal cycle. bypass is only reachable by launching with --yolo, which also adds it to the cycle as a fourth rung (plan → bypass → default).

To jump straight to a mode without cycling, use /mode or its shorthands: /mode:default, /mode:auto-accept, /mode:plan.

Complete guidePermissions→

Modes are only the baseline. The complete guide covers allow/ask/deny rule syntax, the decision ladder every tool call runs, safety behaviors, and the full mode-by-operation decision table.

Command Code creates a checkpoint before modifying files in any mode, so an auto-accept run is always rewindable.

Picking a mode

The usual loop: start in plan, explore and agree on the approach, approve the plan, let it run in auto-accept, rewind with checkpoints if something goes sideways.

Plan review

Plan review turns a plan into a first-class, persistent artifact you can read, comment on, revise, and approve — instead of a block of text that scrolls away.

• One mode: REVIEW. Read line by line, comment on any line, resolve with a verb. There is no separate "edit mode" — plan edits go through your $EDITOR.
• Plans persist. Every plan is saved to ~/.commandcode/plans/ as markdown and indexed, so canceling a review never throws the plan away.
• Comments are review artifacts, not plan text. They live in a sidecar overlay and only reach the agent inside a prompt — they are never written into the plan document.
• Review rounds. When the agent revises a plan, the next round diffs against the last one — changed lines render green so you re-review only what moved.
• Deterministic. A harness backstop guarantees the review is offered even when a weaker model writes a plan and simply stops.

How it works

Inside the reader one line is always selected, comments pin inline under their line, and the bottom bar holds the review verbs:

● marks a commented line and ↳ is your comment pinned beneath it. In a revised round, changed lines render green. The hint row at the very bottom carries the rest: type + enter to comment, ctrl+n/ctrl+p to jump changes, ? x ! for quick comments, ctrl+g to edit.

Four ways in

All of these open the same surface, scoped to a plan written during the current session.

1. Finishing plan mode. The agent writes the plan and calls exit_plan_mode, which opens plan review as the approval surface — the plan is the approval prompt. Approving here can also switch you into auto-accept mode so implementation runs without further prompts.
2. Asking for it. Outside plan mode, say "review plan" / "open plan review". The agent calls the plan_review tool, which opens the panel for the most recent plan file, instead of pasting the plan back as a wall of text.
3. /plan-review. Jumps straight into a review of this session's latest plan.
4. /plans. Opens the full-screen plan browser — every plan from this session and past sessions, with status badges, comment counts, and search. /plans <name> jumps straight into a named plan.

The automatic backstop. Some models write a plan file and stop without ever presenting it. When a run ends naturally with a plan that was written but never reviewed (in default or plan mode), the harness presents the review panel itself. Approving continues the run with an instruction to implement; declining lets the run end so you can steer. Modes that mean "don't interrupt me" — auto-accept, bypass, and dont-ask — skip the backstop.

Reading and commenting

The reader renders the plan like a document — headings, code, quotes, and tables styled per line. Long lines wrap at a comfortable reading width (80 columns when there's room, otherwise 60) rather than truncating.

Navigating:

Commenting is Figma-style — start typing on a line and a draft box opens inline, directly under that line, exactly where it will sit once pinned.

Pinned comments show a ● gutter marker and a ↳ comment row beneath the line. They're saved to disk with the plan, so they survive closing the reader and even ending the session.

Editing the plan happens in your editor: ctrl+g hands the plan file to $EDITOR (or $VISUAL) and the reader reloads when you close it.

Resolving a review

Trigger a verb by chord from anywhere, or arrow onto it and press Enter.

If you press Approve with comments still pending, Command Code asks rather than guessing:

With comments as notes sends them as a follow-up user turn — non-blocking notes the agent implements against. Original plan approves it clean and drops the comments. ←/→ switches, Enter confirms, esc backs out.

Review rounds and versioning

Each time you Submit review, Command Code:

1. Snapshots the current plan to ~/.commandcode/plans/versions/<name>-v<N>.md.
2. Bumps the plan's version and clears your pending comments (they were all handed to the agent in one prompt).
3. Lets the agent revise the plan, overwriting the live file.

When the revised plan comes back (version > 1), the reader diffs it against the previous round's snapshot. Changed lines render green, and the badge line reports round N · M lines changed — so a second review means re-reading only what actually moved. ctrl+n/ctrl+p jump between those changed lines.

Where plans live

Every plan carries a status:

• pending — written but not yet taken through review.
• approved — you approved it and moved to implementation.
• not-implemented — you canceled the review; the plan is kept for later reading, commenting, and revision.

Because a canceled plan is recorded rather than discarded, planning never feels throwaway — reopen it any time with /plans. Writes to ~/.commandcode/plans/*.md never prompt for permission in any mode, and only .md files there get that exemption, so the plans directory can't double as a scratchpad.

Reference

Slash commands

CLI flags

Tools

See also

• Permissions — the rule syntax and decision model behind every mode.
• Checkpoints — rewind after an approved plan is implemented.
• Tools and Slash Commands — the full references.