Agents

This page is for AI coding agents that need to operate nax non-interactively. nax runs Netlify Agent Runner jobs through Claude, Codex, Gemini, and OpenCode, then records workflow state and artifacts for inspection, handoff, and follow-up runs.

Variables

Use explicit variables in scripts and agent plans:

PROJECT_ROOT=/path/to/repo
GITHUB_REPO=owner/name
NETLIFY_SITE_ID=site-id
BRANCH=main

Run commands from the project root unless a command accepts --project-root directly:

cd "$PROJECT_ROOT"

Prerequisites

nax expects the host environment to have:

• Node 20+.
• netlify authenticated with access to the target site.
• gh authenticated when GitHub Actions setup, GitHub transport, or GitHub comments are needed.
• A pushed branch when using --branch.

Install

Use a global install when the agent will run multiple commands:

npm install -g netlify-agent-executor
nax --help
nax list

Use npx for one-off execution when a global install is not desirable:

npx netlify-agent-executor@latest list

Install agent skills

Install the bundled nax-workflows skill into the local agent harness so future agents know how to operate the project workflows.

nax admin skills install \
  --project-root "$PROJECT_ROOT" \
  --provider codex \
  --skill nax-workflows

Use the provider for the current harness:

nax admin skills install --project-root "$PROJECT_ROOT" --provider claude --skill nax-workflows
nax admin skills install --project-root "$PROJECT_ROOT" --provider cursor --skill nax-workflows
nax admin skills install --project-root "$PROJECT_ROOT" --provider gemini --skill nax-workflows

When maintaining a repo for multiple local agents:

nax admin skills install --project-root "$PROJECT_ROOT" --all-providers --skill nax-workflows
nax admin skills check --project-root "$PROJECT_ROOT" --all-providers --skill nax-workflows
nax admin skills update --project-root "$PROJECT_ROOT" --all-providers --skill nax-workflows

If no provider directory exists and no provider is passed, nax installs into .claude/skills by default.

Initialize non-interactively

Preview first:

nax init \
  --project-root "$PROJECT_ROOT" \
  --repo "$GITHUB_REPO" \
  --site-id "$NETLIFY_SITE_ID" \
  --github-actions \
  --dry

Initialize a repo that already has a Netlify site:

nax init \
  --project-root "$PROJECT_ROOT" \
  --repo "$GITHUB_REPO" \
  --site-id "$NETLIFY_SITE_ID" \
  --github-actions \
  --force

Create and link a new Netlify site by name:

nax init \
  --project-root "$PROJECT_ROOT" \
  --repo "$GITHUB_REPO" \
  --site-name my-netlify-site \
  --create \
  --github-actions \
  --force

If GitHub Actions secrets are managed outside nax, add --skip-secrets:

nax init \
  --project-root "$PROJECT_ROOT" \
  --repo "$GITHUB_REPO" \
  --site-id "$NETLIFY_SITE_ID" \
  --github-actions \
  --skip-secrets \
  --force

Run one-off Agent Runner jobs

Use nax run agent when the task does not need a full multi-step workflow.

cd "$PROJECT_ROOT"
nax run agent codex --prompt "Inspect the current branch for regressions." --transport netlify-api --force

Use another supported agent provider when appropriate:

nax run agent claude --prompt "Propose a minimal fix for the failing tests." --transport netlify-api --force
nax run agent gemini --prompt "Check the docs for broken links and stale setup steps." --transport netlify-api --force

Pin a real model and effort when the task requires it:

nax run agent claude \
  --prompt "Audit the services directory." \
  --model claude-opus-4-8 \
  --effort high \
  --transport netlify-api \
  --force

Add branch and context when the target is not the current default:

nax run agent codex \
  --branch "$BRANCH" \
  --context "Focus on the auth callback and billing webhook changes." \
  --prompt "Review this branch for bugs and missing tests." \
  --transport netlify-api \
  --force

Use a file for longer instructions:

