FAQ

FAQ

Short answers. Each one links to the page that works it out properly.

About PlanX

What is PlanX?

An open-source planning skill and terminal review interface for AI coding agents. It turns an agent's plan into a versioned artifact you can read, annotate, revise, compare, approve and execute.

Why not just ask the agent to plan in chat?

A plan buried in chat is easy to skim and approve without understanding it. PlanX separates planning from execution, gives the plan a review interface, and makes approval refer to an exact version. The goal is not more planning text — it is helping you decide what should be built before an agent starts building it.

How is it different from an agent's own plan mode?

Plan modes help an agent think before it codes, but the plan stays a transient message inside one conversation. PlanX adds the artifact around it: versions, word-level diffs, line comments, direct edits, folding, human approval and cross-agent hand-offs. It also expects you to leave plan mode — the accept/reject gate is where PlanX starts, not where it ends. See Planning.

What is the best way to plan before an AI agent writes code?

Get the plan out of the chat window and into something you can disagree with a line at a time. Whatever tool you use, the properties that matter are the same: the plan survives the session, you can point at a specific line, a revision arrives as a diff rather than another wall of text, and approval refers to one exact version. A plan you approve without reading is worse than no plan. See Why review an agent's plan.

Is PlanX open source?

Yes, MIT-licensed. The CLI is published as @thisisnsh/planx on npm, and the source, contribution guide and security policy are in the repository.

Agents

Does PlanX work with Codex?

Yes. Start a new Codex session and use $planx <task>. See The skill.

Does PlanX work with Claude Code?

Yes. Start a new Claude Code session and use /planx <task>. See The skill.

Why is it $planx in one and /planx in the other?

That is how each agent spells a skill invocation. PlanX uses the right one when it composes a command for you.

Does PlanX work with Claude Code's plan mode?

Yes, and it expects it. Plan mode gates on accept/reject, and accepting is where PlanX starts — so the skill exits plan mode with a one-line stub before it does anything else, then researches, writes and captures. The two are not alternatives. See Plan mode vs. a reviewable plan.

Can I use another agent?

Yes. Any command that accepts a trailing prompt can be a hand-off target, set with planx defaults, provided the receiving agent has the PlanX skill installed. See Custom agents.

Can I plan with one agent and build with another?

Yes — that is the point of storing the plan as a file. Claude Code can research and plan, Codex can build, and the version number is the whole hand-off. See Custom agents.

Can I ask my agent how PlanX works instead of reading this?

Yes. /planx help <question> — $planx help <question> in Codex — has the agent fetch the wiki page that covers it and answer in chat. See Asking for help.

Will /planx help me do X answer instead of planning?

No. help takes the wiki branch only when the rest of the line is a question about PlanX. A task that begins with help is planned like any other, and a line that reads both ways gets a question back. See Asking for help.

/planx does nothing after installing. Why?

Start a new agent session. A session already running does not pick up a skill written underneath it. See Troubleshooting.

I copied the skill and /planx does nothing — what is missing?

The CLI. The skill is the front half of PlanX: without planx on your PATH there is no store, no versions and no review, so the skill has nothing to hand back. Copying SKILL.md from a directory, a gist or npx skills add gets you the skill alone. Run npm install --global @thisisnsh/planx — or just invoke /planx <task> and say yes when it offers to install it for you. The install also replaces the copied skill with the one matching the CLI. See Installation.

Reviewing

Can I review a plan without the agent running?

Yes — that is the normal way. The agent captures the plan, prints one line and ends its turn; nothing polls and nothing blocks. You exit the agent and run planx <plan-id> v<n> in your own time. The plan is a file in ~/.planx, so it is still there tomorrow, and you can capture one without an agent at all: planx capture --stdin --title "..." < plan.md. See Planning.

How do I open a review?

planx for the picker, planx <plan-id> for a plan, planx <plan-id> v<n> for an exact version. See Reviewing.

How do I see every keyboard shortcut?

Press ? in a review. The hint bar along the bottom shows only what works on the row you are on. Every key is also tabulated in Reviewing.

