Codex /plan vs. $planx: when to use each

[thisisnsh]

Codex /plan vs. $planx: when to use each

npm install --global @thisisnsh/planx

Codex now has two planning commands that look close enough to be confusing:

/plan add rate limiting to the public API

and:

$planx add rate limiting to the public API

They are not aliases. /plan is a built-in Codex mode. $planx invokes an
installed skill. They solve different parts of the planning problem.

The short answer

	/plan	$planx
What it is	Built-in Codex plan mode	An installed planning skill plus a terminal reviewer
Best for	Think first, then build in this chat	Review, revise, approve, then build an exact version
What you review	A message in the conversation	A stored file in a terminal UI
Feedback	A follow-up prompt	Comments attached to selected lines
Revisions	Another full plan message	v2 shown as a diff against v1
Later access	Find the conversation again	Open <plan-id> v<n> directly
Cross-agent hand-off	Copy and explain	Hand the approved version to another agent

OpenAI's Codex docs describe /plan as the command that switches a chat into
plan mode. The
same docs describe $ as the way to mention a skill in Codex.

Use /plan when the gate is enough

/plan asks Codex to propose an execution plan before implementation begins.
That is the important behavioral change: exploration and design happen before
the first edit.

For small work, this is usually all you need:

• the whole plan fits on one screen
• there are no decisions you need to debate line by line
• one revision at most is likely
• the same Codex chat will build it immediately

Turn it on, read the proposal, correct anything important, and continue. Adding
an artifact workflow to a six-line plan would be ceremony.

Use $planx when the review is the work

$planx tells the skill to research the task, capture the result as a version,
and stop. It does not proceed directly into implementation.

$planx migrate session storage from Redis to Postgres

The result is not only text in the conversation. It is v1 of a plan stored
under ~/.planx, with the Codex thread that wrote it recorded beside it.

Open the review with:

planx <plan-id> v1

This is useful when:

• a wrong sequencing decision could waste an afternoon
• the plan names migrations, rollout stages, or compatibility boundaries
• several parts are right and two precise passages are wrong
• you want a second review round without re-reading 300 lines
• the plan must survive the current context window or terminal session
• Codex may plan while Claude Code, another Codex thread, or a custom agent builds

More: Why review an agent's plan

Do not stack the two commands

You do not need to enter /plan and then invoke $planx inside it. Both ask an
agent to plan, but only one decides where the result goes.

• /plan keeps the plan in Codex's plan-mode flow
• $planx captures the plan in PlanX's versioned review flow

If you are already in plan mode when you choose PlanX, leave plan mode first,
then run $planx <task>. The PlanX skill needs to finish by writing a stored
version and stopping, rather than passing through plan mode's normal
accept-and-build gate.

More: Plan mode vs. a reviewable plan

The difference shows up on revision two

The first plan looks much the same either way: headings, files, steps, checks.
The advantage of the artifact is easier to see after feedback.

In a conversation, the new plan is another wall of text. To verify a narrow
change, you have to compare both messages yourself.

In PlanX, select lines with v, comment with f, then send the review back.
The next version opens as a word-level diff with unchanged text collapsed.

The cost of asking for one more correction falls from “read the whole thing
again” to “read what changed.” That is why the second and third review rounds
actually happen.

More: Versions and diffs ·
Feedback and edits

The difference shows up again at execution

A conversational approval means “go ahead with the plan we were just talking
about.” A versioned approval means:

$planx execute <plan-id> v2

PlanX deliberately refuses to replace v2 with latest. A later revision may
exist by the time the command runs; that does not make it the revision you read.

The receiving agent can be the same Codex thread, a fresh Codex thread, or a
different coding agent. Because the agreement is a stored version rather than a
conversation, who planned and who builds become separate decisions.

More: Hand-offs ·
Planning with Codex

My rule of thumb

Use /plan until you catch yourself doing one of these:

• writing “in the third section, where you said...”
• opening two long messages to work out what changed
• searching the scrollback for the version you approved
• pasting the plan into another agent and explaining its history

Then use $planx. Plan mode makes Codex think before it edits. PlanX makes the
result something you can decide on.

Install

npm install --global @thisisnsh/planx

Node 20.19+. Start a new Codex session after installation.

---

MIT, nothing hosted, plans stay on your machine. If this distinction saved you
a confusing first run, a star helps other
Codex users find it.