Planning with Claude Code

Planning with Claude Code

npm install --global @thisisnsh/planx

That installs the planx binary and writes the PlanX skill into ~/.claude/skills/planx/. Start a new Claude Code session afterwards — one already running loaded its skills at start-up and will not see a skill written underneath it.

Then the whole loop is three commands, and you type one of them.

1. Plan

/planx add rate limiting to the public API

Claude Code loads the skill and takes the plan branch. What it does next, in order:

Leaves plan mode. The accept/reject gate ends the planning phase, which is where PlanX starts, so the skill exits it with a one-line stub before doing anything else.

Asks what it needs to, once. One batch of questions about scope, approach and the trade-offs that actually decide what gets built — asked before the research, and only where your answer changes the plan.

Researches and writes. It reads the repository, makes the decisions, and writes the plan as markdown: an H1 title, ##/###/#### sections, hard wrapped to 80 characters, context near the top and the checks that prove the work at the end. See Planning for why that shape matters.

Captures it once, recording $CLAUDE_CODE_SESSION_ID so the review can start this same conversation again later.

Stops. It builds nothing. It prints one line and ends its turn:

Plan created. Exit the agent, then run planx <plan-id> v<n>

Nothing polls and nothing blocks. Exit Claude Code.

2. Review

planx <plan-id> v1

The review opens in your terminal. planx on its own opens the picker instead, if you have lost the id.

The keys you need first:

Key	What it does
space	Fold the section under the cursor — start by folding what you agree with
v then f	Select lines, then comment on exactly those lines
n	A note about the whole plan
e	Rewrite a line yourself
d	Show or hide the diff against the previous version
?	Every key

Everything here is in Reviewing and Feedback and edits.

3. Hand it back, or build it

Press s. PlanX submits every comment, every edit and the note together, and asks what happens next. See Hand-offs for all six exits; the two that matter on a first run:

• Revise plan in the session that wrote it. PlanX resumes the exact Claude Code session that planned it — same model, same flags, repository research still in context — and sends it your feedback. It captures v2, and you read the diff rather than the whole plan again.
• Execute plan in a new session. Starts a fresh Claude Code on this exact version. It gets the plan and every comment still open on it, and works them into the code as it builds. Approval refers to v<n>, not to whatever is newest.

An empty review — nothing to change — offers execute only. That is PlanX saying the version is ready.

Typing the commands yourself

You rarely need to; the review composes them. But both branches are ordinary skill invocations:

/planx revise <plan-id> v2
/planx execute <plan-id> v2

Always with the version. Neither branch defaults to latest, because a plan can gain a version between your review and the command running, and defaulting would build something nobody read.

Asking Claude Code about PlanX itself

/planx help how do I comment on a single line?

That takes the help branch: Claude fetches the wiki page that covers it and answers in chat. A task that merely starts with the word help — /planx help me split the auth module — is planned like any other. See Asking for help.

If /planx does nothing

Start a new session. If it still does nothing, see Troubleshooting.

Next

• Planning with Codex — the same loop, one sigil different.
• Custom agents — plan here, build somewhere else.
• Plan mode vs. a reviewable plan.