Troubleshooting

Troubleshooting

The skill does not appear

Start a new agent session. A session already running loaded its skills at start-up and does not see one written underneath it. This is the answer roughly every time /planx is not recognised straight after an install.

If a new session still does not have it, check that the agent directory existed when PlanX installed. add-skills writes only into directories that are already there, so an agent installed after PlanX has no skill until you run:

planx add-skills --agent codex

planx add-skills also reports what it wrote and where, one line per step.

planx doctor

planx doctor

Prints which store it is talking to, rebuilds index.json from the plans on disk, and reports anything that does not add up — a plan with no versions recorded, or a version listed in versions.json whose file is missing. It exits non-zero when it found problems.

Rebuilding the index is the repair. The problems it reports are told to you rather than fixed, because deleting a plan is not something a check command should decide.

Never edit ~/.planx by hand

index.json is a cache that planx list and the picker read instead of opening every plan. A file changed behind it leaves the two disagreeing about what is stored, and nothing but planx doctor will put that right.

Every change goes through the CLI. The skills tell agents the same thing.

A scratch store

planx --dir /tmp/planx-smoke list
PLANX_DIR=/tmp/planx-smoke planx list

--dir points every path lookup at a different store, and PLANX_DIR does the same through the environment. Useful for testing a release without touching your real plans.

Machine-readable output

--json works on every read command:

planx list --json
planx revise <plan-id> v3 --json
planx defaults --json

Colour

--no-color disables ANSI colour, and NO_COLOR in the environment is honoured too.

The hint toggle does nothing

Some terminals send nothing at all for ctrl+_. ctrl+/ sends the same byte on most of them and works identically, so try that first.

If neither reaches PlanX, the flag is hints in ~/.planx/config.json. That one file is safe to edit — the caution above is about the plan store, which index.json caches; config.json is nothing's cache:

{ "format_version": 1, "hints": false }

Resume fails: the binary is not on PATH

ctrl+r prints the line it was going to run, under Resume it yourself, and stops. Put the agent back on your PATH and paste the line, or resume the session with the agent's own command — claude --resume <id>, codex resume <id>.

The same fallback applies to a hand-off launch: PlanX names the missing binary and leaves you the command.

Resume is not offered at all

See Resuming a build. In short: no session id was recorded, the agent is not one PlanX can launch, or you are on a plan row with two builds behind it — press → and pick the version.

The plan's directory is gone

PlanX says so and runs the agent in the current directory instead.

planx: missing version

revise, execute and show all require a version. A plan reference with no version means whatever was captured most recently, which is not what a command written against a version you reviewed meant. The error names the newest version of that plan. latest resolves too — it just has to be said.

planx: no plans stored yet

Nothing has been captured into this store. Check you are not pointed at a scratch store with --dir or PLANX_DIR.

Version and help

planx --version
planx --help
planx <command> --help

Still stuck

Ask in Q&A with the command you ran and what came back. If it is a bug, open an issue; if it is something PlanX should do differently, post it in Ideas.