Agent skill and JSON output

Let your agent run zap

skills/zap/SKILL.md tells a coding agent to look first with --json and --dry-run, show you what it found, and delete only after you agree.

For Claude Code:

mkdir -p ~/.claude/skills/zap
curl -fsSL https://raw.githubusercontent.com/thecloudranger/zap/main/skills/zap/SKILL.md \
  -o ~/.claude/skills/zap/SKILL.md

Then ask it something like "which of my worktrees can go?".

The skill tells the agent never to run zap init, --unlock-stale or zap schedule on unless you ask, and never to accept the disclaimer for you. A zap clean from an agent fails with exit code 4 until you've accepted the disclaimer once in your own terminal.

JSON output

scan, explain, clean, check, map, history, undo and roots take --json. Each prints one envelope on stdout:

{
  "schemaVersion": 1,
  "command": "scan",
  "status": "ok",
  "data": { "...": "..." },
  "warnings": []
}

On failure, status is "error" and an error object holds a code and a message. For zap clean --json, each item in data.results has an outcome: zapped, skipped or failed.

zap clean asks for confirmation on a terminal. In a script, pass --yes.

Exit codes

Code	Meaning
0	OK
1	Something failed
2	Wrong flags or arguments
3	zap check: a limit was passed
4	zap refused: the disclaimer isn't accepted, or --yes is missing off a terminal
130	Interrupted