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.

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.

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.

/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.

Reviewing

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.

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.