- version: 0.8.3
Drive AI Coding agent through isolated, gated phases
- Usage:
phax [FLAGS] <SUBCOMMAND>
Print human-readable progress and system events
Write structured JSONL trace events to the run folder
Print the phax.usage.kdl CLI spec and exit
Format for --usage output: kdl (default, no external dependency) or json (requires the usage CLI)
Default: kdl
- Usage:
phax validate [--plan <path>]
Validate phax.json and its user overlays without any side effects; pass --plan to also validate a phax-plan.json
Also validate a phax-plan.json at this path
- Usage:
phax unlock [--force] <short-name>
Remove a stale run lock; use --force to remove any lock
Run short name, e.g. usage-cli
Remove the lock regardless of staleness
- Usage:
phax extract-plan <FLAGS>
Extract phax-plan.json from a plan.md by calling Claude Code headlessly
Path to the plan.md file to extract from
Output path for phax-plan.json
Overwrite existing output file (blocked if the run is actively locked)
Claude model to use (overrides phax.json agent.extractPlan.model)
Effort level (low|medium|high, overrides phax.json agent.extractPlan.effort)
Re-extract even if a cached extraction exists (overwrites cache entry)
- Usage:
phax enter <short-name>
Attaches to the kept-open agent session in the final worktree, so you can review the agent's work, ask follow-up questions, or apply manual fixes interactively.
Run short name, e.g. usage-cli
phax enter usage-cli
- Usage:
phax enter-phase <short-name> <phase-id>
Attaches to the agent session for a specific phase worktree. Useful for inspecting intermediate state or debugging a phase that has not yet been committed to main.
Run short name, e.g. usage-cli
Phase identifier, e.g. phase-02
phax enter-phase usage-cli phase-02
- Usage:
phax session-info [--debug] <short-name>
Prints diagnostic information about a run: its current state, active phase, worktree path, and agent session id. Read-only — no side effects.
Run short name, e.g. usage-cli
Dump raw binding and model-resolution metadata
phax session-info usage-cli
phax session-info usage-cli --debug
- Usage:
phax shell <short-name>
Opens an interactive shell in the final worktree. Useful for manually inspecting files, running tests, or executing commands outside the agent session.
Run short name, e.g. usage-cli
phax shell usage-cli
- Usage:
phax path <short-name>
Prints the absolute path to the final worktree on a single line. Useful in scripts: cd $(phax path my-run) or for piping to other tools.
Run short name, e.g. usage-cli
phax path usage-cli
cd $(phax path usage-cli)
- Usage:
phax open <short-name>
Opens the final worktree in the editor configured in phax.json (or the EDITOR environment variable). Equivalent to running your editor with the worktree path as an argument.
Run short name, e.g. usage-cli
phax open usage-cli
- Usage:
phax ls [FLAGS]
Lists runs from the local registry (~/.phax/runs/). With no filter flags, shows all runs. Use status filters to narrow output: --active (created or running), --failed, --review-open (awaiting human review), or --archived. Use --json for machine-readable output.
Show only active runs (created or running)
Show only failed runs
Show only review_open runs
Show only archived runs
Output as JSON
Print run short-names for shell completion
phax ls
phax ls --review-open
phax ls --failed --json
- Usage:
phax archive [--force] <short-name>
Archives a run by removing its worktrees and marking it archived in the registry. Without --force, fails when the final worktree has uncommitted changes.
Side effects: deletes worktrees from the filesystem, updates ~/.phax/runs/.
Run short name, e.g. usage-cli
Archive even if the final worktree has uncommitted changes
phax archive usage-cli
phax archive usage-cli --force
- Usage:
phax run <FLAGS> [short-name]
Extracts a plan from the plan.md given by --plan, creates a run entry in the registry, and executes each phase sequentially in its own Git worktree using the configured AI agent. Each phase runs a gate profile after execution; the final phase worktree stays open for human review.
Extraction results are cached by content hash under ~/.phax/cache/plans/; a repeated run of the same plan.md reuses the cached extraction without calling the LLM again. Use --refresh to force a fresh extraction.
Side effects: creates worktrees, commits files, writes to ~/.phax/runs/.
Run short name, e.g. usage-cli
Path to the plan.md file to extract from
Allow starting when the working tree is dirty
Comma-separated provider priority override (e.g. mistral-vibe,claude-code)
Preview only — extracts the plan but performs no run actions
Security mode override (secure|unsafe|isolated, overrides config default)
Re-extract the plan even if a cached extraction exists
phax run --plan plan.md
phax run my-feature --plan plan.md
phax run --plan plan.md --dry-run
phax run --plan plan.md --refresh
- Usage:
phax review-handoff [--allow-partial] <short-name>
Regenerate review-handoff.md and global file reconciliation for a review_open run
Run short name, e.g. usage-cli
Generate a partial document when some phase artifacts are missing
- Usage:
phax publish-pr <short-name>
Pushes the final worktree branch to the GitHub remote and creates a pull request, or reuses an existing PR for the same branch. Requires a GitHub remote and gh CLI authentication.
Side effects: git push to remote, GitHub API call to create or update a pull request.
Run short name, e.g. usage-cli
phax publish-pr usage-cli
- Usage:
phax review-compliance <short-name>
Runs a non-mutating plan-compliance review by invoking the AI agent with the run's handoff artifacts and the original plan. Does not modify the worktree, registry, or any files.
Side effects: spawns a short-lived AI agent session (network I/O); no filesystem mutations.
Run short name, e.g. usage-cli
phax review-compliance usage-cli
- Usage:
phax review-code [FLAGS] <short-name>
Opens an interactive, pre-prompted code-review session for a review_open run by launching the AI agent in the run's worktree with the code-review prompt. The session is resumable: re-running resumes the existing session, while --new-session starts fresh. The developer takes over the session to investigate, discuss, and apply fixes.
Side effects: writes a code-review prompt file under the worktree's .phax-context/ and a session record under the run directory; spawns a long-lived interactive AI agent session (network I/O).
Run short name, e.g. usage-cli
Start a fresh review session instead of resuming the existing one
Override the model, including on resume (default: review.code.model, else claude-opus-4-8)
Override the effort (low | medium | high), including on resume (default: review.code.effort, else high)
phax review-code usage-cli
- Usage:
phax adjust-plan <FLAGS> <plan>
Opens an interactive, pre-prompted session to help you adjust a plan.md after a landed run has introduced drift. The session establishes which of the plan's declared files, line references, and decisions are invalidated by the landed run's actual changes, asks clarifying questions where needed, proposes concrete edits and waits for your explicit approval, and only then edits and commits the plan — all interactively within the session. The command itself mutates nothing.
Input: the path to the plan.md to adjust and --landed (the run whose actual changes drive the adjustment). The landed run must have a global-file-reconciliation.json (i.e. it must have reached review). Re-invocation without --new-session resumes the same session; --new-session starts a fresh one.
Side effects: spawns a long-lived interactive provider session (network I/O); the session may, after developer approval, edit and commit the plan.md.
Path to the plan.md to adjust
The landed run whose actual changes drive the adjustment
Start a fresh adjustment session instead of resuming
Override the model (default: claude-opus-4-8)
Override the effort (low | medium | high)
phax adjust-plan docs/plans/40-foo.md --landed my-feature
- Usage:
phax init [--force] [--yes]
Creates phax.json and phax.schema.json in the current directory. Use --force to overwrite an existing phax.json. Does not connect to any network or external service.
Overwrite and reconfigure an existing phax.json
Accept detected defaults without prompting
phax init
phax init --force
- Usage:
phax report [--no-gist] [short-name]
Creates a GitHub issue from local run telemetry. By default, uploads the full log as a secret GitHub gist and links it in the issue body. Use --no-gist to inline the log directly.
Side effects: GitHub API calls — creates a GitHub issue and, unless --no-gist is set, a secret gist.
Run short name, e.g. usage-cli
Inline the full log in the issue body instead of creating a secret gist
phax report
phax report usage-cli
phax report usage-cli --no-gist
- Usage:
phax orient [--file <path>] [id]
Pull orientation from the configured orient provider: expand a row by id, or pass --file to get an index for an arbitrary file
Row id to expand
Return an index for an arbitrary file instead of expanding a row id
- Usage:
phax completions <shell>
Generate a shell completion script (zsh, bash, fish, nu, powershell). Requires the usage CLI.
Shell to generate completions for (zsh, bash, fish, nu, powershell)
- Usage:
phax resume [FLAGS] <short-name>
Picks up a run from its next pending phase, re-entering the same execution loop as phax run. Prompts for confirmation before proceeding unless --yes is set.
Side effects: creates worktrees, commits files, writes to ~/.phax/runs/.
Run short name, e.g. usage-cli
Proceed without confirmation
Print human-readable progress and system events
Write structured JSONL trace events to the run folder
Comma-separated provider priority override (e.g. mistral-vibe,claude-code)
phax resume usage-cli
phax resume usage-cli --yes
- Usage:
phax reset-phase [FLAGS] <short-name> [phase-id]
Reset a stuck or failed phase so phax resume re-runs it from scratch
Run short name, e.g. usage-cli
Phase identifier to reset, e.g. phase-02; defaults to the stuck phase
Proceed without confirmation (removes the worktree and branch)
Print human-readable progress and system events
Write structured JSONL trace events to the run folder
- Usage:
phax agent <SUBCOMMAND>
Inspect and manage model routing and provider configuration
- Usage:
phax agent models
Print the routing table and provider priority
- Usage:
phax agent resolve <FLAGS>
Show how a model+effort request resolves to a provider and concrete model
Requested model id (e.g. claude-sonnet-4-6)
Effort/thinking level (none|off|low|medium|high|xhigh|max|ultracode|ultra)
Output the resolution as JSON
- Usage:
phax agent probe
Check which provider executables are available on PATH; never throws on an unavailable provider
- Usage:
phax agent setup <SUBCOMMAND>
Set up provider integrations
- Usage:
phax agent setup mistral-vibe [--dry-run] [--install-model-aliases]
Append PHAX-owned Mistral Vibe model aliases to ~/.vibe/config.toml (append-only, atomic)
Preview what would be appended without writing anything
Actually append the missing aliases and write the backup
- Usage:
phax agent setup providers [FLAGS]
Reconcile ~/.phax/providers.json enabled flags from live executable probes (dry-run by default)
Persist the reconciled config (writes a timestamped backup first)
Also disable providers whose executable is unavailable
Scaffold ~/.phax/model-routing.json from defaults when absent (never overwrites)
- Usage:
phax security [--verbose] [--trace] <SUBCOMMAND>
Security-related commands
Print human-readable progress and system events
Write structured JSONL trace events to the run folder
- Usage:
phax security status [--verbose] [--trace]
Show provider security capabilities and availability
Print human-readable progress and system events
Write structured JSONL trace events to the run folder
- Usage:
phax skills <SUBCOMMAND>
Manage PHAX skills
- Usage:
phax skills install <--target <target>> [--scope <scope>] [skill]
Install bundled PHAX skills into an agent's native skill directory
Skill to install (phax-planning|phax-cli|phax-spec); installs all skills when omitted
Agent target (claude|codex|agent)
Installation scope (project|user)
Default: project
- Usage:
phax schema <SUBCOMMAND>
Manage the local phax.schema.json
- Usage:
phax schema upgrade
Regenerate phax.schema.json from the installed binary's config contract; never modifies phax.json
- Usage:
phax artifact <SUBCOMMAND>
Parent command for inspecting and transitioning the lifecycle status of a spec (docs/specs/) or plan (docs/plans/). Specs carry Draft, Approved, Abandoned, or Completed; plans additionally carry Stale. Transitioning to a terminal status (Abandoned, Completed) moves the file into the artifact's archive/ subdirectory as part of the transition. Illegal transitions and validation failures (missing frontmatter block, unknown status, status/location disagreement) refuse with exit code 12.
phax artifact status docs/plans/45-typescript-7-migration-plan.md
- Usage:
phax artifact status <path>
Reports an artifact's kind (spec or plan), current status, and the legal transitions from that status. Read-only — no side effects.
Path to a spec or plan file under docs/specs/ or docs/plans/
phax artifact status docs/plans/45-typescript-7-migration-plan.md
- Usage:
phax artifact approve <path>
Transitions an artifact to Approved. Legal from Draft (both kinds) and from Stale (plans only); re-approving an already-Approved plan re-records the approval, refreshing its timestamp and baseline. Rewrites the frontmatter status key in place.
Side effects: writes the artifact file and commits the transition's write-set (the artifact file, plus the approval record for plans) in a single commit; refuses with exit code 12 if any write-set path already has uncommitted changes.
Path to a spec or plan file under docs/specs/ or docs/plans/
phax artifact approve docs/plans/45-typescript-7-migration-plan.md
- Usage:
phax artifact stale <path>
Manually marks a plan Stale. Legal from Approved only — Stale has no automatic trigger (that belongs to a future lineage spec). Rewrites the frontmatter status key in place.
Side effects: writes the plan file and commits the write-set in a single commit; refuses with exit code 12 if the plan file already has uncommitted changes.
Path to a spec or plan file under docs/specs/ or docs/plans/
phax artifact stale docs/plans/32-billing-plan.md
- Usage:
phax artifact abandon <path>
Abandons an artifact — a terminal status distinct from Completed, for work dropped without execution. Legal from Draft or Approved (specs) or Draft, Approved, or Stale (plans).
Side effects: moves the file into the artifact's archive/ subdirectory with its frontmatter status key rewritten to Abandoned and commits the move (and, for plans, the approval-record removal) in a single commit; refuses with exit code 12 if any write-set path already has uncommitted changes.
Path to a spec or plan file under docs/specs/ or docs/plans/
phax artifact abandon docs/plans/45-typescript-7-migration-plan.md
- Usage:
phax artifact complete <path>
Completes an artifact — a terminal status for work that ran to completion. Legal from Approved (specs) or Approved or Stale (plans).
Side effects: moves the file into the artifact's archive/ subdirectory with its frontmatter status key rewritten to Completed and commits the move (and, for plans, the approval-record removal) in a single commit; refuses with exit code 12 if any write-set path already has uncommitted changes.
Path to a spec or plan file under docs/specs/ or docs/plans/
phax artifact complete docs/specs/21-artifact-lifecycle-status.md
- Usage:
phax artifact reopen <path>
Reopens a Stale plan back to Draft, for when re-planning is needed before re-approval. Legal from Stale only. Rewrites the frontmatter status key in place.
Side effects: writes the plan file and commits the write-set in a single commit; refuses with exit code 12 if the plan file already has uncommitted changes.
Path to a spec or plan file under docs/specs/ or docs/plans/
phax artifact reopen docs/plans/32-billing-plan.md
- Usage:
phax plans <SUBCOMMAND>
Parent command for reporting on plans: staleness of Approved plans against their recorded approval, and cross-plan file overlap.
phax plans status
phax plans overlap docs/plans/33-a.md docs/plans/35-b.md
- Usage:
phax plans status [--apply] [--json]
Reports every live, Approved plan's staleness against the ground it was approved against: the declared source spec's content, the plan's own content, and the files changed since the recorded baseline intersected with the plan's footprint. Each stale entry names its reasons (spec-changed, ground-changed, self-changed) with evidence; a plan with no approval record — or one whose baseline commit no longer exists — reports missing-record, which renders as stale. This is a report, not a gate: it exits 0 whether or not stale plans exist. Use --apply to flip stale-computed plans Approved -> Stale as an explicit gesture (the flip is never automatic). Use --json for machine-readable output.
Side effects: read-only unless --apply is set, in which case it writes the flipped plans' frontmatter status key.
Flip stale-computed plans Approved -> Stale
Emit the report as JSON instead of a rendered table
phax plans status
phax plans status --apply
phax plans status --json
- Usage:
phax plans overlap [FLAGS] <plan>
Reports which of two or more plans can run in parallel without a merge conflict — predicted from each plan's declared file-sets, or confirmed against a landed run's actual diff.
(Predicted) Without --landed: reads each plan.md's structured form through the content-addressed extraction cache (a cold cache miss extracts once via LLM and caches the result; use --no-extract to fail on a miss instead). Unions each plan's declared phase file-sets into a per-plan footprint, intersects footprints pairwise, and reports the severity-graded conflict matrix, clean pairs, the largest fully-disjoint parallel-safe set, and a greedy wave schedule.
(Confirmed) With --landed : takes a run that has already produced changes and reports which of the given plans need re-adjustment because they touch a file the run actually changed. The landed run's footprint is read from its persisted global-file-reconciliation.json (the real git diff across its phases), giving actual-vs-declared impact with no false negatives.
Caveats: the predicted mode reflects declared file intentions, not what agents will actually touch. Conflicts are file-level, not hunk-level — two plans editing different regions of the same file are flagged even if git would auto-merge them. Regenerated artifacts (phax.usage.kdl, docs/cli/reference.md) are a hard-conflict class.
Side effects: read-only with respect to your plans; may run one LLM extraction per uncached plan.md.
Paths to two or more plan.md files
Emit the overlap result as JSON instead of a report
Fail on a cache miss instead of extracting the plan.md
Report which of the given plans need re-adjustment after this run's actual changes
phax plans overlap docs/plans/33-a.md docs/plans/35-b.md
phax plans overlap --landed my-feature docs/plans/40-other.md