phax

    Debugging and troubleshooting

    Debugging

    Add --verbose to any command to print semantic events (state transitions, adapter calls, gate results) to the terminal:

    phax run --plan plan.md --verbose
phax resume <short-name> --verbose

    Add --trace to also write one JSON line per semantic event to semantic.jsonl in the run folder (~/.phax/runs/<short-name>/):

    phax run --plan plan.md --trace

    Both flags can be combined. See docs/observability.md for the full observability architecture and docs/plan-extraction-model.md for how to configure the model phax run uses for the fallback extraction.

    Observability

    phax emits structured semantic telemetry through the SystemTelemetry port — state transitions, adapter calls, gate results, and artifacts. Telemetry is on by default and recorded to a per-run journal; toggle it globally with "enabled": false in ~/.phax/telemetry.json. Two opt-in flags surface it live:

    FlagEffect
    --verbosePrint semantic events to the terminal
    --traceWrite semantic events as JSONL to semantic.jsonl in the run folder

    See docs/observability.md for architecture details, the snapshot rule, and the adapter-boundary failure contract.

    Troubleshooting

    claude not found — install Claude Code and ensure the binary is on $PATH.

    Lock conflict — another phax process is running, or a previous process died. Run phax unlock <short-name> to clear a stale lock.

    Gate failure loop — increase maxFixAttempts in phax.json, or reduce gate scope. Check ~/.phax/runs/<short-name>/phase-NN/checks-attempt-01.log for details.

    Missing phase-handoff.md sections — the phase transitioned to handoff_failed. Check the phase status file and resume the agent session with phax enter.

    Format conflicts — run pnpm format, do not add lint exceptions. Knip failures — remove the dead code or wire it into an entry point, do not add ignoreDependencies entries casually.