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, agent providers, 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 agent claude "Audit authentication" --model claude-opus-4-8 --effort high


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 provider-only hosted workflow-dispatch runs and team-visible logs. Use netlify-api for model/effort configuration, local orchestration, resume support, and dashboard event streaming. With pinned model or effort settings, auto selects netlify-api; forcing GitHub fails before creating remote work.

Build an instance lineup


nax run review --agents claude,codex
nax run review \
  --agents claude:claude-opus-5:auto \
  --agents claude:claude-opus-4-8:auto
nax run review \
  --agents claude:claude-fable-5:low \
  --agents claude:claude-fable-5:medium \
  --agents claude:claude-fable-5:high
nax run review \
  --agents claude:latest:high \
  --agents gemini:latest:high \
  --agents codex:latest:high
nax run review \
  --agents claude,codex \
  --models claude=claude-opus-4-8 \
  --efforts claude=high \
  --models codex=gpt-5.6-sol \
  --efforts codex=high
nax run review --step-agents review=gemini,codex --step-agents synthesize=codex
nax run review \
  --step-models review:gemini=gemini-3.1-pro-preview \
  --step-efforts review:gemini=medium

The execution unit is an agent instance: one provider, optional model, and optional effort. The stable id is provider:model:effort, with auto for an omitted dimension. Repeating a provider is supported, so the same mechanism handles model bake-offs, effort sweeps, flagship councils, and mixed lineups. Exact duplicate tuples are rejected.

Bare providers remain Auto and omit model and effort. latest and default resolve to the catalog default model at launch and are stored as concrete values for retry and resume. OpenCode is opt-in and is not added to bundled council defaults.

Configuration precedence is step CLI, global CLI, step workflow map, defaults workflow map, then Auto. When a higher scope changes a model without setting effort, inherited effort resets to Auto. agent=auto explicitly clears a pin; Auto is never sent to the SDK.

Known incompatible combinations fail before a run starts. Unknown future IDs are forwarded with a warning. For OpenCode GLM 5.2 and DeepSeek V4 Pro, the displayed Max effort is sent as xhigh.

Pinned or repeated-provider lineups require the Netlify API transport. Each step admits at most four resolved agent instances, and local execution can run all four concurrently. --force does not bypass this limit.

Follow-up steps inherit the surviving lineup from their first input step. Each instance continues its own runner session. A mixed result becomes completed_with_failures and survivors proceed; an all-failed step halts the workflow.

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
nax run review --retry <run-id> --step cross-review \
  --instance claude:claude-opus-5:high

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

⚠️

Use --step carefully when the step expects prior inputs. If you need earlier results, prefer --from-step or run the full flow.