Planning with Codex

Planning with Codex

npm install --global @thisisnsh/planx

That installs the planx binary and writes the PlanX skill into ~/.codex/skills/planx/ — but only if ~/.codex already exists. PlanX never creates an agent directory on a machine that does not have that agent. Install Codex first, then run planx add-skills if PlanX was already installed.

Start a new Codex session afterwards. A running session does not pick up a skill written underneath it.

The sigil is $, not /

$planx add rate limiting to the public API

Agent	Type
Claude Code	/planx <task>
Codex	$planx <task>

That difference is not cosmetic and it is not something PlanX chose. It is how each agent spells a skill invocation, and it is the single thing you have to remember when you move between them. PlanX uses the right one whenever it composes a command for you — the copy rows in the review hand you $planx when the target is Codex.

Everything after the sigil is identical. The same five branches, the same reference files, the same store.

The loop

1. Plan. $planx <task>. Codex clarifies once, researches the repository, writes the plan and captures it — recording $CODEX_THREAD_ID as the session, which is the Codex equivalent of Claude Code's session id and what lets the review resume this exact thread later. Then it stops and prints:

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

2. Review. Exit Codex and run that command. Fold with space, comment with v then f, rewrite a line with e, read the diff with d. See Reviewing.

3. Hand it back. s, then a hand-off. Revise plan in the session that wrote it resumes that Codex thread with your feedback and its research still loaded; Execute plan in a new session starts a fresh Codex on the exact version you approved. See Hand-offs.

Typing the commands yourself

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

Always with the version — neither branch defaults to latest. See The skill.

Plan in one agent, build in the other

This is the case Codex support exists for. Because the plan is a file with a version number rather than a conversation, the agent that writes it does not have to be the agent that builds it:

• Claude Code plans, you review, Codex builds — or the reverse.
• The hand-off is <plan-id> v<n> and nothing else. The receiving agent needs no context beyond the PlanX skill; it reads the stored version and the comments on it.
• The review's copy rows give you the invocation in the right sigil for the agent you are pasting into.

Set planx defaults if you want your own launch commands offered in the review — any command that takes a trailing prompt works, including agents PlanX does not know how to start on its own. See Custom agents.

If $planx does nothing

Start a new Codex session first. If ~/.codex/skills/planx/ is missing entirely, PlanX was installed before Codex was — run planx add-skills. See Troubleshooting.

Next

• Planning with Claude Code — the same loop, one sigil different.
• Custom agents — planning and building in different agents.
• Resuming a build — ctrl+r back into the thread that built a version.