autosnap is a local Git checkpointing CLI for preserving known-good worktree
states while you work. It is a safety net between intentional Git commits, not a
replacement for normal commits.
By default, autosnap stores passing checkpoints as local Git refs under
refs/autosnapshots/. It does not commit to your active branch, does not push,
and does not overwrite your work during normal daemon operation.
Run autosnap from inside a Git worktree:
autosnap config initEdit .autosnap.toml and set the check command for your project. For example:
check = "make test"
idle_seconds = 60
snapshot_mode = "both"
commit_mode = "checkpoint"
commit_merge_commits = false
msg_source_cmd = ""
msg_body_source_cmd = ""
note_command = ""
note_ref = ""
post_checkpoint_command = ""msg_source_cmd can return a complete commit message. msg_body_source_cmd
can return extra body text. Autosnap appends that text after one blank line.
Both commands receive the checkpoint context variables.
Use commit_merge_commits = true or --commit-merge-commits to let autosnap
run checks and create checkpoints or direct/sync commits during an active Git
merge. It is disabled by default.
Show the installed version with:
autosnap --versionStart the daemon:
autosnap start
autosnap statusTo start autosnap automatically in this worktree and linked worktrees, install the managed Git hooks:
autosnap hooks install
autosnap hooks statusThe post-checkout hook runs after a new worktree has been populated, when its
tracked .autosnap.toml is available. autosnap ensure-running provides the
same idempotent startup behavior for scripts and editor integrations.
After editing .autosnap.toml, restart the daemon:
autosnap restartrestart requires a running daemon. It reloads .autosnap.toml while preserving
configuration flags supplied to the original autosnap start. To change those
flags, run autosnap stop and then a new autosnap start command. Detailed
restart progress is appended to the daemon log and is visible with
autosnap logs.
See docs/quick-start.md for the full first-run flow.
On Debian-based Linux amd64 or arm64 systems, install the latest released Debian package:
curl -fsSL https://raw.githubusercontent.com/mlahr/autosnap/main/install.sh | bashThe installer downloads the latest GitHub Release .deb, verifies it against
the release checksums.txt, and installs it with apt-get.
Install from source:
make installPackaged Linux installs include manual pages and Markdown documentation:
man autosnap
autosnap docsRepository documentation:
This repository includes an autosnap forensics agent skill at docs/skills/autosnap-forensics/SKILL.md. The skill helps agents use existing autosnap checkpoints to find when a bug, regression, unwanted behavior, or bad implementation decision was introduced during a long-running coding session.
To install it for a local Codex-compatible skill loader:
mkdir -p ~/.codex/skills/autosnap-forensics
cp docs/skills/autosnap-forensics/SKILL.md ~/.codex/skills/autosnap-forensics/SKILL.mdRequirements:
- Go 1.22+
- Git in
PATH
Build:
make buildInstall source-built documentation:
make docs
sudo make install-docsBy default, source docs install under /usr/local/share/man/man1/ and
/usr/local/share/doc/autosnap/. Override PREFIX, MANDIR, DOCDIR, or
DESTDIR when packaging or installing somewhere else.
Run tests:
make test
make test-integration
make test-allRegenerate documentation:
make docsReleases are built by GitHub Actions with GoReleaser on version tags:
git tag v0.1.0
git push origin v0.1.0The release workflow builds Linux tarballs and .deb packages for amd64 and
arm64.