Plan Review

Plan review is the full-screen surface where Command Code presents a written plan for your sign-off — a code-review experience for plans, in the terminal. New in v1, it 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.

If you've reviewed a pull request on GitHub, plan review will feel familiar: one plan line is always selected, you leave inline comments, and you resolve the plan with a verb — Submit review, Approve, or Cancel.

Plan review pairs with Plan Mode. Plan mode is where the agent writes the plan; plan review is where you sign off on it.

At a glance

• 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 never get written into the plan document.
• GitHub-style verbs. Submit review (ctrl+r), Approve (ctrl+a) or Execute plan (ctrl+e), Cancel/Back (esc).
• 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

A plan starts in plan mode, lands in review, and loops until you approve it. Submitting a review sends it back to the agent for a revision; approving implements it; canceling saves it for later.

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

Opening plan review

There are four ways into the same review surface. All of them are scoped to a plan written during the current session.

1. Finishing plan mode

While in plan mode, the agent writes the plan to ~/.commandcode/plans/<name>.md and then calls exit_plan_mode. That 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 to review a plan (plan_review tool)

Outside plan mode, just ask:

"review plan" · "open plan review" · "show me the plan"

The agent calls the plan_review tool, which opens the review panel for the most recent plan file. This exists so the agent shows you the real review surface instead of pasting the plan back as a wall of text. In plan mode the agent uses exit_plan_mode instead — there is exactly one review path per mode.

3. The /plan-review slash command

Run /plan-review to jump straight into a review of this session's latest plan.

4. The /plans browser

Run /plans to open the full-screen plan browser — every plan from this session and past sessions, with status badges, comment counts, and search. Open any plan to read and review it. /plans <name> jumps straight into a named plan.

The automatic backstop (auto plan review)

Some models write a plan file and stop without ever presenting it. Command Code makes the review a guarantee, not a courtesy: when a run ends naturally with a plan that was written but never reviewed (in default or plan mode), the harness presents the same review panel itself. Approving it 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.

Reviewing a plan

The reader renders the plan like a document — headings, code, quotes, and tables are styled per line. One line is always highlighted. The bottom of the screen holds a fixed zone: a REVIEW badge with the pending-comment count, a single context-sensitive hint line, and the stacked review verbs. Nothing in that zone changes as you scroll — your position lives in the highlight and the gutter line number.

Navigating

Long lines wrap at a comfortable reading width (80 columns when there's room, otherwise 60) rather than truncating, so you can always read the full paragraph.

Leaving comments

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

Pinned comments show a ● gutter marker on the line and a ↳ comment row beneath it. Comments are saved to disk with the plan, so they survive closing the reader and even ending the session. They never become part of the plan document.

Editing the plan

Plan review has no separate edit mode. Press ctrl+g to hand the plan file to your $EDITOR (from $EDITOR/$VISUAL); the reader reloads when you close it. The editor is the edit surface, the reader is the review surface.

Resolving a review

The review verbs are stacked in the pinned bottom bar. Trigger them by chord from anywhere, or arrow onto them and press Enter.

Approving with pending comments

If you press Approve while comments are still pending, Command Code doesn't guess. It asks:

Choose with comments as notes and your comments are sent as a follow-up user turn — non-blocking notes the agent implements against. Choose original plan to approve it clean and drop the comments. Use ←/→ to switch, Enter to confirm, esc to back out.

Review rounds and versioning

Plan review is iterative. 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, not the whole plan again. ctrl+n/ctrl+p jump between those changed lines.

Where plans live

Plans and their metadata are stored under your home directory:

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.

Slash commands

Related tools

• exit_plan_mode — presents the plan for approval when leaving plan mode. Only valid in plan mode.
• plan_review — opens the review panel on demand outside plan mode. Renders as PLAN(review) in the activity feed.
• enter_plan_mode — switches into plan mode (with your confirmation) for read-only exploration.

Next steps

• Learn how Plan Mode and Auto-Accept mode split reasoning from execution.
• Use Checkpoints to rewind after an approved plan is implemented.
• Browse the full Slash Commands and Tools references.