You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
How to review a Claude Code plan before it writes any code
npm install --global @thisisnsh/planx
Claude Code can plan before it codes. But what you get back is one long message with an accept button under it. If line 40 is wrong, your only options are to accept a plan you know is wrong, or reject the whole thing and re-explain it in prose.
Here's a workflow that fixes that.
1. Ask for a plan
/planx add rate limiting to the public API
This loads the PlanX skill, which:
exits plan mode
asks any setup questions up front, in one batch
reads the repo
writes the plan to disk instead of dumping it into chat
When it's done, it prints one line and stops — no build, no polling:
Plan created. Exit the agent, then run planx <plan-id> v1
Exit the agent. The plan is now a file under ~/.planx, so it's still there tomorrow, after the context window has moved on.
2. Open the review
planx <plan-id> v1
This opens a terminal review — not a message in a scrollback:
A 400-line plan read top to bottom is a plan you skim. Press space to fold the section under the cursor, starting with everything you agree with. What's left on screen is what you're actually deciding on.
space — fold the section under the cursor
h — fold every comment at once
j — jump between comments
g / G — jump to the start / end
? — full key list
Reviewing isn't reading the whole thing again — it's finding the four lines you disagree with.
4. Say exactly what's wrong
Put the cursor on a line, press v, extend with the arrows, press f. The comment attaches to those exact lines, not to the plan in general.
Three keys, three different acts:
f — a comment on the selected lines. This is wrong, here.
n — a note about the whole plan. Use it for something that applies everywhere, not to one passage.
e — rewrite the line yourself. The agent reproduces your wording instead of interpreting a comment about it.
That last one is worth using more than it looks — half the time you already know the right wording, and typing it is faster than describing it.
The revision comes back as v2, shown as a word-level diff against v1 with unchanged text collapsed.
This is what makes the loop cheap. Re-reading a revised plan in chat costs as much as reading it the first time, because nothing shows you what changed. Here it costs seconds, and a rewritten approach can't slip past as re-flowed text.
When nothing's left to change, s again and pick an execute hand-off.
The agent starts from the stored version — not a summary it remembers from chat — with every comment still open on it, and works those into the code as it goes.
Approval always names a version:
revise, execute, and show all refuse to default to latest
a plan can gain a version between your review and the command
defaulting is how an agent ends up building something nobody read
What the loop costs
Three minutes on a plan you'd otherwise have skimmed and accepted. What gets built is what you actually decided on.
PLAN → REVIEW → REVISE → EXECUTE → RESUME
If you use Codex
Same workflow, $planx instead of /planx — that's just how each agent spells a skill invocation. See Planning with Codex. Because the plan is a file rather than a conversation, the agent that builds it doesn't have to be the agent that wrote it. That's the next post.
Install
npm install --global @thisisnsh/planx
Needs Node 20.19+. Start a new agent session after installing — one already running loaded its skills at start-up and won't see a skill added underneath it.
MIT, nothing hosted, plans are local files. If this made a plan easier to review, a star helps the next person who is tired of losing plans in a scrollback find it.
reacted with thumbs up emoji reacted with thumbs down emoji reacted with laugh emoji reacted with hooray emoji reacted with confused emoji reacted with heart emoji reacted with rocket emoji reacted with eyes emoji
Uh oh!
There was an error while loading. Please reload this page.
How to review a Claude Code plan before it writes any code
Claude Code can plan before it codes. But what you get back is one long message with an accept button under it. If line 40 is wrong, your only options are to accept a plan you know is wrong, or reject the whole thing and re-explain it in prose.
Here's a workflow that fixes that.
1. Ask for a plan
This loads the PlanX skill, which:
When it's done, it prints one line and stops — no build, no polling:
Exit the agent. The plan is now a file under
~/.planx, so it's still there tomorrow, after the context window has moved on.2. Open the review
This opens a terminal review — not a message in a scrollback:
More: Planning · Reviewing
3. Fold what you already agree with
A 400-line plan read top to bottom is a plan you skim. Press
spaceto fold the section under the cursor, starting with everything you agree with. What's left on screen is what you're actually deciding on.space— fold the section under the cursorh— fold every comment at oncej— jump between commentsg/G— jump to the start / end?— full key listReviewing isn't reading the whole thing again — it's finding the four lines you disagree with.
4. Say exactly what's wrong
Put the cursor on a line, press
v, extend with the arrows, pressf. The comment attaches to those exact lines, not to the plan in general.Three keys, three different acts:
f— a comment on the selected lines. This is wrong, here.n— a note about the whole plan. Use it for something that applies everywhere, not to one passage.e— rewrite the line yourself. The agent reproduces your wording instead of interpreting a comment about it.That last one is worth using more than it looks — half the time you already know the right wording, and typing it is faster than describing it.
More: Feedback and edits
5. Hand it back
Press
s. Every comment, edit, and note goes back together, and PlanX asks what should happen next.On a first run, pick Revise plan in the session that wrote it. PlanX:
Not a fresh agent reading the plan cold.
More: Hand-offs
6. Read the diff, not the whole plan again
The revision comes back as
v2, shown as a word-level diff againstv1with unchanged text collapsed.This is what makes the loop cheap. Re-reading a revised plan in chat costs as much as reading it the first time, because nothing shows you what changed. Here it costs seconds, and a rewritten approach can't slip past as re-flowed text.
More: Versions and diffs
7. Build the version you approved
When nothing's left to change,
sagain and pick an execute hand-off.The agent starts from the stored version — not a summary it remembers from chat — with every comment still open on it, and works those into the code as it goes.
Approval always names a version:
revise,execute, andshowall refuse to default tolatestWhat the loop costs
Three minutes on a plan you'd otherwise have skimmed and accepted. What gets built is what you actually decided on.
PLAN → REVIEW → REVISE → EXECUTE → RESUMEIf you use Codex
Same workflow,
$planxinstead of/planx— that's just how each agent spells a skill invocation. See Planning with Codex. Because the plan is a file rather than a conversation, the agent that builds it doesn't have to be the agent that wrote it. That's the next post.Install
Needs Node 20.19+. Start a new agent session after installing — one already running loaded its skills at start-up and won't see a skill added underneath it.
More: Installation · The skill · Reviewing · CLI reference
MIT, nothing hosted, plans are local files. If this made a plan easier to review, a star helps the next person who is tired of losing plans in a scrollback find it.
All reactions