Read the plan before the agent builds it.

Where plan mode stops

Plan mode does one thing very well: it holds the agent still before it edits anything, and shows you what it intends to do. What it hands back is a decision with two answers, and most plans need a third.

What to check in an agent's plan

Agent plans read well and leave out the same six things. Going down this list takes about two minutes and catches most of what turns into a bad afternoon later.

Ask for the plan as a file first

A plan that lives only in the session cannot be marked up. Ask for it on disk — "write the plan to plan.md before you change anything" — and you have a document instead of a transcript. Put that line in CLAUDE.md or AGENTS.md and it happens on its own from then on. Then open the file for review: the first two commands install the plugin once, and the third opens the document and waits.

/plugin marketplace add migsilva89/imark
/plugin install imark@imark

/imark:imark-review plan.md

What a note looks like inside the plan

Select the words you disagree with, write in the margin, and this is what lands in the file. It is an HTML comment, so GitHub, Obsidian and every other Markdown renderer show the plan exactly as before — the note is only visible in the raw text and in Imark. The same format is covered in full on annotating Markdown for review.

## 3. Migration

The rewrite runs in a single pass over the table.

<!-- imark quote="a single pass over the table" by="miguel" at="2026-08-18T09:14:22Z"
Not against production. Batch it, 5000 rows at a time, and say what
happens when the job dies halfway through.
-->

What the agent reads when you send it back

Press Send Back and the command returns. The agent does not get a summary of your mood; it gets an instruction and then every note, each one carrying the words it was attached to, the section it fell under and the line above it. Six numbered steps follow the opening, and the first of them is to answer you before touching anything.

THE REVIEWER DID NOT APPROVE THIS. Do not rewrite anything yet.

Work through this in order. Do not skip to the last step.

1. Read every note below. Open the annotated document when a note needs the
   text around it: /Users/miguel/project/plan.md
2. Before changing anything, reply to the reviewer. Take the notes one at a
   time, quote the words each is attached to, and say what you understood and
   what you intend to do about it.
[…]

### Note 1 — on “a single pass over the table”
miguel, 2026-08-18 · line 42
Section: 3. Migration
> The rewrite runs in a single pass over the table.

Not against production. Batch it, 5000 rows at a time, and say what
happens when the job dies halfway through.

Reviewing the plan without asking for a file

There is also a hook that catches plan mode itself. Set one variable and leaving plan mode opens the plan in Imark and waits; commenting and sending it back denies the permission request and hands the agent your notes, so it revises instead of building.

export IMARK_PLAN_REVIEW=1

When Imark is the wrong tool

It is a narrow tool and there are four situations where something else is the better answer. Three of them point at the same place.

Why the notes go in the file

A review that lives in a tool is a review you lose when you change tools. Because each note is part of the document, it shows up in the diff beside the paragraph it argues with, gets committed with the plan, moves between branches, and can be sent to a colleague who has never installed anything. If you want the plugin's commands and the rest of what it returns, the plugin page covers installing and using it.