Artifacts

Every nax run writes a durable local record under .nax/. The artifact tree is the handoff surface between workflow steps, the dashboard, follow-up prompts, and later debugging sessions.

For multi-model workflows, artifacts are the evidence trail. They let you inspect the workflow config, prompts, per-model responses, cross-review notes, consensus summaries, generated patches, and token or cost metadata when available.

Artifact layout

- state.json
- - - workflow.json
    - events.jsonl
- blob-refs.jsonl

latest symlinks are created when the filesystem supports them. The most common handoff file is:


.nax/workflows/latest/artifacts/summary.md

Local state and git ignore

The first time nax writes durable artifacts in a project, it also makes sure local artifacts are ignored by Git. If the project .gitignore does not already contain a .nax rule, nax adds:


.nax/

This check is intentionally one-time. After the first check, nax records it in .nax/state.json:


{
  "schemaVersion": 1,
  "generatedBy": {
    "name": "netlify-agent-executor",
    "version": "<installed-version>"
  },
  "version": 1,
  "gitignore": {
    "checkedAt": "<timestamp>",
    "status": "created",
    "path": "/path/to/project/.gitignore"
  }
}

On later runs, nax sees gitignore.checkedAt and does not touch .gitignore again. If you remove .nax/ from .gitignore, nax will respect that choice and will not re-add it unless you delete .nax/state.json or remove the gitignore entry from that file.

nax treats existing .nax, .nax/, /.nax/, .nax/**, and /.nax/** entries as already configured.

Artifact metadata

New JSON artifacts include both a schema version and the package version that generated them:


{
  "schemaVersion": 1,
  "generatedBy": {
    "name": "netlify-agent-executor",
    "version": "<installed-version>"
  }
}

Older artifacts may not have generatedBy. Dashboard and tooling should treat that field as optional and use schemaVersion as the primary compatibility signal.

Handoff paths


nax handoff
nax handoff -c
nax handoff --session <id> --copy
nax handoff --workflow <id> --flow review
nax handoff --runner <id> --agent codex

The dashboard exposes the same idea through Run details and Send to next agent.

⚠️

Do not delete .nax before handing off results. It is the durable local record for workflow summaries, runner summaries, session summaries, event streams, and prompt blob mirrors.

Prompt blob artifacts

When prompts are too large for the safe submission budget, nax mirrors offloaded payloads locally under .nax/workflows/<run-id>/blobs/ and tracks remote refs in .nax/blob-refs.jsonl.

Clean stale refs with:


nax admin clean blobs
nax admin clean blobs --force

Common mistakes

Treating .nax as disposable cache before the run has been handed off.
Looking only at terminal output after a failed synthesis. The saved summaries and prompt blobs often contain the full fan-in context.
Assuming prompt blob cleanup deletes local debug mirrors. Remote blobs are cleaned up, but local copies stay available for inspection.