DeltaSnap

AI agent skill

Install the DeltaSnap skill in desktop and CLI agents so they checkpoint, diff, and recover risky file changes.

The open-source DeltaSnap agent skill teaches an AI tool to put a native APFS safety checkpoint around a risky change round. The agent creates a tagged pre-change snapshot, performs the work, creates a post-change snapshot, and compares the two so unexpected paths are visible.

The skill is a portable SKILL.md, not a background service or a second copy of DeltaSnap. It drives the signed dsnap CLI already installed with the app.

Requirements

  • macOS 15 or later with DeltaSnap 0.7.1 or newer in /Applications;
  • the DeltaSnap helper installed and approved;
  • an active DeltaSnap trial or license for snapshot creation; and
  • an AI tool that can load Agent Skills and run local shell commands.

Verify the local side first:

dsnap version
dsnap list

If the agent runs inside a restricted sandbox, give it permission to execute dsnap and reach the local DeltaSnap helper. A chat-only desktop client without local shell access can read the workflow, but it cannot create checkpoints itself.

Install in Claude Code

Use the plugin marketplace published by the DeltaSnap repository:

/plugin marketplace add scaleninja/deltasnap
/plugin install deltasnap@scaleninja
/reload-plugins

The skill is model-invoked when Claude identifies a risky or broad file change. You can invoke it directly with:

/deltasnap:deltasnap

For a manual installation, copy skills/deltasnap/ from the repository into ~/.claude/skills/deltasnap/ for every project, or .claude/skills/deltasnap/ for one project.

Install in Codex desktop or CLI

The simplest cross-tool method uses GitHub CLI 2.90 or later:

gh skill preview scaleninja/deltasnap deltasnap
gh skill install scaleninja/deltasnap deltasnap --agent codex --scope user

preview lets you inspect the instructions before installation. Restart Codex after installing if the current session does not discover the skill.

DeltaSnap also publishes a Codex plugin manifest. To make it available in the Codex Plugins Directory, add the repository to ~/.agents/plugins/marketplace.json:

{
  "name": "scaleninja",
  "plugins": [
    {
      "name": "deltasnap",
      "source": { "source": "github", "repo": "scaleninja/deltasnap" },
      "policy": { "installation": "AVAILABLE", "authentication": "NONE" },
      "category": "Productivity"
    }
  ]
}

Restart Codex, open the Plugins Directory, and install DeltaSnap. For a manual project-only installation, copy the skill to .codex/skills/deltasnap/.

Install in Cursor, Copilot, Gemini CLI, and other tools

GitHub CLI can place the same skill in the host-specific directory for many desktop and terminal agents:

# Cursor desktop
gh skill install scaleninja/deltasnap deltasnap --agent cursor --scope user

# GitHub Copilot in VS Code
gh skill install scaleninja/deltasnap deltasnap --agent github-copilot --scope user

# Gemini CLI
gh skill install scaleninja/deltasnap deltasnap --agent gemini-cli --scope user

# Windsurf
gh skill install scaleninja/deltasnap deltasnap --agent windsurf --scope user

Use project scope instead when the workflow should travel with one repository:

gh skill install scaleninja/deltasnap deltasnap --agent cursor --scope project

For another skill-aware tool, copy skills/deltasnap/ into the skills directory that tool documents. If it does not implement Agent Skills, place the contents of SKILL.md in the project's AGENTS.md or persistent agent instructions. Review local instructions before trusting any third-party skill.

See the DeltaSnap repository for its current plugin layout and the GitHub CLI skill documentation for supported --agent values.

Ask an agent to use it

A useful first prompt is explicit about both the change and the safety boundary:

Use the DeltaSnap skill for this task. Before changing files, create a safety
checkpoint for the volume containing this workspace. After the change, create
a second checkpoint, diff the two, and report any changed paths outside the
workspace. Do not delete checkpoints that you did not create.

Examples:

  • “Use DeltaSnap, then upgrade every package in this project and verify the blast radius.”
  • “Checkpoint this volume before the migration, run it, and show me every path that changed.”
  • “Use the DeltaSnap skill while reorganizing these photos; keep the final checkpoint.”
  • “Recover Sources/Config.swift from your pre-change checkpoint without rolling back the volume.”

The skill should activate on its own for broad refactors, bulk edits, installs, migrations, and risky commands, but naming it in the prompt removes ambiguity.

What happens during a change round

The skill follows this sequence:

  1. Resolve dsnap, check the helper, and identify the APFS volume containing the workspace.
  2. Create an auto-expiring snapshot with dsnap snapshot --safety.
  3. Attach JSON session metadata with dsnap tag.
  4. Perform the requested file changes.
  5. Create and tag a second safety snapshot.
  6. Run dsnap diff --format=tree between the stable snapshot references.
  7. Report unexpected changes and preserve the pre-change point for recovery.

A simplified manual equivalent is:

SESSION="$(date +%Y%m%d%H%M%S)-$$"
PRE=$(dsnap snapshot --safety data@ai-pre-r1)
dsnap tag "$PRE" "{\"agent\":\"codex\",\"session\":\"$SESSION\",\"round\":1,\"phase\":\"pre\"}"

# Let the agent perform one bounded change round here.

POST=$(dsnap snapshot --safety data@ai-post-r1)
dsnap tag "$POST" "{\"agent\":\"codex\",\"session\":\"$SESSION\",\"round\":1,\"phase\":\"post\"}"
dsnap diff --format=tree "$PRE" "$POST"

Safety snapshots expire after the machine-wide safety retention period (24 hours by default). Use dsnap hold "$POST" only when you deliberately want the final checkpoint to outlive that period.

Recovery

For interactive recovery, open Version Control in DeltaSnap or right-click the damaged item in Finder and choose DeltaSnap → Restore Previous Version….

An agent can recover one file from its own pre-change snapshot by mounting it read-only:

MOUNT=$(dsnap mount "$PRE")
cp -a "$MOUNT/Users/me/project/broken-file.py" ~/project/broken-file.py
dsnap unmount "$PRE"

Prefer restoring a copy and inspecting it before replacement. DeltaSnap deliberately has no whole-volume rollback command.

Safety rules built into the skill

  • It uses --safety so abandoned sessions do not accumulate permanent manual snapshots.
  • It captures the printed snapshot reference instead of relying on a moving HEAD.
  • It never deletes a snapshot it did not create.
  • It never uses destroy --all-snapshots or --force without an explicit user request.
  • It treats a snapshot as local undo, not as a backup.
  • If dsnap is missing or the helper is unavailable, it stops and tells the user instead of silently proceeding without a checkpoint.

Remember that each APFS snapshot is volume-wide. Work spanning two volumes needs one pre/post pair on each, and the diff may include unrelated activity elsewhere on a busy volume.