# zap

> zap finds the git worktrees that coding agents (Claude Code, Codex, Cursor, Conductor, T3 Code) and people leave behind, removes the ones whose work is already merged, with backups and undo, and reports what else agents keep on the disk.

zap is a single static Go binary for macOS and Linux (amd64, arm64), MIT licensed. Source: https://github.com/thecloudranger/zap

The latest release is v0.2.3, from 2026-11-13. Release notes: https://raw.githubusercontent.com/thecloudranger/zap/main/CHANGELOG.md. Install: `brew install thecloudranger/tap/zap`, or `go install github.com/thecloudranger/zap/cmd/zap@latest`, or a binary from https://github.com/thecloudranger/zap/releases/latest

zap deletes only when a person confirms. If you are an agent, look first and remove nothing without the user's go-ahead:

- `zap scan --all --json` lists every worktree under the user's scan roots with its status: merged, empty, gone, missing, idle or active.
- `zap explain --json <path>` shows every check and safety gate behind one worktree's status.
- `zap clean --all --dry-run --json` shows what a clean would remove, and what it keeps and why.
- `zap check --json` reports merged or empty worktrees and free disk space; `zap map --json` reports agent worktrees, temp sessions and transcripts.
- Only after the user agrees: `zap clean --all --yes --json` (or without `--all` for the current repository, matching the dry run you showed). Then `zap undo --json` brings the last run back: branches and worktrees, not ignored files such as `node_modules`.

zap removes worktrees only in repositories that contain a `.zap` file, and only when every safety check passes: no uncommitted or hidden changes, no ignored secrets such as `.env`, no process working inside, not locked, protected or recently active. Do not run `zap init`, edit `.zap`, pass `--unlock-stale` or run `zap schedule on` unless the user asks. zap never deletes agent temp sessions or transcripts; do not delete them yourself either.

Every `--json` command prints one envelope: `{schemaVersion, command, status: "ok"|"error", data, warnings, error: {code, message}}`. Exit codes: 0 ok, 1 error, 2 bad usage, 3 `zap check` passed a limit, 4 refused (the one-time disclaimer has not been accepted, or a confirmation is missing; nothing was changed; ask the user to run `zap clean` once in their own terminal), 130 interrupted.

## Docs

- [README](https://raw.githubusercontent.com/thecloudranger/zap/main/README.md): what zap does, install, commands, how it decides, the safety checks, `.zap` settings, the picker keys and what it measures.
- [Agent skill](https://raw.githubusercontent.com/thecloudranger/zap/main/skills/zap/SKILL.md): how an agent should use zap: look with `--json` and `--dry-run`, remove only after the user agrees, and the exit codes.
- [Changelog](https://raw.githubusercontent.com/thecloudranger/zap/main/CHANGELOG.md): every release and what changed.

## Optional

- [Website](https://getzap.dev/): the same story as a page, with real zap output from a demo machine and the launch film.
- [Launch film, 16:9](https://getzap.dev/media/zap-launch-16x9.mp4) and [square](https://getzap.dev/media/zap-launch.mp4): 58 seconds, narrated. It shows agents filling a disk with worktrees, zap scanning a repo, the ten safety checks behind one worktree, a clean that frees 1.2 GB, and `zap undo` restoring the worktrees and branches. Every path in it is from a made-up demo home folder.
- [Security policy](https://raw.githubusercontent.com/thecloudranger/zap/main/SECURITY.md): how to report a bug where zap deletes something it should have kept, privately through GitHub security advisories.
- [Bug reports](https://github.com/thecloudranger/zap/issues/new?template=bug.yml): what happened, the output (`zap explain --json <path>` for a worktree zap kept or removed by mistake), and the zap version and OS.