Custom Agents

Custom agents

PlanX launches claude and codex itself. Anything else — a wrapper, a flag set you always want, a different agent entirely — you tell it about once, and it becomes two more rows on the hand-off list.

planx defaults

With no flags, in a terminal, that opens a screen. With a flag it sets the value and prints it.

Flag	Sets
--revise CMD	Your own command for the revise hand-off
--execute CMD	Your own command for the execute hand-off

planx defaults --revise "claude --model opus"
planx defaults --execute "codex --full-auto"
planx defaults --execute ""            # empty clears it

The settings are global — one pair, not one per plan.

What PlanX appends

It takes the command you stored and puts the skill invocation on the end of it as one quoted argument:

claude --model opus "/planx revise guard-clock-a3f9 v3"
codex --full-auto "$planx execute guard-clock-a3f9 v3"

$planx for a command that runs Codex, /planx for everything else, because that is how each agent spells a skill invocation. Getting it wrong is a launch that starts an agent and then says nothing to it.

Two consequences:

• The command must take a trailing prompt. PlanX appends one argument; a command that ignores its last positional will start and sit there.
• The receiving agent needs the PlanX skill installed. Without it the prompt means nothing there. See Installation.

The line is split, not shelled. &&, | and $(…) inside a stored command reach the binary as text rather than being interpreted.

Your rows come first

The two custom rows sit above the ones PlanX builds itself, so 1 picks a command you wrote.

They also answer to less than PlanX's own rows do: they need neither a recorded session, nor a recorded launch line, nor an agent PlanX knows how to start, because a command you wrote is a command PlanX can run. That is why they survive on a version PlanX can start nothing else for.

The custom revise row still waits for something to revise — without a comment, an edit or a note there is no request to send, whichever agent would receive it.

Fixing one in the review

Rewrite a custom row on the hand-off list before pressing enter, and what you typed is stored as the new default — minus the prompt PlanX appended. The next review opens on the command you settled on rather than on the one you have now corrected twice.

A line rewritten past recognition is stored whole, because a guess at which half was yours is worse than keeping all of it. A blank remainder writes nothing: clearing a default is what planx defaults --revise "" is for, and an accidentally emptied line should not silently unset a command.

Worked example: plan in Claude Code, build in Codex

planx defaults --revise "claude"
planx defaults --execute "codex"

Then:

1. In Claude Code, /planx <task>. It researches, captures and stops.
2. Exit, and run planx <plan-id> v1. Read it, comment, edit.
3. Press s. Revise using custom command goes back to Claude Code, which still has the repository research in context. Execute using custom command hands v1 to Codex.
4. Codex runs planx execute <id> v1, gets the plan and your comments, and builds it.
5. Afterwards, ctrl+r on that version in the picker puts you back in the Codex session that wrote the code. See Resuming a build.

Nothing was pasted between the two agents. The plan is a stored file, and the version number is the whole hand-off.