How do I comment on exact lines?

v to start a selection, ↑ ↓ to extend, f to write the comment, enter to save. See Feedback and edits.

How do I add a note about the whole plan?

n. Use line feedback for a passage and the note for something that applies everywhere. See Feedback and edits.

How do I edit a line myself?

e on the line, or on a selection to walk it line by line. An edit says this is the wording, I have decided — the agent reproduces it rather than interpreting it. See Feedback and edits.

How do I delete a note?

Empty it: f, clear the text, enter.

How do I make a long plan readable?

space folds the section, note or unchanged diff run under the cursor, h folds every note at once, j jumps between comments, and g / G reach the ends. See Reviewing.

Can I hide the hint bar?

ctrl+_, on every screen PlanX draws hints on — the review, the picker and planx defaults. Every row goes at once, the bottom border picks up ctrl+_ show hints, and the choice is remembered until you press it again. See the hint bar.

Why does the plan use so many headings?

##, ### and #### are exactly what the review can fold, and the heading is also the label a comment comes back under. A plan divided finely enough folds where you need it and comes back with feedback you can place. See Planning.

What does an empty review mean?

That the version was reviewed and there is nothing to change. PlanX does not create an identical revision for it — that version is ready to build. See Feedback and edits.

Versions

How do I compare two versions?

Open the newer one and PlanX shows the diff first; d toggles it, ← and → move between versions. Changed words are highlighted and unchanged runs collapse. See Versions and diffs.

Can I print a diff without the review?

planx diff <plan-id> v1 v3 --print, with --plain for a raw unified diff or --stat for the summary line. See Versions and diffs.

How do I find an older version?

planx list, or planx and → on the plan. planx <plan-id> v<n> opens one directly. See Versions and diffs.

Why do revise, execute and show refuse to default to the latest?

Because those commands arrive as a line copied out of a review of one particular version, and the plan may have gained another since. Defaulting would silently retarget the newest, which is how an agent ends up building a version nobody read. latest still works — it just has to be said.

Building

How do I send feedback back to the agent?

s, then pick a revise hand-off. PlanX submits the line comments, the edits and the note together, and can resume the session that wrote the plan so the agent revises with its repository research still in context. See Hand-offs.

How do I execute the version I approved?

s, then an execute hand-off. It starts from the stored version rather than a summary remembered from chat, and it records the session that ran it. See Hand-offs.

Do I have to resolve every comment before building?

No. Handing a plan on with its feedback open says build it, with these — the execute payload carries every comment, and the agent works them into the code.

How do I get back into the session that built a plan?

planx, → for the versions, ctrl+r on the green one. PlanX starts that session back up with the same flags, in the plan's own directory, and sends it no prompt — the first thing it hears is whatever you type. See Resuming a build.

Why is ctrl+r missing on some rows?

No session was recorded, the agent is not one PlanX can launch, or the plan row has two builds behind it — press → and pick the version. See Resuming a build.

How do I stop an agent executing a bad plan?

Separate planning from execution. Capture the plan, exit the agent, review it in the terminal, and request revisions until the diff matches your decisions. Execute only the exact version you approved.

Does it help with scope creep?

It makes scope changes visible before code is written. When an agent revises the approach, the next version is a diff rather than a replacement in chat, and you can comment on the changed lines or rewrite them before execution.

Storage

Where are plans stored?

~/.planx, one directory per plan. --dir or PLANX_DIR points at a different store. See Installation.

Can I edit the store by hand?

No. index.json is a cache the list and the picker read instead of opening every plan, so a file changed behind it leaves the two disagreeing. Every change goes through the CLI, and planx doctor is what repairs the index. See Troubleshooting.

How do I delete a plan?

ctrl+d in the picker, which confirms first. There is no trash behind it. See Versions and diffs.

Not answered here

Try /planx help <question> first — it reads the whole wiki, not just this page. If that comes back empty, ask it in Q&A. Questions that keep coming back end up on this page.