Project setup

Set up a project

phax init writes phax.json at the root of your repository, with the JSON Schemas your editor uses to check it (phax.schema.json, phax.user.schema.json). In a terminal it asks a few questions, pre-filled from your package.json: the project's name, its gate commands, whether to review and publish runs automatically. Elsewhere it takes the detected defaults.

phax init            # asks, or takes the defaults when there is no terminal
phax init --yes      # takes the defaults
phax init --force    # reconfigures an existing phax.json

A phax.json looks like this:

{
  "$schema": "./phax.schema.json",
  "version": 1,
  "name": "my-project",
  "commands": { "setup": ["pnpm install"] },
  "gateProfiles": {
    "standard": [
      { "command": "pnpm typecheck", "surface": "local", "firing": "every-phase" },
      { "command": "pnpm test", "surface": "local", "firing": "every-phase" },
      { "command": "pnpm lint", "surface": "structural", "firing": "every-phase" },
      { "command": "pnpm build", "surface": "product", "firing": "terminal" }
    ]
  },
  "review": { "compliance": { "enabled": true } },
  "publish": { "auto": true, "remote": "origin", "baseBranch": "main" }
}

name is the namespace of your runs: a run is <name>.<run name>.
commands.setup runs in each phase's fresh worktree before the agent starts; commands.cleanup runs in it once the phase has committed, to free space (node_modules, build output).
gateProfiles holds your checks. Each step has a command, a firing (every-phase, or terminal for the last phase only) and a surface that says what it verifies (local, structural or product). phax records each step's surface and result, and the run's summary lists the surfaces it verified. A step can also return structured findings instead of a log — see Extend phax.
review.compliance and publish run a compliance review and open a pull request when a run reaches review — see Review and land. review.code sets the model for phax review-code, and authoring.spec and authoring.plan the model for headless authoring.
security.profile sets the default security mode (secure unless you say otherwise) — see Providers and security.
agent.maxFixAttempts is how many times a failing gate goes back to the agent (1 by default).
fileReconciliation.mode is report_only (default) or warn, to also log each deviation from the planned files.
records is written by phax records init — see Records.

Layers. phax.json is the team's baseline. Two more files can add to it: ~/.phax/config.json for your machine, and phax.local.json (gitignored) for you in this repository. A scalar takes the most personal value. An allowlist (security.filesystem.allowRead|allowWrite, security.agentCommands, security.mcp.allow) is the union of all layers, so a personal layer can add to the project's security baseline but never remove from it. Gate profiles merge by name.

Check and upgrade.

phax validate                          # check phax.json and its layers, no side effects
phax validate --plan phax-plan.json    # and an extracted plan
phax schema upgrade                    # after upgrading phax: regenerate the editor schemas

Project setup#

#Set up a project

Project setup

Set up a project