How to use PlanX with Codex CLI

[thisisnsh]

How to use PlanX with Codex CLI

npm install --global @thisisnsh/planx

PlanX has two pieces:

1. a Codex skill that researches, revises, and executes plans
2. a terminal interface where you read and annotate those plans

The npm command installs both. This walkthrough goes from a clean install to a
reviewed plan being built in Codex.

Install it

npm install --global @thisisnsh/planx

You need Node 20.19 or newer. The installer detects Codex and writes the PlanX
skill alongside your other Codex skills.

Start a new Codex session afterward. Skills are part of the agent's available
workflow context; a session that was already running may not have loaded the
new one. You can check the installed CLI separately:

planx --version

More: Installation

Know which command belongs where

This is the only naming wrinkle:

Where you are	Command	What it does
Inside Codex	$planx <task>	Invokes the PlanX skill
In your shell	planx <plan-id> v1	Opens the terminal review
Inside Codex	/plan <task>	Uses Codex's built-in plan mode instead

Codex uses $ for skills. OpenAI documents that you can type $ to mention a
skill or use /skills to select one.
The unprefixed planx command is the executable installed by npm.

So this goes into Codex:

$planx add request tracing to the worker

And this goes into the shell after Codex hands the plan back:

planx <plan-id> v1

Create the first version

Ask PlanX for a real change you have not started implementing:

$planx add request tracing to the worker

The skill will:

• ask only the setup questions that materially change the plan
• inspect the repository and its existing conventions
• write a structured plan with context, implementation steps, and checks
• capture the plan as v1, associated with the current Codex thread
• stop before editing the code

It ends with:

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

Keep the id and version together. PlanX commands never guess which version you
mean.

More: The skill ·
Planning with Codex

Review it in the terminal

Exit Codex and run the command it printed:

planx <plan-id> v1

Start by folding what you already accept:

• space folds the section under the cursor
• [ and ] jump between section headings
• g and G jump to the top and bottom
• ? opens the complete key list

The goal is not to keep the whole plan expanded and admire it. The goal is to
reduce the screen to the decisions that still need attention.

More: Reviewing

Add feedback without paraphrasing the location

To comment on a passage:

1. move the cursor to its first line
2. press v
3. extend the selection with the arrow keys
4. press f and type the comment

Use n for a note that applies to the whole plan. Use e when you want to
replace a line with exact wording instead of asking Codex to interpret a
correction.

More: Feedback and edits

Revise in Codex

Press s to open the hand-off menu, then choose Revise plan in the session
that wrote it.

PlanX resumes the recorded Codex thread and delivers the complete review. The
repository research is still in that thread; your feedback is added to it
instead of being handed to a fresh agent with no history.

Codex captures the result as v2 and stops again. Reopen it:

planx <plan-id> v2

This time you see a word-level diff against v1, with unchanged text folded.

Press d to switch between the diff and the full document. If anything is
still wrong, leave another comment and repeat. Every round produces one new
version.

More: Versions and diffs

Execute the approved version

Once v2 is right, press s and choose an execute hand-off. The prompt sent to
Codex names the plan and the version:

$planx execute <plan-id> v2

The skill reads the stored plan, keeps its open comments in view while working,
implements the change, runs the checks, and records the Codex thread that built
it. Later, the PlanX picker can resume that build session directly.

More: Hand-offs ·
Resuming a build

If $planx does not appear

Run:

planx add-skills

Then start a new Codex session and type $ or use /skills to look for
planx. If Codex was installed after PlanX, the npm installer could not detect
it on the first pass; add-skills is the repair for that order.

If the CLI itself is missing, reinstall it:

npm install --global @thisisnsh/planx

More: Installation ·
CLI reference

The whole loop

$planx <task>              # inside Codex
planx <plan-id> v1         # in the shell
                           # comment, then press s to revise
planx <plan-id> v2         # review the diff
                           # press s to execute v2

PLAN → REVIEW → REVISE → EXECUTE → RESUME

The point is not to make Codex plan more. It is to give you a place to decide
what Codex will build, and a version number that preserves that decision.

---

PlanX is MIT, nothing is hosted, and every plan stays local. If this got your
first Codex review working, a star helps
the next person find it.