phax

    Managing runs

    List runs

    phax ls                   # all runs
phax ls --active          # created or running
phax ls --failed
phax ls --review-open
phax ls --archived
phax ls --json            # machine-readable

    Archive and prune

    Archive moves a finished run aside and keeps everything; prune deletes it. It moves:

    • ~/.phax/runs/<namespace>.<short-name> → ~/.phax/archive/<namespace>.<short-name>/runs/
    • ~/.phax/worktrees/<namespace>.<short-name>/ → ~/.phax/archive/<namespace>.<short-name>/worktrees/

    Then runs git worktree prune to drop stale admin records. Nothing is destructively deleted — every phase's working state is preserved for later inspection, and the run's name stays held.

    phax archive <short-name>        # any non-running run; unfinished states require --force
phax archive <short-name> --force  # archive an unfinished run, or bypass the dirty-worktree check

    Finished runs (review_open, completed) archive without --force. Unfinished runs (created, failed, interrupted, rate_limited, stopped) are refused unless --force is passed — the refusal message names the state. Running, locked, and already-archived runs are never archivable. The run's stoppedReason and lastError survive archival intact.

    Prune

    phax prune deletes archived runs for real: the archive folder, the worktree metadata in the current repository, the run's local branches (<branch> and <branch>--phase-NN) and, last, the registry entry. That frees the run's name and its disk space. It never touches phax/records/v1, remote branches, remote-tracking refs or pull requests, and it never contacts a remote.

    phax prune --all --dry-run   # preview every archived run of this namespace
phax prune old-idea          # prune one archived run after confirming
phax prune --all --yes       # prune every archived run without asking
    • Unpreserved commits (commits no other local branch, tag or remote-tracking ref keeps) keep a run whole. --force discards them.
    • A branch checked out in a worktree keeps its run, even with --force.
    • A preview always comes first. Then it asks on a TTY, or proceeds with --yes. Without a TTY and without --yes or --dry-run, the command refuses.
    • Only the current namespace's archived runs can be pruned, so run phax prune from the repository that owns them.
    • Surviving remote branches are listed as a warning. A future run with the same name will meet them at publish-pr.