How to review a Codex plan before it writes any code

[thisisnsh]

How to review a Codex plan before it writes any code

npm install --global @thisisnsh/planx

Codex has a built-in /plan command. It is good at the first half of the job:
research the repository, think through the work, and propose an approach before
editing files.

The awkward part comes next. A plan in the conversation is still one long
message. You can accept it, reject it, or describe a correction in another
message, but you cannot comment on line 40, compare the revision with the first
draft, or come back tomorrow and build the exact version you approved.

Here is the same planning loop with a review in the middle.

1. Start with the PlanX skill

In Codex, skills are invoked with $:

$planx add rate limiting to the public API

That is different from /plan. /plan switches Codex into its built-in plan
mode; $planx asks the PlanX skill to produce a stored, reviewable plan. OpenAI
documents both the /plan command
and $ skill invocation.

The skill asks any decisions it needs up front, reads the repo, writes a
structured plan, captures it as v1, and stops before implementation.

When it finishes, it gives you one command:

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

The plan is now under ~/.planx, with the Codex thread that produced it recorded
beside it.

More: Planning ·
Planning with Codex

2. Open the plan outside the chat

planx <plan-id> v1

This opens a terminal review with the plan context at the top, the proposed work
in the middle, and the checks that will prove it at the bottom.

The useful reading keys are deliberately small:

• space — fold the section under the cursor
• [ / ] — move between section titles
• g / G — jump to the start / end
• ? — show every key

Fold the sections you agree with. The text left open is the part you are still
deciding on.

More: Reviewing

3. Comment on the wrong lines

Put the cursor on a line, press v, extend the selection with the arrows, then
press f. Your feedback attaches to those exact lines.

There are three different ways to disagree:

• f — explain what is wrong with the selected lines
• n — leave a note about the whole plan
• e — rewrite a line yourself when you already know the right wording

That distinction matters. “Use the existing limiter in src/http” attached to
the proposed dependency is much harder to misunderstand than “the dependencies
section needs work” sent into the chat.

More: Feedback and edits

4. Send the review back to the same Codex thread

Press s and pick Revise plan in the session that wrote it.

PlanX resumes the Codex thread that did the repository research and sends every
line comment, direct edit, and plan-wide note back together. If Codex was
launched with flags, those flags are replayed and printed before the resumed
session starts.

This is the part copy and paste cannot preserve. A fresh chat can read the plan,
but it does not have the investigation that produced it. The resumed thread has
both.

More: Hand-offs

5. Review the revision as a diff

The next draft is v2. Open it and PlanX shows a word-level diff against v1,
with unchanged runs collapsed.

You no longer have to read the entire plan again to discover whether Codex
changed the five words you objected to or quietly replaced the whole approach.
Press d whenever you want to switch between the diff and the complete plan.

More: Versions and diffs

6. Execute the version you approved

When the plan is right, press s again and choose an execute hand-off. The
invocation always names the reviewed version:

$planx execute <plan-id> v2

Codex reads v2, not latest and not a summary remembered from the
conversation. It also receives the comments still open on that version and
works them into the implementation.

That version number is the approval. If v3 appears after your review, Codex
does not silently build it.

When this is worth the extra step

For a two-file change, the built-in /plan flow is often enough. Use a stored
review when:

• the plan is long enough that you would otherwise skim it
• you agree with most of it but need to challenge a few exact lines
• you expect more than one revision
• the review will be interrupted and resumed later
• another agent may build what Codex planned

The loop is:

PLAN → REVIEW → REVISE → EXECUTE → RESUME

Install

npm install --global @thisisnsh/planx

Needs Node 20.19+. Start a new Codex session after installing so the PlanX skill
is present in the session's skill list.

More: Installation ·
The skill ·
CLI reference

---

MIT, nothing hosted, plans are local files. If this made a Codex plan easier to
review, a star helps the next person find
it.