#phax

phax is a deterministic orchestrator for AI coding agents: you give it a plan, and it executes that plan as a sequence of isolated, gated phases. The orchestration itself is plain code — phase sequencing, gates, retries, and state transitions are all deterministic — so the only non-deterministic part is the agent working inside each phase.

Because every phase declares the files it expects to create or edit, phax makes each run reviewable: it reconciles the plan against what actually changed and surfaces every deviation — planned-but-not-done, done-but-not-planned, deleted, renamed — which the agent must justify in its handoff. Instead of landing on a pull request full of touched files with no idea what was intended, you get a review that's already framed, phase by phase and across the whole run.

Each phase runs in its own Git worktree, must pass its gates before the next one starts, and has a same-session fix loop for repairing gate failures; the final phase is kept open for human review. The agent itself is interchangeable — Claude Code, Mistral Vibe, or OpenAI Codex — selected by the model-routing layer, with Claude Code as the default and terminal fallback.

#Quickstart

#1. install the CLI
npm install -g @lbdremy/phax

# 1.1 Install the phax skills (phax-planning + phax-cli) into your agent
phax skills install --target claude
# 1.2 Install phax CLI auto completions (optional - you need usage CLI to be installed first)
brew install usage
echo 'source <(phax completions zsh)' >> ~/.zshrc

# 2. Have any coding agent draft the plan (here: Claude Code). Point it at the
#    phax-planning skill so the plan.md it writes matches the format phax expects:
claude -p "Write plan.md for specs/<your spec> using the phax-planning skill."

# 3. extract the plan + run every gated phase
phax run --plan plan.md
# 4. review the agent's work in a pre-prompted session (optional)
phax review-code <short-name>
# 5. push the final branch and open the PR
phax publish-pr <short-name>