Run workflows

Use this guide after nax is installed and initialized. The runner is designed around repeatable, reviewable flows: each flow declares its steps, prompts, models, inputs, and wait behavior, so a multi-agent process can be rerun without copy-paste coordination.

The bundled review-style flows use the council pattern: independent first passes, cross-review, then a final synthesis that keeps confirmed findings and useful disagreement visible.

List and pick workflows

nax list
nax list --verbose
nax run

The picker includes a single-agent option, bundled workflows, and project-local workflows.

Run common workflow shapes

nax run review
nax run security-audit
nax run performance-audit
nax run documentation

nax run agent codex "Review this branch for regressions"
nax run agent gemini --prompt "Check for broken links"

nax run review --branch fix/auth
nax run review --branch '#123'

nax run review --step cross-review
nax run review --from-step synthesize

Choose a transport

nax run review --transport auto
nax run review --transport github-actions
nax run review --transport netlify-api

Use github-actions for hosted workflow-dispatch runs and team-visible logs. Use netlify-api for local orchestration, resume support, and dashboard event streaming.

Override models

nax run review --models claude,codex
nax run review --step-models review=gemini,codex --step-models synthesize=codex

--models changes all runnable steps. --step-models changes named steps and can be repeated.

Model overrides are useful when you want the full council for ambiguous work, two models for a cheaper confirmation pass, or one model for a targeted follow-up.

Add context

nax run review --context "Focus on the auth callback changes."
nax run review --context-file ./agent-context.md

Extra context is appended to each step prompt after the workflow prompt and before fetched prior-round results.

Resume and retry

nax run --retry <run-id>
nax run review --retry <run-id> --step cross-review

Interrupted netlify-api runs write state under .nax/workflows/<run-id>/workflow.json. Starting nax run again offers to resume unfinished work.

See also

• Command reference for the full public command surface.
• Workflow file reference for step schema.
• Council pattern for the independent-review shape behind multi-model flows.
• Transports for transport trade-offs.