Plan Mode vs a Reviewable Plan

Plan mode vs. a reviewable plan

npm install --global @thisisnsh/planx

Plan mode is the pause an agent takes before it writes code. A reviewable plan is what you get when that pause produces a file instead of a message. They solve different halves of the same problem, and the second one starts where the first one ends.

What plan mode gives you

Claude Code's plan mode — and the equivalent in every other agent — makes the agent research first and propose second. It stops it from editing files while it is still working out what to do, and it puts an accept/reject gate in front of the work. That is genuinely useful, and PlanX does not replace it.

What it hands you at the gate is a message. It is long, it arrived all at once, it scrolls, and the only two things you can do to it are approve it or reject it. If line 40 is wrong and the other 200 lines are right, your options are to accept a plan you know is wrong or to reject the whole thing and re-explain in prose what you wanted instead.

That is where plan mode stops.

What a reviewable plan gives you

PlanX takes the plan out of the conversation and stores it as a version:

• It is a file, so it survives. The plan is on disk in ~/.planx, under a plan id and a version number. Closing the agent does not lose it, and neither does a context window that has moved on. See Installation.
• You can say what is wrong with line 40. Put the cursor on it, press v, extend the selection, press f. The comment attaches to those exact lines, so the agent gets a location rather than a paraphrase. See Feedback and edits.
• You can write the line yourself. e rewrites a line in place. An edit says this is the wording, I have decided — the agent reproduces it rather than interpreting it.
• The next version is a diff. When the agent revises, PlanX shows a word-level diff against the version before, with unchanged runs collapsed. A rewritten approach cannot slip past as re-flowed text. See Versions and diffs.
• Approval refers to a number. You approve v3, and v3 is what gets built — not the newest thing in the directory, and not a summary someone remembered from chat. See Hand-offs.
• The plan outlives the agent that wrote it. Claude Code can plan and Codex can build, because the hand-off is a version number and a file. See Custom agents.

They are not alternatives

The two work together, and the order matters: PlanX expects you to leave plan mode. The accept/reject gate is where PlanX starts.

A normal run looks like this. You invoke /planx <task>. The agent clarifies what it needs to, researches the repository, writes a structured plan and captures it as v1. It stops there — it does not build anything. You open the review in the terminal, read it with the sections folded, comment on what is wrong, and hand it back. The agent revises with its research still in context and captures v2. You read the diff. When there is nothing left to change, you send v2 to be built.

Plan mode makes the agent think first. PlanX makes what it thought reviewable, comparable and approvable — and makes the approval refer to something specific.

When plan mode alone is enough

Honestly: often. If the change is small, if you can hold the whole plan in your head while you read it once, and if you are going to build it in the same session you planned it in, the gate is the whole review and a stored artifact is overhead you do not need.

PlanX earns its place when the plan is long enough that you cannot review it in one pass, when you want to disagree with part of it rather than all of it, or when the thing that plans and the thing that builds are not the same session.

Next

• Why review an agent's plan — the case, if you are not yet sure you need this.
• Planning with Claude Code — the workflow, end to end.
• Custom agents — use the skill and review with another agent.