nax run agent codex \
  --context-file ./agent-context.md \
  --prompt "Run the requested investigation and summarize concrete findings." \
  --transport netlify-api \
  --force

Run multi-step workflows

List available bundled and project-local workflows:

cd "$PROJECT_ROOT"
nax list --verbose

Dry-run the workflow shape before creating Agent Runner jobs:

nax run review --dry --force

Run the workflow:

nax run review --transport netlify-api --force

Override the instance lineup. Repeat --agents when one provider should run more than once:

nax run review \
  --agents claude:claude-opus-5:low \
  --agents claude:claude-opus-5:high \
  --agents codex:latest:high \
  --transport netlify-api \
  --force

Each provider:model:effort tuple is one independent instance. Bare providers such as --agents codex,claude remain Auto on the wire. latest and default resolve to the catalog default at launch; retry and resume reuse the recorded concrete model. Exact duplicate tuples fail before mutation.

The legacy --models and --efforts mappings remain available for one unambiguous instance per provider. Use exact --agents specs for model bake-offs, effort sweeps, and mixed repeated-provider lineups. Pinned or repeated-provider lineups require the Netlify API transport.

Common lineup shapes:

# Three models from one provider.
nax run review --agents \
  claude:claude-opus-5:auto,claude:claude-opus-4-8:auto,claude:claude-fable-5:auto \
  --transport netlify-api --force
 
# One model at three efforts.
nax run review --agents \
  claude:claude-opus-5:low,claude:claude-opus-5:medium,claude:claude-opus-5:high \
  --transport netlify-api --force
 
# Bare council; model and effort stay omitted.
nax run review --agents claude,gemini,codex --force
 
# OpenCode uses provider-scoped model IDs; Max maps to xhigh on the wire.
nax run review --agents \
  opencode:z-ai/glm-5.2:max,opencode:moonshotai/kimi-k3:high \
  --transport netlify-api --force

OpenCode model IDs are provider-scoped (for example moonshotai/kimi-k3, z-ai/glm-5.2, deepseek/deepseek-v4-pro) and some expose only High/Max, where Max is sent as xhigh. See the model and effort catalog for every provider’s IDs and efforts, or query context_get for the live list.

Each step accepts at most four resolved agent instances, and local execution can run all four concurrently. --force does not bypass this limit.

Run part of a workflow:

nax run review --step cross-review --transport netlify-api --force
nax run review --from-step synthesize --transport netlify-api --force

Use bundled workflows by id:

nax run security-audit --transport netlify-api --force
nax run documentation --transport netlify-api --force
nax run ideas --transport netlify-api --force
nax run do-next --transport netlify-api --force

Inspect and hand off results

Use handoff to read the latest summary or pass it to another agent run:

nax handoff
nax handoff -c
nax handoff --workflow <workflow-run-id>
nax handoff --runner <runner-id>
nax handoff --session <session-id>

For local Netlify API orchestration, resume or retry interrupted work:

nax run --retry <workflow-run-id>
nax run --retry <workflow-run-id> --step <step-id> \
  --instance claude:claude-opus-5:high
nax admin sync last

Agent operating rules

• Prefer --dry --force before real runs.
• Prefer --transport netlify-api for local orchestration, dashboard events, resume, and immediate handoff.
• Prefer --transport github-actions when the user wants hosted GitHub logs and team-visible automation.
• Include --branch when the user named a branch or PR.
• Include --context or --context-file when the user supplied extra constraints.
• Treat completed_with_failures as a mixed outcome: inspect failed instance artifacts even though survivors continue.
• Expect follow-up steps to inherit surviving instances from their first input; do not add an agents block to a follow-up step.
• Do not assume a final agent recommendation is correct; inspect artifacts and ask for human approval before merging code.

See also

• Get started for human-oriented setup.
• Run workflows for workflow execution flags.
• Workflow file reference for flow schema.
• Council pattern for multi-agent workflow design.