Installation

Installation

npm install --global @thisisnsh/planx

That is the whole install. It puts the planx binary on your PATH, writes the PlanX skill into detected Claude Code and Codex installations, and seeds the store.

Node 20.19 or newer. The package declares "node": ">=20.19.0" and npm refuses the install below it.

Installing the skill on its own

npx skills add thisisnsh/planx

This installs the PlanX skill without the CLI, and PlanX is only half a tool that way — no store, no versions, no review. It is a valid way in all the same: the first time you run /planx, the skill notices the CLI is missing and offers to install it, then carries on with what you asked for. See The skill.

If you already know you want PlanX, npm install --global @thisisnsh/planx is one step instead of two.

The skill is also listed on Smithery and LobeHub, if you install skills through one of those directories instead.

For another agent, install the skill with the skill manager that agent supports, then add its command with planx defaults. The skill and CLI work there too; automatic session recording and resuming depend on the agent integration.

What postinstall does

npm runs planx add-skills after every install, so the skills on disk are the ones the CLI you just installed ships. Upgrading refreshes them without being asked twice.

It is deliberately narrow:

• it writes only into agent directories that already exist — it will not create ~/.codex on a machine with no Codex;
• it replaces only skill directories carrying PlanX's own marker, so one you edited by hand is left alone;
• it never touches an agent's settings files;
• it never fails the install. A skill that could not be written is reported and the install still succeeds.

Set PLANX_NO_POSTINSTALL=1 to silence it entirely, and run planx add-skills yourself when you want it.

A checkout of PlanX itself running npm install is treated as a dev install and skips the step, so working on the repo does not rewrite your real skills.

planx add-skills

planx add-skills
planx add-skills --agent codex
planx add-skills --agent claude
planx add-skills --local
planx add-skills --no-store

Detects which agents are on this machine, writes a skill into each, and seeds ~/.planx, showing each step as it happens. Idempotent — run it again to pick up an agent you installed since.

Flag	Meaning
--agent NAME	Only this agent. Repeatable.
--local	Write into ./.claude/skills for a repo-local install.
--no-store	Write skills only; leave ~/.planx alone.

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

planx remove-skills

planx remove-skills
planx remove-skills --local
npm uninstall --global @thisisnsh/planx

Removes only the skill directories PlanX wrote — one you edited by hand is kept and reported. Then it asks whether to delete ~/.planx, naming the path and how many plans are in it. A non-interactive run never deletes and never asks.

planx update

planx update

Runs npm install -g @thisisnsh/planx@latest --foreground-scripts and hands the terminal to npm, so its output scrolls and the add-skills its postinstall runs is drawn live at the end. It checks the registry first and does nothing when you are already on the latest. npm's exit code is the command's exit code.

Where things land

Path	What is there
~/.planx/	The store: config.json, index.json, and plans/<id>/
~/.claude/skills/planx/	The Claude Code skill
~/.codex/skills/planx/	The Codex skill
./.claude/skills/planx/	The repo-local skill, with --local

Inside a plan directory: meta.json, versions.json, v<n>.md per version, and feedback/v<n>.json per reviewed version.

Never edit anything under ~/.planx by hand. 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 about what is stored. Every change goes through the CLI, and planx doctor is what repairs the index.

--dir PATH points the CLI at a different store, and PLANX_DIR does the same thing through the environment.