projects · varn v0.4.0

Varn.

Local state checkpointing and safe rollback for AI agents and automated tools. Varn captures a known state of your local filesystem, lets you observe what changed, and safely restores a previous state.

Designed for automated coding agents, refactoring scripts, and developers who want to experiment locally without worrying about destructive filesystem changes. Operates 100% offline, coexists with Git, and exposes structured JSON output for autonomous tool loops.

“An automated process changed my local environment. What exactly changed, and can I safely return to the previous state?”

version

v0.4.0 (september 2026)

language

rust 1.85+

storage

sha-256 content-addressed

network

0 calls (100% offline)

platforms

linux, macos, windows

license

mit open source

install·quick start·restore pipeline·cli reference·source

Core Thesis

Varn is not Git.

It does not implement branches, remotes, commits, rebases, merges, or Git-compatible history. Varn complements Git — Git tracks project and source history; Varn protects local state. Coexists cleanly alongside your repositories with zero network calls and automatic gitignore guards.

Installation

linux & macos (auto-detects architecture):

$curl -fsSL https://raw.githubusercontent.com/flawme/varn/master/install.sh | sh

windows powershell:

>iwr -useb https://raw.githubusercontent.com/flawme/varn/master/install.ps1 | iex

rust cargo:

$cargo install --git https://github.com/flawme/varn.git

Quick Start Workflow

[bash]· Local capture, diff, restore, undo

varn init
varn checkpoint "before changes"

# ... local edits occur or an ai agent runs ...
varn diff <checkpoint-id>
varn restore <checkpoint-id>

# unwanted restore? undo in one command:
varn undo

Atomic Restore Pipeline

Varn never modifies files halfway. Every restore operation executes through a deterministic, multi-phase safety sequence with layout-aware writability probes and automatic undo guards.

phase 01plan

Compares the target snapshot with live disk, enumerates changes, and flags conflicts.

phase 02confirm

Requires explicit interactive confirmation or the --yes flag for automated agents.

phase 03execute

Captures a safety checkpoint, then writes contents, links, permissions, and mtimes atomically.

phase 04verify

Re-scans disk to ensure the restored tree matches the snapshot byte-for-byte.

CLI Command Reference

varn init[path] [--gitignore]

Initialize a .varn repository. In Git projects, automatically adds an ignore guard to keep checkpoint objects out of git stages.

varn init
varn init --gitignore

varn checkpoint<description>

Capture the complete filesystem state. Hashes files with SHA-256, deduplicates objects, and records symlinks, hardlinks, permissions, and mtimes.

varn checkpoint "before autonomous agent execution"

varn list

Display all available checkpoints with creation timestamps, commit messages, and entry counts.

varn list

varn diff<checkpoint-id> [checkpoint-id]

Compare current disk against a checkpoint, or compare two historical checkpoints directly without scanning disk.

varn diff a91f
varn diff a91f b72c

varn restore<checkpoint-id> [--yes] [--no-safety]

Restore files to a checkpoint state through a 4-phase atomic pipeline. Automatically creates a safety checkpoint before modifying anything.

varn restore a91f
varn restore a91f --yes

varn undo[--yes] [--no-safety]

Revert the last restore operation. Restores the pre-restore state via its safety checkpoint, and creates a new safety checkpoint so undo can be undone.

varn undo

varn delete<id> [--keep-last N] [--older-than AGE] [--safety-only]

Remove checkpoint references by ID or retention rule. Unreferenced objects can then be reclaimed with gc.

varn delete a91f
varn delete --keep-last 10 --yes

varn gc[--dry-run]

Garbage-collect unreferenced content-addressed objects from .varn/store to reclaim disk space.

varn gc
varn gc --dry-run

varn --json<command>

Emit structured machine-readable JSON for automated AI agents and tool scripts.

varn --json checkpoint "auto-save"
varn --json restore a91f --yes

← return to index