The zap file

A .zap file at the root of a repository opts it in to cleaning and holds its rules. zap init writes one with the defaults. Every key is optional.

# .zap (these are the defaults)
# target = "main"                       # default: origin/HEAD, then main, then master
rules         = ["merged", "empty", "missing"]   # "gone" and "idle" can be added
min_age       = "1d"                    # skip anything active more recently (m, h, d, w)
idle_after    = "30d"                   # when an unmerged worktree counts as idle
delete_branch = true
protect       = ["main", "master"]      # branch globs zap never removes
keep_ignored  = [".env", ".env.*", ".envrc", "*.pem", "*.key", "*.p12", "*.pfx", "*.tfstate"]

Key	What it does
target	The branch merges are measured against. --target on the command line overrides it.
rules	Which statuses zap clean removes. See How zap decides.
min_age	zap keeps a worktree if anything in it changed more recently than this.
idle_after	How long an unmerged worktree must sit untouched before it counts as idle.
delete_branch	Set to false to keep branches and only remove the folders.
protect	Branch name patterns zap never removes, such as "release/*".
keep_ignored	Ignored files that stop a removal. See Safety checks.

Commit .zap so everyone on the repository shares the same rules.

Recipes

Clean up after merged pull requests whose remote branch was deleted:

rules = ["merged", "empty", "missing", "gone"]

Offer worktrees nobody has touched for two weeks in the picker:

rules      = ["merged", "empty", "missing", "idle"]
idle_after = "14d"

Never touch release branches, and keep local config files:

protect      = ["main", "master", "release/*"]
keep_ignored = [".env", ".env.*", ".envrc", "*.pem", "*.key", "*.p12", "*.pfx", "*.tfstate", "config.local.*"]

Remove agent worktrees as soon as they're merged:

min_age = "0m"